Device Security

Enroll

Estimated reading: 6 minutes 203 views

There are two ways to initiate an enrollment through AwareID using Device Security:

  • QR code
    • a QR code is generated using a secondary application which is then scanned to receive
  • Initiated via client
    • initiating the enrollment process via the client application entails making api calls yielding the information that would be present in QR code method and then continuing the enrollment process as normal from there.

On the enrollment is initiated then both methods follow the same steps.

Initiate enrollment from client

Base URL

www.awareid.aware-apis.com

To perform a successful enroll using the Device Security SDK and AwareID we need to follow 4 simple steps.

These steps include:

  1. Retrieve an access token. This token allows communication between the client application and the AwareID servers.
  2. Initiate an enrollment.
  3. Add device
  4. Check device security

Enrollment Step 1 - Get Access Token

  1. Our first step is to retrieve an “access_token”. This token will be used in our next api call to retrieve an enrollment token to proceed with enrollment.

POST /auth/realms/{{customer_name}}-consumers/protocol/openid-connect/token
Content-Type: 'application/x-www-form-urlencoded',

"client_id": client_id
"client_secret": client_secret
"scope": openid
"grant_type" : client_credentials

💡 This is the only call whose content type of this call is “application/x-www-form-urlencoded”

Response for openid-connect

STATUS CODE 200
{
    "access_token": {{ACCESS_TOKEN}},
    "expires_in": {{TIME_IN_SECONDS}},
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "id_token": {{JWT_TOKEN}},
    "not-before-policy": 0,
    "scope": "openid"
}

Enrollment Step 2 - Initiate An Enrollment

  1. With the method type we start onboarding with accessToken, sessionToken, apikey
POST /onboarding/enrollment/enroll
Authorization: 'Bearer AccessToken'
apikey: 'apikey'

{    
		"username":  "username",
		"firstName": "first name", //optional
		"lastName": "last name" //optional 
		"email": "user email", 
		"phoneNumber": "user phonenumber"
}

Response for openid-connect

STATUS CODE 200
{
    "enrollmentToken": "enrollmentToken",
    "userExistsAlready": false,
    "requiredChecks": [
        "addDevice",
        "deviceSecurity"
    ]
}

Enrollment Step 3 - Add device

The device ID is checked when performing an authentication to confirm the device enrolled is the same as the device attempting.

💡 This device ID can be retrieved using the following code:Settings.Secure.getString(getContentResolver(), Settings.Secure.ANDROID_ID);

POST /onboarding/enrollment/adddevice
Authorization: 'Bearer AccessToken'
apikey: 'apikey'

{
    "enrollmentToken": "enrollmentToken",
    "deviceId": "deviceID"
}

Response for add device

STATUS CODE 200
{
    "enrollmentStatus": 1,
    "registrationCode": ""
}

From here the response will include a registration code and enrollment status.

There are 3 enrollment statuses:

  • 0 = Enrollment Failed
  • 1 = Enrollment Pending
  • 2 = Enrollment Complete

Enrollment Step 4 - Add device security app session code and check if device passes the security requirements for enrollment.

The device security package will run its checks on the device and send the results securely to our servers. This prevents client side tampering with the results.

To access the results of the device security checks, after it has completed its run it will return a session code. This session code is then sent to AwareID to get the session data and report on the security information gathered from the device.

POST /onboarding/enrollment/deviceProfile/checkDevice
Authorization: 'Bearer AccessToken'
apikey: 'apikey'

{
      "enrollmentToken": enrollmentToken,
      "apSessionId": sessionID,
    };

Response for CheckDevice

{
  "errorCode": 0,
  "errorMsg": "",
  "responseDetail": {
    "errorCode": "",
    "errorDescription": "",
    "transaction_id": "7e524fec-263a-4042-9a21-af9e4ef877fa",
    "userAttributes": [
      {
        "attributeType": "APSessionID",
        "dateCreated": "06/03/2024 13:29:10",
        "values": { "apSessionId": "37080a9ef83a4fcd83672a27dfc04fa8" }
      }
    ],
    "acquiredAttributes": [
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "SmartIDBrowserstringPersonaAgeMonths",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "smartIDBrowserStringPersonaAge": "0" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "TrueIPConnectionType",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "trueIPConnectionType": "tx" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "TrueIPCity",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "trueIPCity": "brookline" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "BiometricReasonCode",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "biometricReasonCode": "Not Found" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "BiometricAssessmentScore",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "biometricAssessmentScore": "174.51" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "BiometricAnomalyScore",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "biometricAnomalyScore": "Not Found" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "TMXScore",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "tmxScore": "0" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "TrueIPGeoCountry",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "trueIPGeoCountry": "US" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "TrueIPLineSpeed",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "trueIPLineSpeed": "high" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "DigitalID",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "digitalID": "89ecdf561a3b4639a0d1b569f3395b26" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "TrueIP",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "trueIP": "38.140.59.226" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "SocialEngineeringScore",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "socialEngineeringScore": "Not Found" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "Platform",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "platform": "agent_mobile" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "BiometricFraudScore",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "biometricFraudScore": "500.00" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "HTMLLocationAccuracy",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "htmlLocationAccuracy": "Not Found" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "ExactIDIPPersonaAgeMonths",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "exactIDIPPersonaAge": "0" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "HTMLLocationLongitude",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "htmlLocationLongitude": "Not Found" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "FuzzyDeviceID",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "fuzzyDeviceID": "81b4da7a6a23441d8ca6eda259407ad8" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "OperatingSystem",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "operatingSystem": "iOS" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "OperatingSystemVersion",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "operatingSystemVersion": "17.4.1" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "BrowserSpoofReason",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "browserSpoofReason": "Not Found" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "TrueIPLatitude",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "trueIPLatitude": "42.34334" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "OperatingSystemAnomaly",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "operatingSystemAnomaly": "Not Found" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "HTMLLocationLatitude",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "htmlLocationLatitude": "Not Found" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "HoneypotFingerprintMatch",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "honeypotFingerprintMatch": "Not Found" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "ScreenResolution",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "screenResolution": "1792x828" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "BiometricBotScore",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "biometricBotScore": "500.00" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "TrueIPLongitude",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "trueIPLongitude": "-71.12276" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "NEATPersonaAgeMonths",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "NEATPersonaAge": "0" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "DigitalIDConfidence",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "digitalIDConfidence": "7107" }
      },
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "attributeType": "FuzzyDeviceIDConfidence",
        "dateCreated": "06/03/2024 13:29:11",
        "values": { "fuzzyDeviceIDConfidence": "100.00" }
      }
    ],
    "userAssertionList": [
      {
        "provider": "Threatmetrix",
        "serviceOffering": "Threatmetrix Session Query Low Location Accuracy",
        "dateAsserted": "06/03/2024 13:29:11",
        "assertions": {
          "blacklist.ofacIP": "pass",
          "blacklist.device": "pass",
          "test.gte3Credential1d": "pass",
          "detect.browserAnomaly": "pass",
          "test.gte5Credential1d": "pass",
          "test.lte3ProxyToday": "pass",
          "test.trustedDevice6mo": "fail",
          "test.trustedDevice": "fail",
          "test.lte3CredentialsDevice7d": "pass",
          "detect.possibleVPNOrTunnel": "pass",
          "test.gte5Device1d": "pass",
          "link.timeZone_TrueGeo": "pass",
          "test.gte5CredentialDevice1d": "pass",
          "test.credentialLTE500mi1hr": "pass",
          "detect.vpn": "pass",
          "test.trueIPLTE500miInputIP": "pass",
          "test.exactIDAgeGTE7d": "pass",
          "detect.proxyAnonymous": "pass",
          "test.apSessionIDNotReplay": "pass",
          "detect.jailbreak": "pass",
          "blacklist.ip": "pass",
          "test.expectedLanguage": "pass",
          "link.proxyOrg_TrueOrg": "pass",
          "detect.malware": "pass",
          "detect.torExitNode90d": "pass",
          "test.gte10Credential1d": "pass",
          "detect.mobileTethering": "pass",
          "test.trustedDevice28days": "fail",
          "test.gte20Credential1d": "pass",
          "detect.aggregator": "pass",
          "test.smartIDAgeGTE7d": "pass",
          "detect.unusualActivity": "pass",
          "detect.proxyOpenTransparent": "pass",
          "detect.proxyHidden": "pass",
          "link.proxyISP_TrueISP": "pass",
          "detect.tor": "pass",
          "detect.torNode": "pass",
          "detect.knownVPNISP": "pass",
          "link.proxyGeo_TrueGeo": "pass",
          "test.gte2Credential1d": "pass"
        }
      }
    ],
    "mbun": "60e7a31b-c207-4e93-b50d-761509768dd9",
    "forwardApiKey": "",
    "policyObligation": false,
    "policyDecision": "approve"
  },
  "enrollmentStatus": 2,
  "registrationCode": "864d70e1-eaf3-4dbe-8b8b-920169889217"
}
CONTENTS

Powered By Aware Inc