Risk-based authentication and machine authentication

Use this page to understand how risk evaluation and machine authentication affect Authentication API flows.

How RBA affects Authentication API requests

Risk-based authentication (RBA) evaluates the risk factors configured in an application's resource rule. IDaaS combines the risk points from failed factors, classifies the request as low, medium, or high risk, and applies the authentication flow configured for that risk level.

Authentication API requests and IDaaS-hosted authentication use the shared resource rule evaluation engine. Only factors configured in the applicable resource rule are evaluated. For details about risk scoring and authentication flow selection, see Create and manage resource rules.

Risk factor inputs

Configured risk factors use the following inputs. The Authentication API client must provide only the client-derived inputs required by those factors.

Risk factor	Input used during evaluation
Date and Time	The current time from IDaaS, converted to the time zone configured in the risk factor. No request input is required.
External	User and account data, the client IP address, and transactionDetails, as required by the configured external risk engine.
Geolocation	The client IP address, which IDaaS resolves to a geographic location.
Source IP Address	The client IP address.
Location History	The current client IP address and locations stored from the user's previous successful authentications.
Machine Authentication	The current machineAuthenticator, which can contain a machine nonce, sequence nonce, device fingerprint, or a configured combination.
Transaction	The transactionDetails configured for the resource rule transaction context.
Travel Velocity	The current client IP address, its resolved location, previous location history, and the elapsed time between authentications.

The Authentication API application controls whether IDaaS gets the client IP address from the request body, the incoming HTTP connection, or neither source. See Choose the client IP address source.

Configured IP-based risk factors are still evaluated when no client IP address is available. The missing input can cause a factor to fail and increase the evaluated risk.

For transaction input requirements, see Transaction details and mobile SDK push messages. For external risk engine configuration, see Manage external risk engines.

Resource rule access filter inputs

Before IDaaS evaluates risk factors, access filters determine whether a resource rule applies to the request. Authentication API resource rules can use these inputs:

Access filter	Input used to select the resource rule
Group	The identified user's IDaaS group memberships. No request input is required.
ACR	The space-separated Authentication Context Reference values in requestAcrs. Include the same value in each request in the authentication flow when the rule uses an ACR.

Access filters select eligible resource rules and do not add risk points. See Add Access Filters.

Device Verification outcomes

Device Verification is separate from Machine Authentication. Machine Authentication evaluates the machineAuthenticator supplied by the client. Device Verification uses a trusted device certificate and the Device Agent when the applicable resource rule requires the Device Certificate context.

The Authentication API can return the following fields during the user query, challenge, and challenge completion requests:

Response field	Meaning
deviceCertAuthDesired	true when the resource rule requires the client to attempt Device Verification.
verificationRequired	Indicates during a user query that the user's account verification requirement has not been satisfied.
userVerificationRequired	Indicates the same user account verification requirement in an authentication challenge or challenge completion response.

Do not treat verificationRequired as a Device Verification result. When deviceCertAuthDesired is true, the application must continue the supported Device Verification integration. Sending clientIp or machineAuthenticator does not complete certificate verification.

For example, a user query can return:

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

An authentication challenge or challenge completion response can return:

{
  "authenticationCompleted": false,
  "token": "<authentication-token>",
  "userVerificationRequired": false,
  "deviceCertAuthDesired": true
}

Configure the Device Agent, trusted certificates, and the Device Certificate resource rule context before testing this outcome. See Manage Device Verification.

Machine authentication data

Machine Authentication lets a resource rule distinguish a recognized machine from a new or changed machine. The machineAuthenticator object can contain these values:

• machineNonce: A value IDaaS creates when the machine authenticator is registered. Store it on the client and return it in later authentication requests.
• sequenceNonce: A value IDaaS replaces after each successful machine authentication evaluation. When a response contains a new value, store it and use it in the next Authentication API request.
• fingerprint: Device information collected by the client. IDaaS does not return the fingerprint in a response.

The required values depend on the tenant's machine authenticator settings. Authentication responses use userMachineSettings.deviceFingerprintRequired to indicate whether the client must collect a fingerprint and userMachineSettings.attributeExclusions to identify attributes to exclude. If Device Fingerprint Required is enabled, use the Entrust Device Fingerprint SDK from TrustedCare to produce the fingerprint value. A device fingerprint is not required when the tenant uses a supported nonce-only configuration.

Send machineAuthenticator with each request that can evaluate the Machine Authentication risk factor. If IDaaS returns an updated machineAuthenticator, replace the stored nonce values before the next request.

To register a new machine after successful authentication, send machineAuthenticatorRegistration with the final challenge response. Registration can include a label and, when required, a fingerprint. IDaaS returns the machine and sequence nonces that the client must store.

Interpret risk evaluation

Authentication API responses do not include the calculated risk level or individual risk factor results. Instead, the resource rule outcome affects fields such as authenticationTypes, availableSecondFactor, and authenticationCompleted.

Use authentication audits to review the selected resource rule, risk level, generated risk points, authentication flow, and individual risk factor results. See View and export audit logs.

For complete request examples, see Risk-based authentication.