Skip to main content

Risk-based authentication

Use these examples to send the inputs used by Authentication API resource rules, including the client IP address, machine authentication data, transaction details, and requested Authentication Context Reference (ACR) values.

Prerequisites​

Before you use these examples, configure the following:

  • An Authentication API application with Source of Client IP Address for Resource Rule Risk Factors and Audits set to Provided in the API. For other integration patterns, see Choose the client IP address source.
  • A resource rule that includes the required risk factors, such as Geolocation, Location History, Travel Velocity, Machine Authentication, Transaction, or External. See the Authentication API resource rule example.
  • Risk-based authentication settings for location history and travel velocity. See Modify risk-based authenticator general settings.
  • For Machine Authentication, a registered machine and its current nonce values. If a device fingerprint is required, collect it with the Entrust Device Fingerprint SDK.

The end-to-end flow below sends the client IP address, machine data, the knowledge ACR, and RBA transaction details in each request. Remove requestAcrs or transactionDetails when the resource rule does not use those inputs. The example assumes that the resource rule maps low risk to password authentication and elevated risk to password plus a second factor. Your response values depend on your resource rule, authentication flows, user authenticators, and RBA history.

Use inputs evaluated by IDaaS​

Date and Time does not require a request field. IDaaS evaluates its current time in the time zone configured in the risk factor. A Group access filter also does not require a request field because IDaaS uses the identified user's group memberships. For example, this request contains all the data required when a matching resource rule uses only the Date and Time risk factor and a Group access filter:

{
  "applicationId": "7593dfb5-dd90-49b2-9dd8-b69b28d36f27",
  "userId": "jsmith"
}

Add an ACR access filter input​

When a resource rule uses an ACR access filter, send its configured ACR value in requestAcrs. For example, this request can select a rule configured for the knowledge ACR:

{
  "applicationId": "7593dfb5-dd90-49b2-9dd8-b69b28d36f27",
  "userId": "jsmith",
  "requestAcrs": "knowledge"
}

Separate multiple requested ACR values with spaces. Include the same requestAcrs value in the user query, challenge, and challenge completion requests.

Add Transaction and External risk inputs​

When a resource rule uses a Transaction risk factor, send the details referenced by its transaction rules in transactionDetails. An external risk engine can also consume these details, in addition to IDaaS account and user data and the client IP address. For example:

{
  "applicationId": "7593dfb5-dd90-49b2-9dd8-b69b28d36f27",
  "userId": "jsmith",
  "clientIp": "<end-user-public-ipv4-address>",
  "transactionDetails": [
    {
      "detail": "Amount",
      "value": "10001",
      "usage": ["RBA"]
    },
    {
      "detail": "Purpose",
      "value": "Transfer",
      "usage": ["RBA"]
    }
  ]
}

The detail names must match the configured transaction rules or external risk engine requirements. Include the same RBA transaction details in the user query, challenge, and challenge completion requests. An External risk factor is separate from the EXTERNAL authenticator.

Query the user's authenticators​

Send the end user's IP address, current machine data, requested ACR, and RBA transaction details when you query the user's authenticators:

POST https://customer.region.trustedauth.com/api/web/v2/authentication/users
Content-Type: application/json
{
  "applicationId": "7593dfb5-dd90-49b2-9dd8-b69b28d36f27",
  "userId": "jsmith",
  "clientIp": "<end-user-public-ipv4-address>",
  "machineAuthenticator": {
    "machineNonce": "ZOjC2Kyhw9GJKnfl+p9/1A==",
    "sequenceNonce": "ns2xIgb40uXJnxZYQ6DAqA==",
    "fingerprint": "{\"platform\":\"web\",\"version\":\"2.0.0\",\"attributes\":{\"osName\":\"Mac OS\"}}"
  },
  "requestAcrs": "knowledge",
  "transactionDetails": [
    {
      "detail": "Amount",
      "value": "10001",
      "usage": ["RBA"]
    },
    {
      "detail": "Purpose",
      "value": "Transfer",
      "usage": ["RBA"]
    }
  ]
}

Replace <end-user-public-ipv4-address> with the end user's public IPv4 address so IDaaS can resolve its location. Omit fingerprint when the tenant does not require device fingerprinting.

For a recognized machine and location, the response can identify an authenticator allowed by the low-risk authentication flow. It can also return an updated sequence nonce. The following example shows only the response fields relevant to this flow:

{
  "authenticationTypes": ["PASSWORD"],
  "availableSecondFactor": null,
  "userMachineSettings": {
    "machineAuthenticatorEnabled": true,
    "deviceFingerprintRequired": true,
    "attributeExclusions": []
  },
  "machineAuthenticator": {
    "machineNonce": "ZOjC2Kyhw9GJKnfl+p9/1A==",
    "sequenceNonce": "Qn3zK8mY2pL5vR7sT9wX1A==",
    "fingerprint": null
  }
}

Replace the stored nonce values with all nonce values returned in machineAuthenticator before making the next request. If the request has elevated risk, the response can instead contain an authentication type such as PASSWORD_AND_SECONDFACTOR. The response does not include the calculated risk level.

If the matching resource rule also requires the Device Certificate context, the response contains deviceCertAuthDesired: true:

{
  "authenticationTypes": ["PASSWORD"],
  "deviceCertAuthDesired": true
}

This field instructs the application to continue its supported Device Verification integration. It is not satisfied by machineAuthenticator. See Device Verification outcomes.

Request an authentication challenge​

Select an authenticator returned by the previous request. Include the same client IP address, requested ACR, transaction details, and the latest machine nonce values:

POST https://customer.region.trustedauth.com/api/web/v2/authentication/users/authenticate/PASSWORD
Content-Type: application/json
{
  "applicationId": "7593dfb5-dd90-49b2-9dd8-b69b28d36f27",
  "userId": "jsmith",
  "clientIp": "<end-user-public-ipv4-address>",
  "machineAuthenticator": {
    "machineNonce": "ZOjC2Kyhw9GJKnfl+p9/1A==",
    "sequenceNonce": "Qn3zK8mY2pL5vR7sT9wX1A==",
    "fingerprint": "{\"platform\":\"web\",\"version\":\"2.0.0\",\"attributes\":{\"osName\":\"Mac OS\"}}"
  },
  "requestAcrs": "knowledge",
  "transactionDetails": [
    {
      "detail": "Amount",
      "value": "10001",
      "usage": ["RBA"]
    },
    {
      "detail": "Purpose",
      "value": "Transfer",
      "usage": ["RBA"]
    }
  ]
}

The response contains a token for the challenge. It can also contain updated nonce values. The following partial response shows the machine data only:

{
  "machineAuthenticator": {
    "machineNonce": "ZOjC2Kyhw9GJKnfl+p9/1A==",
    "sequenceNonce": "aB4dE7gH0jK3mN6qR9tV2w==",
    "fingerprint": null
  }
}

Replace the stored nonce values with the returned values before completing the challenge.

Complete the authentication challenge​

Send the challenge response with the same client IP address, requested ACR, transaction details, and the latest machine data. Use the token returned by the challenge request in the Authorization header:

POST https://customer.region.trustedauth.com/api/web/v1/authentication/users/authenticate/PASSWORD/complete
Authorization: Bearer <token>
Content-Type: application/json
{
  "applicationId": "7593dfb5-dd90-49b2-9dd8-b69b28d36f27",
  "response": "user-password",
  "clientIp": "<end-user-public-ipv4-address>",
  "machineAuthenticator": {
    "machineNonce": "ZOjC2Kyhw9GJKnfl+p9/1A==",
    "sequenceNonce": "aB4dE7gH0jK3mN6qR9tV2w==",
    "fingerprint": "{\"platform\":\"web\",\"version\":\"2.0.0\",\"attributes\":{\"osName\":\"Mac OS\"}}"
  },
  "requestAcrs": "knowledge",
  "transactionDetails": [
    {
      "detail": "Amount",
      "value": "10001",
      "usage": ["RBA"]
    },
    {
      "detail": "Purpose",
      "value": "Transfer",
      "usage": ["RBA"]
    }
  ]
}

When authentication succeeds, the response sets authenticationCompleted to true. Store any returned machine and sequence nonces for the next authentication flow.

Register a new machine​

If the user is registering the current machine, include machineAuthenticatorRegistration when completing a successful authentication challenge:

{
  "applicationId": "7593dfb5-dd90-49b2-9dd8-b69b28d36f27",
  "response": "user-password",
  "clientIp": "<end-user-public-ipv4-address>",
  "machineAuthenticatorRegistration": {
    "label": "Work laptop",
    "fingerprint": "{\"platform\":\"web\",\"version\":\"2.0.0\",\"attributes\":{\"osName\":\"Mac OS\"}}"
  },
  "requestAcrs": "knowledge",
  "transactionDetails": [
    {
      "detail": "Amount",
      "value": "10001",
      "usage": ["RBA"]
    },
    {
      "detail": "Purpose",
      "value": "Transfer",
      "usage": ["RBA"]
    }
  ]
}

The user must complete the minimum authentication level configured for machine registration. After successful registration, IDaaS returns machineAuthenticator with the nonce values to store. Omit fingerprint only when device fingerprinting is not required.

Verify the risk evaluation​

The Authentication API response shows the authentication flow outcome, not the underlying risk calculation. Verify the expected behavior as follows:

  1. Review authenticationTypes as an indication of the resulting authentication flow. The value also depends on the authenticators available to the user.
  2. Complete the returned authentication flow and confirm that authenticationCompleted is true.
  3. Use the authentication audit as the authoritative record of the selected resource rule, risk level, generated risk points, authentication flow, and individual risk factor results. See View and export audit logs.