Managing the Correlation ID

A Correlation ID allows you to tag a particular transaction or an event chain in order to capture the log events. HID Authentication Service allows a client application to integrate and pass the Correlation ID in the request header which will then be stored in the generated Audit Logs.

Note: The recommended format of the generated Correlation ID is UUID.

Correlation ID Flow

Request and Response

The client application can pass the correlation ID for each RESTful API call through the X-Correlation-ID HTTP header. This Correlation ID is returned in the response header for all responses (Success and Fail).

Audit Logs

The correlation ID passed in the HTTP header of an API call can also be found in the corresponding audit logs. If the API call does not contain correlation ID in its HTTP header, then the field correlation ID is empty in the audit logs.

Sample Flow of Correlation ID

In the following example, the Correlation ID - f058ebd6-02f7-4d3f-942e-904344e8cde5 - is passed in the HTTP header:

Copy

POST https://[base-server-url]/{tenant}/authn/token HTTP/1.1
X-Correlation-ID: f058ebd6-02f7-4d3f-942e-904344e8cde5
grant_type=client_credentials&client_id=spl-api&client_secret=password01&scope=openid profile

The same Correlation ID is stored in the corresponding Audit Logs:

Copy

{
    "result":"RESPONSE_SUCCESS",
    "return_value":"SUCCESS",
    "service":{
        "host":"<IP Address>",
        "id":"CH_DIRECT"
        },
    "jws":"<TOKEN>":"YOUR_TENANT",
    "action":{
        "actionParameters":[
            {
            "ATC":"AT_SYSLOG"
            },
            .
            .
            .
            .
        "actionName":"primaryAuthenticateUP"
        },
    "targetUserId":{
        "immutableId":"9fd451c6af4d96836dd0",
        "session":{
            "authenticationMethod":"AT_SYSLOG",
            "id":null
        },
    "id":"4bf1d463-221b52030725"
        },
    "correlationId":"f058ebd6-02f7-4d3f-942e-904344e8cde5",
    "id":"2564ghj_1.4:11",
    "message":null,
    "eventDate":"2020-10-27T14:56:14Z"
    }

Leveraging Correlation ID in HID Authentication Service

The Correlation ID can be leveraged for multiple Audit purposes.

The following diagram illustrates the following:

Single Correlation ID in Multiple Audit Logs
Correlation ID and COI in Audit Logs
Audit Search Endpoint
Backward Compatibility for Event Search Endpoint

Note: Registering Open ID Client and Bulk User Import are used for illustration purposes.

Types of Correlation ID in Audit Logs

There are two types of correlation ID - the header Correlation ID and the API-generated correlation ID.

To accommodate these two types of correlation ID in the Audit Logs, there are two different capture fields:

Correlation ID - captures the Correlation ID passed in the request header through the HTTP X-Correlation-ID header

COI - captures the Correlation ID generated in the response body as a result of specific action on an API call.

For example, the Auth Req ID in the CIBA response body and Correlation ID in the Bulk Import response body can be captured in the COI of the respective Audit Logs.

This correlation ID will be generated by HID Authentication Service.

Single Correlation ID in Multiple Audit Logs

If an API call generates multiple audit logs, then the correlation ID passed in the HTTP header should be stored in all the corresponding Audit Logs. You can then search the Audit Logs by filtering the respective Correlation ID to trace the chain of events.

When a ClientID is registered with a password authenticator through an API, it triggers the following actions and all these corresponding events are captured in the Audit Logs:

Create User
Create Adapter Configuration
Create User Authenticator

In the following sample, the Correlation ID - f058ebd6-02f7-4d3f-942e-904344e8cde5 - is added in the Request Header of the API which makes multiple Audit Logs.

Copy

POST https://[base-server-url]/{tenant}/authn/register HTTP/1.1
X-Correlation-ID: f058ebd6-02f7-4d3f-942e-904344e8cde5
{
    "redirect_uris":["https://client.example.org","https://client2.example.org"],
    "client_name" : "CustomerClientId",
    "token_endpoint_auth_method": "client_secret_basic",
    "hid_client_channel": "CH_EXTRAPP", 
    "hid_client_pwd_policy": "AT_SYSLOG",
    "hid_client_pki_policy": "AT_SYSPKI",
    "hid_user_channel": "CH_EXTRAPP",
    "hid_user_authn_policy": "AT_STDPWD",
    "hid_sessiontransfer_type": "NUM001",
    "hid_client_group": "UG_CLIENTID", 
    "hid_client_scopes":"{\"scopes\":[\"openid\",\"profile\"]}",
    "hid_client_consentprompt": "false"
}

The sample response contains the Create User, Create Adapter Configuration and Create User Authenticator actions:

Copy

HTTP/1.1 200 OK
Date: Mon, 07 Dec 2020 10:31:31 GMT
Content-Type: application/json;charset=UTF-8
X-FRAME-OPTIONS: DENY
Content-Disposition: attachment;filename=response.json
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=16070400; includeSubDomains
X-Correlation-ID: f058ebd6-02f7-4d3f-942e-904344e8cde5
{
    "hid_sessiontransfer_type":"NUM001",
    "grant_types":[
        "client_credentials",
        "password",
        "authorization_code"
        ],
    "hid_client_group":"UG_CLIENTID",
    "registration_client_uri":"https:\/\/[base-server-url]\/{tenant}\/authn\/register\/f058ebd6-02f7-4d3f-942e-904344e8cde5,
    "redirect_uris":[
        "https:\/\/client.example.org",
        "https:\/\/client2.example.org"
        ],
    "hid_client_channel":"CH_EXTRAPP",
    "token_endpoint_auth_method":"client_secret_basic",
    "client_id":"40592624",
    "hid_client_pwd_policy":"AT_SYSLOG",
    "hid_client_consentprompt":"false",
    "hid_client_pki_policy":"AT_SYSPKI",
    "hid_client_scopes":"{\"scopes\":[\"openid\",\"profile\"]}",
    "hid_user_channel":"CH_EXTRAPP",
    "client_secret_expires_at":1765017089,
    "hid_user_authn_policy":"AT_STDPWD",
    "client_id_issued_at":1607337091,
    "client_secret":"CLIENTSECRET",
    "tls_client_certificate_bound_access_tokens":false,
    "client_name":"CustomerClientId"
}

The following Audit Search endpoint can be used to filter the Correlation ID and the response will contain the multiple logs created.

Copy

POST https://[base-server-url]/{tenant}/v2/AuditRecords/.search HTTP/1.1
{
    "schemas":["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
    "filter": "correlationId eq f058ebd6-02f7-4d3f-942e-904344e8cde5",
    "count": 10
}

The Audit Search response is:

Copy

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 3,
    "resources":    [
    {
        "schemas": ["urn:hid:scim:api:idp:2.0:AuditRecord"],
        "id": "IP-12-7-146-133_1.48:1",
        "service": {"id": "CH_DIRECT"},
        "correlationId": "f058ebd6-02f7-4d3f-942e-904344e8cde5",
        "action":          {
            "actionName": "createAdapterConfiguration",
            "actionParameters": {"Action": "createAdapterConfiguration"}
        },
        "result": "RESPONSE_SUCCESS",
        "tenantId": "YOUR_TENANT",
        "actingUserId":          {
            "id": "TestUser2206",
            "immutableId": "11052",
            "session": {"id": "fa8075078783835311ddawer459eec2423d5dd22"}
            },
            "created": "2020-12-15T11:05:41.561Z"
    },
    {
        "schemas": ["urn:hid:scim:api:idp:2.0:AuditRecord"],
        "id": "IP-12-7-146-133_1.47:1",
        "service": {"id": "CH_DIRECT"},
        "targetUserId":          {
            "id": "11669990642744264408072",
            "immutableId": "11054",
            "session": {"authenticationMethod": "AT_SYSLOG"}
        },
        "correlationId": "f058ebd6-02f7-4d3f-942e-904344e8cde5",
        "action":          {
            "actionName": "createUPAuthenticator",
            "actionParameters":             {
                "ATC": "AT_SYSLOG",
                "AVF": "15/12/2020 11:05:39",
                "USN": "116699906421550744264408072",
                "Action": "createUPAuthenticator",
                "AUS": "ENABLED",
                "AVT": "14/12/2025 11:05:39"
            }
        },
        "result": "RESPONSE_SUCCESS",
        "tenantId": "YOUR_TENANT",
        "actingUserId":          {
            "id": "TestUser2206",
            "immutableId": "11052",
            "session": {"id": "fa8075078783835311dda2423d5dd22"}
            },
        "created": "2020-12-15T11:05:39.894Z"
    },
    {
        "schemas": ["urn:hid:scim:api:idp:2.0:AuditRecord"],
        "id": "IP-10-7-146-133_1.46:1",
        "service": {"id": "CH_DIRECT"},
        "targetUserId":          {
            "id": "11669990642164408072",
            "immutableId": "11054"
            },
        "correlationId": "f058ebd6-02f7-4d3f-942e-904344e8cde5",
        "action":          {
        "actionName": "createUser",
        "actionParameters":             {
            "STD": "15/12/2020 11:05:39",
            "Action": "createUser",
            "GRC": "UG_CLIENTID"
            }
        },
        "result": "RESPONSE_SUCCESS",
        "tenantId": "YOUR_TENANT",
        "actingUserId":          {
            "id": "TestUser2206",
            "immutableId": "11052",
            "session": {"id": "fa8075078783835311d3d5dd22"}
            },
        "created": "2020-12-15T11:05:39.799Z"
    }
    ]
}

Correlation ID and COI in Audit Logs

For the HID Authentication Service APIs which already generated the Correlation ID in their response body and captured in the Correlation ID field of the Audit Logs, the new field COI is added in the Audit Logs.

When any of the following actions are performed through an API call, then the audit logs will have both COI and Correlation ID (if passed in the request header) fields:

Bulk devices import
Bulk users import
Organization import
Deliver challenge
CIBA calls

For example, for Bulk user import, both Correlation ID and COI are captured in the Audit Logs.

Copy

Sample for Bulk User Import Request with the Correlation ID in the HTTP Header

POST https://[base-server-url]/{tenant}/v2/Users/.import HTTP/1.1
X-Correlation-ID: f058ebd6-02f7-4d3f-942e-904344e8cde5

{
    "users": [{
        "emails": [{
            "value": "email_1@companyl.com"
        }],
        "name": {
            "familyName": "last1",
            "givenName": "first1"
        },
        "externalId": "userPrefix_1"
        },
        {
        "emails": [{
            "value": "email_2@company.com"
        }],
        "name": {
            "familyName": "last2",
            "givenName": "first2"
        },
        "externalId": "userPrefix_2"
    }],
    "group": {
        "value": "USG_FTEMP"
    }
}

Copy

The response contains two Correlation IDs - one in the response header and the other in the response body

HTTP/1.1 201 Created
X-Correlation-ID: f058ebd6-02f7-4d3f-942e-904344e8cde5
Cache-Control: no-cache
Pragma: no-cache
Location: https://[base-server-url]/{tenant}/v2/Users/.import/13U8F2URK9GC8Q9FQELR
Content-Disposition: attachment;filename=response.json

{
    "schemas": ["urn:hid:scim:api:idp:2.0:user:ImportResponse"],
    "meta": {
        "resourceType": "UserImportResponse",
        "location": "hhttps://[base-server-url]/{tenant}/v2/Users/.import/13U8F2URK9GC8Q9FQELR",
        "version": "1"
    },
    "correlationId": "13U8F2URK9GC8Q9FQELR"
}

Copy

The corresponding Audit Log captures both the Correlation ID in the respective COI and Correlation ID fields

{
    "result":"RESPONSE_SUCCESS",
    "return_value":null,
    "service":{
        "host":"<IP ADDRESS>",
        "id":"CH_DIRECT"
    },
    "jws":"<TOKEN>",
    "tenantId":"YOUR_TENANT",
    "action":{
        "actionParameters":{
            "Action":"importUsers",
            "step":"start",
            "importSize":"2",
            "COI":"13U8F2URK9GC8Q9FQELR"
            },
        "actionName":"importUsers"
    },
    "actingUserId":{
        "immutableId":"2eac45ce-6972-46da-a1d5-b65b636bf45e",
        "session":{
            "authenticationMethod":null,
            "id":"39c5ca23741401dcf61530e91cd3f"
        },
        "id":"4d514de17b43ec7"
    },
    "correlationId":"f058ebd6-02f7-4d3f-942e-904344e8cde5",
    "id":"fgth5",
    "message":null,
    "eventDate":"DATE : TIME"
}

Copy

Sample audit event for a transaction signature with context data (where LHT is the login_hint_token) in the action parameters

"action": {
    "actionName": "indirectDeliverChallenge",
    "actionParameters": {
        "ATC": "AT_TDS",
        "Action": "indirectDeliverChallenge",
        "LHT": "eyJhbGciOiJub25lIn0.eyJhdXRocG9sIjoiQVRfVERTIiwidGRzIjoie2Ftb3VudCwgNDAwLjAwfSx7c29ydGNvZGUsMjAtMzAtOTB9LCB7YWNjb3VudF90bywxMjM0LTU2Nzh9IiwiY2hhbm5lbCI6IkNIX1REUyIsInVzZXJjb2RlIjoiYmxlLXB1c2giLCJjcmVhdGVTZXNzaW9uIjoiMSIsInRkc19jb250ZXh0IjoiVFhrZ2RISmhibk5oWTNScGIyNGdjMkZ0Y0d4bElHTnZiblJsZUhRPSJ9.",
        "COI": "a41bfdd4-c391-429d-8538-fc7729359d7a",
        "DSN": "aebd459f-c826-40a3-bd3c-f98527f607cb",
        "CHC": "CH_TDS"
    }
}

Audit Search Endpoint

You can search the Audit Logs by filtering the Correlation ID and COI fields.

Sample Request with the Correlation ID filter:

Copy

POST https://[base-server-url]/{tenant}/v2/AuditRecords/.search HTTP/1.1
{
    "schemas":["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
    "filter": "correlationId eq f058ebd6-02f7-4d3f-942e-904344e8cde5",
    "count": 10
}

The sample request with the COI filter:

Copy

POST https://[base-server-url]/{tenant}/v2/AuditRecords/.search HTTP/1.1
{
    "schemas":["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
    "filter": "action.actionParameters.COI eq 12P4NS361SK9MDQCF6F8",
    "count": 10
}

The response contains the filtered Audit Logs with the COI and Correlation ID:

Copy

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 2,
    "resources":    [
        {
        "correlationId": "f058ebd6-02f7-4d3f-942e-904344e8cde5",
        "action":          {
            "actionName": "importDevices",
            "actionParameters":             {
                "Action": "importDevices",
                "nbImported": "1",
                "COI": "12P4NS361SK9MDQCF6F8"
            }
        },
        "message": "Imported 1 devices",
        "result": "RESPONSE_SUCCESS",
        "tenantId": "YOUR_TENANT",
        "actingUserId":          {
            "id": "TestUser",
            "immutableId": "11052",
            "session": {"id": "789790"}
        },
        "service": {"id": "CH_DIRECT"},
        "correlationId": "f058ebd6-02f7-4d3f-942e-904344e8cde5",
        "action":          {
            "actionName": "addDevice",
            "actionParameters":             {
                "entityType": "Device",
                "entityId": "0965516083",
                "COI": "12P4NS361SK9MDQCF6F8"
            }
        },
        "result": "RESPONSE_SUCCESS",
        "return_value": {"response": "SUCCESS"},
        "tenantId": "YOUR_TENANT",
        "actingUserId":          {
            "id": "TestUser5696",
            "immutableId": "11052"
        },
        "created": "2020-12-10T20:55:51.886Z"
        }
    ]
}

Backward Compatibility for Event Search Endpoint

The Event Search endpoint allows filtering the Audit Logs only with the Correlation ID generated in the response body based on the specific action on an API call, which is currently captured in the COI field of the Audit Logs. However, this change will not affect the Event Search endpoint responses, which will perform the same action as before.

Event Search endpoint can only be with the Correlation ID filter for the below API:

Bulk devices import
Bulk users import
Organization import
Deliver challenge
CIBA calls

Sample request with the Correlation Id (generated in the response body) filter:

Copy

{
    "schemas":["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
    "filter": "correlationId eq 1NGO3I50EG92RKBJTM1V",
    "count": 10
}

Sample response with the filtered Correlation Id:

Copy

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:EventList"],
    "eventTokens":   [ <-- array of eventTokens --> ],
    "tainted": false,
    "matchedCriteria": 6
}

Note: You cannot filter a header Correlation ID using the Event Search endpoint. If you use the header correlation ID in the Event search API, you will receive null results in the response.