Skip to main content

Understanding events and reports

Adaptive access events are generated when an Adaptive access policy assigned to a native application is invoked for a Post authentication rules evaluation.
The event data contains a number of key indicators from the detection, as well as core details of the user, application, access policy and evaluation outcome. Additionally session data and correlation keys are available to assist Support if troubleshooting does not resolve issue.

Adaptive access events can be accessed using

In this example, the same event is retrieved using the Events service API and displayed in the Adaptive access report.

The Events service API provides the raw data that is used to generate the Adaptive access reports and can also be used for SIEM integration.
Any developer (or user) with an entitled access token can access events using the Events service API.
Adaptive access reports are only available in the IBM® Security Verify administration console, however readonly group can be used to provide developers access to reports with no permissions to alter configuration.

Events service API

The Verify Application programming interfaces (APIs) are described in the IBM Security Verify product in the IBM® Knowledge Center.
Access the full API documentation at https://<hostname>.verify.ibm.com/developer/explorer to learn more about the REST API operations and responses.

Events service API documentation

Adaptive access event request

Use the adaptive_risk event_type when calling the Events service API.

  1. Obtain an access token with manageReports or readReports entitlements.
    Refer to the OAuth access token topic in IBM Security Verify product in the IBM® Knowledge Center.

    curl --location --request POST 'https://<hostname>.verify.ibm.com/v1.0/endpoint/default/token' \
    --header 'Accept: application/json' \
    --data-urlencode 'grant_type=client_credentials' \
    --data-urlencode 'client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
    --data-urlencode 'client_secret=xxxxxxxxxx'
    {"access_token":"ixFpC9ToQmbwDzob280GxYqMko3d7zEFcArUBX1C","grant_id":"2340fa1c-ade9-4dd5-b349-7b5f6af388d4","token_type":"Bearer","expires_in":7200}
  2. Use the access_token to retrieve the adaptive_risk events.
    Optionally you can use a time filter to override the default 24 hour window to limit the results to the known troubleshooting time period.

    curl --location --request GET 'https://<hostname>.verify.ibm.com/v1.0/events?event_type=\%22adaptive_risk\%22&range_type=time&from=1600869600000&to=1600955999999' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer ixFpC9ToQmbwDzob280GxYqMko3d7zEFcArUBX1C'
    {
        "response": {
            "events": {
                "search_after": {
                    "total_events": 3,
                    ...
                ... }
            ...}
        },
        "success": true
    }
  3. Review the event detail.
    The event JSON contains the details of the Adaptive access policy evaluation and includes the Session ID and Correlation ID.
    Key details of the event is described in Adaptive access event data elements.

    {
        "response": {
            "events": {
                ...
                "events": [
                    { ... },
                    {
                        ...
                        "data": {
                            ...
                            "applicationid": "4587066640521568871",
                            "applicationname": "My Native Web App",
                            "policy_id": "357317",
                            "policy_name": "My Native Web Adaptive access policy",
                            "rule_id": "1596095800392",
                            "rule_name": "Adaptive Access",
                            "risk_level": "MEDIUM",
                            "policy_action": "ACTION_MFA_PER_SESSION",
                            "reason_id": "1003",
                            "reason": "Access with a change in device attributes",
                            "csid": "pp24c528943651cbe63c91dd0590b24323a80a0b401600954689",
                            ...
                            "snippet_id": "511843",
                            "risk_score": "300",
                            ...
                            "behavioral_anomaly": "false",
                            "new_device": "true",
                            "risky_device": "false",
                            "risky_connection": "false",
                            "isp": "TPG Internet",
                            "city": "Brisbane",
                            "country": "AUS",  
                            "new_location": "true",
                            ...
                        },
                        "year": 2020,
                        "event_type": "adaptive_risk",
                        "month": 9,
                        "day": 24,
                        "time": 1600954701039,
                        ...
                        "correlationid": "CORR_ID-1c1ec6f4-07b2-4a20-ab9f-9adc62b980cd"
    
                    },
                    { ...},
                ]
            }
        },
        ...
    }

Adaptive access report

To access the Adaptive access report, refer to Generating an Adaptive Access activity report.

Administrators can generate and view Adaptive access reports in the IBM® Security Verify administration console.
Verify also includes a readonly group. Members in this group can click Switch to admin to access the administration console from the User home page.
They can view information about applications, governance operations, users and groups, reports and configuration.
They cannot modify any information. However, they can run reports.
To enable readonly permissions refer to Managing groups topic in IBM Security Verify product in the IBM® Knowledge Center.

  1. Access the Reports menu in the IBM® Security Verify administration console.
    The Adaptive access tile displays the Risk levels from the past 24 hours.
    Report tiles

  2. The Adaptive access report is generated.
    Optionally you can filter the events returned. In this example the time filter was used to correspond with the Events service API example.
    https://<hostname>.verify.ibm.com/ui/admin/reports/adaptiveAccess?fromDate=1600869600000&toDate=1600955999999 Adaptive access report

  3. Review the event detail.
    When selecting an individual row the event detail is displayed.
    Key details of the event is described in Adaptive access event data elements.
    You can click the Show session data link to display the Session ID and Correlation ID, or
    click the Download session data link to export the JSON event data, similar to the JSON from the Events service API detail.
    Detailed event view

Adaptive access event data elements

The Events service API and Adaptive access report can be used to extract results from an Adaptive access policy invocation.
In the examples above, the same event is used to demonstrate the correlation between events and reports.
During troubleshooting, some key details from the event or report include

  • Session ID - For example: pp24c528943651cbe63c91dd0590b24323a80a0b401600954689.
    The session id generated by the Native Web SDK as described in Ensuring Collection Completes.
  • Corelation ID - For example: CORR_ID-1c1ec6f4-07b2-4a20-ab9f-9adc62b980cd.
    Low level request indicator that can be included in the problem detail if troubleshooting does not resolve the issue.
  • Snippet ID - For example "snippet_id": "511843"
    The snippet id configured for the application or the IBM® Security Verify tenant host snippet id.
  • Reason - For example Access with a change in device attributes.
    Refer to Generating an Adaptive Access activity report for Reason descriptions.
  • Risk level - For example Medium (Adaptive access report) or "risk_level": "MEDIUM" (Events service API).
    The Risk level for the assessment derived from the risk score.
    Use the Risk level to correlate to the appropriate Policy action configured in Post authentication rules.

Collecting the event data during troubleshooting for an unexpected Adaptive access evaluation is used when Obtaining Support and providing the MustGather data.

Session ID correlation

When troubleshooting an individual assessment or scenario flow, it important to correlate the Native Web application collection and detection in the browser with the Adaptive access policy evaluation.
The Session ID is available:


Next: Successful evaluation

Previous: System status