Troubleshoot Adaptive Access

👍

Check system status

Before you begin troubleshooting it is recommended to check the Current system status for known service interruptions that may impact Adaptive access collection, detection or Adaptive access policy evaluation.

Introduction

If you're not getting the expected behavior from a native web application configured for Adaptive Access, you need a way to figure out where the problem is. Reviewing Events and Reports from your IBM Security Verify tenant can help to point you in the right direction.

You can jump to an appropriate section of this guide if you can identify the issue:

• No event or report entry found
• Risk Service Unavailable in event or report entry
• Unexpected evaluation decision

No event or report entry

When there is no event or report entry for an known authentication attempt in the Native Web application, this indicates either:

• there is no Adaptive access policy associated with the Native web application
• the access policy isn't applied to the grant type being used.
• insufficient data was provided to the /token endpoint
• collection did not commence.
• collection did not complete.
• an error response (or no response) from the Proxy SDK was not handled correctly and no further attempts were made.

No adaptive access policy

In an Adaptive access policy the post authentication rules invoke an assessment.

Check which access policy is attached to your application. On-board a native application:

Ensure this access policy has Adaptive access checkbox enabled:

🚧

I don't see adaptive access in my access policy?

If you don't see adaptive access in your access policy, make sure the policy is a native web application policy. If you don't see the option for native web application policy in policy editor, check that you tenant is enabled for Adaptive Access (by checking subscriptions).

Access policy is not applied for the grant type

Make sure that the access policy is applied for JWT Bearer in the application definition Apply access policy to API grant types section. If you are not seeing an expected event during a different grant type flow (e.g. refresh flow), make sure this grant type is also selected.

See example for refresh grant type here.

Insufficient data

When Using the Proxy SDK to Authenticate a User the function adaptive.assessPolicy(context) requires a context similar to:

var context = {
    sessionId : req.body.sessionId, // The generated session ID posted from the browser
    userAgent : req.headers['user-agent'], // The user-agent collected from headers
    ipAddress : req.ip // The source address of the IP connection.
};

Ensure you have:

1. invoked the getSessionId() from the Browser SDK.
   Refer to Ensuring Collection Completes for details on how to invoke getSessionId() correctly.
2. handled the "error":"adaptive_more_info_required" indicating there was insufficient or incorrect data provided in the context.
   Refer to Perform Recollection to handle the error from the Proxy SDK with the provided snippet.

Unable to apply the access policy or Invalid Forward IP specified in the request.

When performing a user authentication via the Proxy SDK, the ipAddress defined in the context object must be an Internet-routable IP address.

Invalid IP addresses such as loopback addresses (:::1, 127.0.0.*), non-routable, and internal IP addresses (192.168.0.*) result in the collected IP address from the users browser and the IP address that is reported from the Proxy SDK not matching. This mismatch causes the policyAuth flow not to run.

Typically when the Proxy SDK is deployed as a containerized application in non-production environments, the req.ip value is a loopback address between the Adaptive-enabled application and the Proxy containers. When this value is passed on through the flow, an error occurs due to an invalid forward IP address.

var context = {
    sessionId : req.body.sessionId,
    userAgent : req.headers['user-agent'],
    ipAddress : req.ip // This value may contain an invalid value such as a loopback address.
};

To fix this issue, ensure that the provided IP Address can be reached through the internet and does not represent a loopback address. Use the IP address of the users browser explicitly, rather than taking it from the request.

var context = {
    sessionId : req.body.sessionId,
    userAgent : req.headers['user-agent'],
    ipAddress : "<IP address of the user's browser>" // Updated IP to avoid unexpected values
};

When authentication is performed, this change ensures that the ipAddress field matches what is gathered from the user's browser collection. It also ensures that the real IP address of the users browser is used. This fix is only applicable when the application runs locally. Because you are connecting to the application on your own device, the extracted IP address is not the external IP of the server, but the local container's IP.

❗️

Update ipAddress with a fixed value in local, non-production environments only.

Update ipAddress with a fixed value only in non-production environments where both the containers and the user's browser are running locally.

In a production environment, the Adaptive-enabled application must assert the real IP address of the user's browser to the Proxy SDK. It must match the value of the IP address that is collected from the user's browser.

Collection did not commence

When the Browser SDK is initialized on the login page, as described in Ensuring Collection Completes, if the collection does not start, no Session ID will be provided and the call to getSessionId() will not return the correct value.

User the Developer Tools in your browser to check that collection and detection has started.
You should see requests in Network tab that include a request to the cloudfront host specified in the web snippet that was generated during on-boarding the native application
For example https://d1anfu45urknyg.cloudfront.net/511843/aloads.js?dt=login&r=0.3289762412868322.
You should see additional JavaScript loaders requested, which may include

• bits.js
• main.js
• tags.js

These loaders should return a 200 response code with a non-empty response body.

Additionally, you should see multiple requests to the same cloudfront host with different URI paths as the collection continues.

If you do not see these requests, ensure you have:

1. accessed your Native Web application using the same domain name specified for Allowed domain when On-boarding your native application.
2. correctly loaded the Browser SDK to start the Adaptive access collection and detection as described in Ensuring Collection Completes
3. exposed the static resource as described in Hosting a Well-Known Static Resource

Collection did not complete

When the Browser SDK is initialized with startAdaptiveV1('<snippet host>', '<snippet ID>'); collection will commence. Only once the promise for getSessionId() is returned with the Session ID should the login form be submitted.

If you submit the login form before a Session ID is available an "error":"adaptive_more_info_required" will be returned from the Proxy SDK assessPolicy(context) or refresh(context, refreshToken) call.

Ensure you have updated your login page to ensure a Session ID is available from getSessionId() before the login form submission. Refer to options described in Ensuring Collection Completes.

Error response handling

When there is Insufficient data to complete an assessment an error status is returned. Unless additional assessment calls (assessPolicy(context) or refresh(context, refreshToken)) are made, no event will be generated.

Only after a number of unsuccessful re-assessment calls have been made will a Risk Service Unavailable event be generated. The Medium Risk level of the Adaptive access policy will be returned.

Other errors, such as connection errors, will also prevent the Proxy SDK from invoking the IBM Security Verify APIs and will return an error result. Those errors should also be handled within the Native Web application.

Ensure you have:

1. checked the configuration parameters of your IBM Security Verify Adaptive Browser SDK.
   The startAdaptiveV1('<snippet host>', '<snippet ID>'); should match the call web snippet generated during application on-boarding.
2. checked the configuration parameters of your IBM Security Verify Proxy SDK.
   The tenantUrl, clientId and clientSecret passed to new Adaptive(<config>); need to match your custom application definition.
   Refer to Adding the Proxy SDK to an Application Server.
3. handled the "error":"adaptive_more_info_required" indicating there was insufficient or incorrect data provided in the context.
   Refer to Perform Recollection to handle the error from the Proxy SDK
   with the provided snippet.

Risk Service Unavailable

When an Adaptive access assessment is unavailable the policy action corresponding to the Medium Risk level of the Adaptive access policy is returned. The event and report will show the reason "Risk Service Unavailable - Medium Risk Applied.".

This error will be returned when:

• a recoverable error, such as a "error":"adaptive_more_info_required" is encountered multiple times for the same session Id
• a non-recoverable error such as incomplete context data or a service interruption is encountered

In the Adaptive access report:

• Reason will contain "Risk Service Unavailable - Medium Risk Applied."
• Session ID may contain a valid value for example pp629e475c7b6fa646e5b7606a61b3bec35ebde151600944772 or an empty value (-)
• Adaptive details will contain empty values (-) for all Risk indicators

Recoverable error

During recoverable errors, an Adaptive access evaluation is unavailable due to insufficient data including:

• missing or invalid Session ID
• mismatch of snippet id being copied or reused between IBM® Security Verify tenants and Native Web applications
• incomplete collection

Only after multiple unsuccessful collection and corresponding evaluation attempts will the Medium Risk level of the Adaptive access policy be returned.

Use the Events service API or Adaptive access report to determine the Session ID.

• If no Session ID is available, refer to
  • Insufficient data
  • Collection did not commence
  • Collection did not complete
• If there is a Session ID in event or report, check current system status for any known system outages.

Non-recoverable error

When a non-recoverable error occurs, adaptive access is not able to return an assessment result. To provide a consistent level of protection (fail closed) the action corresponding to the Medium Risk level of the Adaptive access policy is returned.

Ensure you have:

1. checked the current system status for any known system outages
2. checked that you are sending all the required context information in your call to the proxy SDK

Unexpected evaluation decision

If you have completed Session ID correlation and cannot locate a matching event with a corresponding Session ID in either the Events service API event or the Adaptive access report detail, ensure you have:

1. attached an Adaptive access policy.
   If an Access policy is attached to your Native Web application and you receive a valid decision, but no Adaptive access event is generated, this indicates Adaptive access was not invoked.
2. correct Error response handling.
   If the API was not invoked correctly an error is returned from the Proxy SDK which must be handled. If the API was invoked correctly, but there was insufficient data, additional collection may be required. In both cases no event is generated.

If you have located an event with correlated Session ID, an Adaptive access assessment was invoked.

Change in user or device attributes

Adaptive access uses deep identity insights, through a sophisticated risk calculation engine (IBM Trusteer®), to accurately match Access policies to the user profile throughout their digital interaction with the application.
During collection, detection and assessment the Session ID may have been evaluated by the risk calculation engine differently to the expected manual testing process.
A range of indicators may alter the assessment result including:

• user was not new
• user had a pending MFA from a previous session
• location, device or behavioral patterns changed significantly

Access policy logic error

Access policies combine the riskiest result from Adaptive access, reauthentication and any matching Policy rule.
If there are no Policy rules, or none are matched during evaluation, the Default rule is used for the riskiest comparison.

Ensure you have:

1. configured the correct action for the expected risk level in the Adaptive access policy.
2. validated that the Reauthentication and Policy rules did not return a riskier result.
   "rule_name" in the Events service API JSON and Rule name in the Adaptive access report detail detail indicate the riskiest result for the policy evaluation.

Multiple unsuccessful access policy invocations

When an Adaptive access policy has insufficient data to complete an assessment, additional collection is required.
If the Native Web application has correct Error response handling, but the evaluation is unsuccessful multiple times, a Risk Service Unavailable event is generated and the associated medium risk action is invoked.

Access policy re-invocation

When an MFA challenge is returned from an Adaptive access policy evaluation and the the challenge is successfully completed, two events are generated:

1. the initial MFA challenge event
2. an Allow event during the policy re-evaluation

If you see the MFA challenge event but not the subsequent Allow event, ensure you have:

1. identified the possible factors in therequires response from assessPolicy function of the IBM Security Verify Proxy SDK:

   JSON

   {
   "status": "requires",
   "transactionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "enrolledFactors": [{type:"emailotp", ...}, {type:"totp", ...}, ...]
   }
   

2. invoked the appropriate generateXXXX (where applicable) and evaluateXXXX functions for one of these factors.

Obtaining Support

If the troubleshooting process does not resolve your error, refer to the IBM Security SaaS Support topic under the Troubleshooting and support section of the IBM Security Verify product in the IBM® Knowledge Center.

Ensure you have collected Mandatory MustGather. During the troubleshooting process you will have probably already collected a large amount of the MustGather data required.

📘

Provide recent data

some of the MustGather data is time sensitive, please ensure that it is recent before contacting support.

Mandatory MustGather

• IBM Security Verify tenant hostname.
  For example: https://<hostname>.verify.ibm.com
• IBM Security Verify Adaptive access snippet host and snippet ID (available on the application configuration page).
  For example: d1anfu45urknyg.cloudfront.net and 511843
• At least one Session ID (available in the browser console).
  For example: pp629e475c7b6fa646e5b7606a61b3bec35ebde151600944772

Optional MustGather

• Correlation ID from event or report.
  For example: CORR_ID-ae2fea3c-66c1-4882-9c52-6130db5448dc
• IBM Security Verify client_id (do not provide the secret).
  For example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• IBM Security Verify application id or name.
  For example: 4587066640521568871 or My Native Web App
• IBM Security Verify Access policy id or name.
  For example: 357317 or My Native Web App Adaptive access policy
• The error code and message.
  For example: CSIAQ0298E Adaptive access assessment unavailable. Session collection was not completed or interrupted.