HomeUse CasesConceptsConfig GuidesDeveloper GuidesAPI Reference
Content

Events and Reports

Suggest Edits

Introduction

This guide describes accessing audited events associated with Adaptive Access and how to interpret the event details.

Adaptive access events are generated when an Adaptive access policy assigned to a native application is invoked for a Policy-based Authentication 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.

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

Adaptive access events can be accessed using

Events service API

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.

The Events API is described in the API Reference information.

To receive adaptive access events, use event_type="adaptive_risk" when calling the Events service API.

Obtain an Access Token

Obtain an access token for using an API Client which has manageReports or readReports entitlements. The easiest way to do this is using the Client Credentials OAuth flow.

curl --location --request POST 'https://<tenant_url>/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}

Retrieve events

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://<tenant_url>/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
    }

Review 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.

Adaptive access reports are only available in the IBM® Security Verify administration console, however the readonly group can be used to provide developers access to reports with no permissions to alter configuration.

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.

To enable readonly permissions refer to Managing groups topic in IBM Security Verify product in the IBM® Knowledge Center.

Navigate to reports

To see the Adaptive access report, navigate to the Reports page in the IBM® Security Verify administration console.

The Adaptive access tile displays the Risk levels from the past 24 hours:

1344

Report tiles

View report

An Adaptive access report is generated when you select View Report.
You can filter the events returned. For example, setting From and To dates.

1335

Adaptive access report

Review 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.

1344

Adaptive access event data elements

The Events service API or an Adaptive access report can both be used to obtain results from an Adaptive access policy invocation.

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 Set up a sample application.
  • 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 Adaptive Access Policy for Native applications.

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 in the:

Updated 9 months ago

What’s Next