Re-enroll

Estimated reading: 7 minutes 68 views

A re-enrollment refers to when a user has already been registered in the system but attempts to enroll again. There could be various reasons for a user to do so, they could've changed devices, uninstalled and reinstalled the application, etc.

There are two ways to initiate a er-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:

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

Enrollment Step 1 - Get Access Token

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"
}

Re-enrollment Step 2 - Initiate An Enrollment

Please note that re-enrollments are triggered by first starting an enrollment and having the value for userExistsAlready return as true.

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": true,
    "requiredChecks": [
        "deviceSecurity"
    ]
}

The part of the response which separates this transaction from an enrollment is the response above including that the userExistsAlready returning a value of true. This indicates that the transaction is a re-enrollment.

We should also note that the requiredChecks could include more than the deviceSecurity check but for this example it's the only one we'll include.

Re-enrollment Step 3 - 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"
}

Re-enrollment Step 4 - Complete Re-enrollment

The re-enrollment process allows a user to either replace an existing device or add current device to the list of registered device.

To do this, we make a final call where we include an int of 0 or 1 where 0 is replace and 1 is add.

POST /onboarding/reEnrollment/completeReEnroll
Authorization: 'Bearer AccessToken'
apikey: 'apikey'

{
      "reEnrollmentToken": reEnrollmentToken, //enrollmentToken
      "deviceId": deviceID,
      "pushId": fcmToken,
      "addOrUpdate": addOrUpdate,
      "publicKey": publicKey
 }

Re-enroll

Initiate enrollment from client

Base URL

Enrollment Step 1 - Get Access Token

Response for openid-connect

Re-enrollment Step 2 - Initiate An Enrollment

Response for openid-connect

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

Response for CheckDevice

Re-enrollment Step 4 - Complete Re-enrollment

CONTENTS