Monitoring my Tenant - Audit Logs and Records

While leveraging your tenant within the HID Authentication Service, you can view the API activity audit (for example, to get reliable information about events that happen for your users).

The HID Authentication Service implements a secure auditing mechanism that records all API events within your tenant.

Each audited entry is:

• Non-repudiable (signed)

• Tamper-resistant (verification of the signature)

• Available (redundant with backups)

An event is an atomic line in the Audit logs stored in the HID Authentication Service. The Audit logs keep a trace of any event occurring within your tenant, including authentications, transactions, user creations, and role assignments.

The Audit logs protect PII (Personally Identifying Information - end user's personal data) by leveraging the Tokenization concept.

Tokenization means that each sensitive personal piece of data is replaced by a randomly generated token (pseudonymization). This token is kept on the HID Authentication Service-side in a mapping table, the Token Vault, allowing to trace back to the real user for whom the log line concerns.

The Token Vault API allows searching for pseudonymization tokens in an human-readable version of the exported audit log to get their original value.

Searching for Audited Records

Searching for records is performed by calling the AuditRecords endpoint with the bearer token of your privileged user (Organization Administrator). This will fetch all records.

POST /scim/{tenant}/v2/AuditRecords/.search
{
    "filter": "created gt 2022-11-27T12:00:00Z and verify eq true",
    "count": 10,
    "startIndex": 1,
    "sortBy": "created",
    "sortOrder": "ascending"
}

Where:

• The filter attribute can be used to check the integrity of the records and reduce the number of records you want to see:

  You can use the and operator between filters and use parentheses between conditions.

  • Records should be checked for integrity:

    verify eq true

  • Successful or failed authentications:

    result eq RESPONSE_SUCCESS

    result eq RESPONSE_FAILURE

  • Records between two dates:

    created gt 2022-11-27T09:00:00Z and created lt 2022-11-28T12:00:00Z

Note: All filters support the 'eq' operator with an exact search or with the '*' wildcard character except 'created'.

• The following attributes can be used for a paginated search:

  • count can be used to limit the size of the search results

  • startIndex specifies the index of the first result returned (where 0 will returned the same paginated result as 1)

  The result will contain a totalResults attribute to allow you to compute the number of pages.

  Important:

  The maximum number of rows returned per request is 100, even if you specify a higher count value. Therefore, for lists that are longer than 100 elements, it is mandatory for you to paginate the results.

• The search results can be sorted using:

  • sortBy - the created filter (the record's timestamp)

  • sortOrder - either ascending or descending (or asc or desc)

HTTP/1.1 200 OK
Date: Wed, 04 Jan 2023 16:05:52 GMT
Content-Type: application/scim+json;charset=utf-8
{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 162,
    "resources": [
        {
            "schemas": ["urn:hid:scim:api:idp:2.0:AuditRecord"],
            "id": "IDP-test-company",
            "targetUserId": {
                "id": "admin@company.com",
                "immutableId": "11092",
                "session": {
                    "id": "1ea9ac7d7236aa0dce70d63fccb2779411c29478b0ea66cef815bb758479c1cf",
                    "authenticationMethod": "AT_STDPWD"
                }
            },
            "action": {
                "actionName": "indirectPrimaryAuthenticateUP",
                "actionParameters": {
                    "ATC": "AT_STDPWD",
                    "USN": "null",
                    "Action": "indirectPrimaryAuthenticateUP",
                    "ANS": "false",
                    "ARP": "CONTEXT[{\"OPENID\":{\"clientid\":\"r7wcHxsAGjT7jweAjtQCwMw6\",\"scope\":\"openid profile\"}}]",
                    "AUS": "ENABLED",
                    "CHC": "CH_EXTRAPP"
                }
            },
            "result": "RESPONSE_SUCCESS",
            "return_value": {
                "response": "SUCCESS"
            },
            "tenantId": "tdf1808f3d368517208759",
            "actingUserId": {
                "id": "r7wcHxsAGjT7jweAjtQCwMw6",
                "immutableId": "200",
                "session": {
                    "id": "16c52d7ae20de197ca8eecf9bb6ec566e5d8b21e03538632e9fdf3d84b6e1f73"
                }
            },
            "integrityStatus": "validated",
            "created": "2023-01-04T16:04:34.678Z",
            "host": "<host-ip>"
        },
        {
            "schemas": ["urn:hid:scim:api:idp:2.0:AuditRecord"],
            "id": "IDP-test-company",
            "targetUserId": {
                "id": "r7wcHxsAGjT7jweAjtQCwMw6",
                "immutableId": "200",
                "session": {
                    "authenticationMethod": "AT_SYSLOG"
                }
            },
            "action": {
                "actionName": "primaryAuthenticateUP",
                "actionParameters": {
                    "ATC": "AT_SYSLOG",
                    "USN": "null",
                    "Action": "primaryAuthenticateUP",
                    "ANS": "false",
                    "ARP": "CONTEXT[{\"OPENID\":{\"clientid\":\"r7wcHxsAGjT7jweAjtQCwMw6\",\"scope\":\"openid profile\"}}],HOSTADDRESS[10.7.252.38]",
                    "AUS": "ENABLED",
                    "CHC": "CH_EXTRAPP"
                }
            },
            "result": "RESPONSE_SUCCESS",
            "return_value": {
                "response": "SUCCESS"
            },
            "tenantId": "tdf1808f3d368517208759",
            "actingUserId": {
                "id": "r7wcHxsAGjT7jweAjtQCwMw6",
                "immutableId": "200",
                "session": {
                    "id": "16c52d7ae20de197ca8eecf9bb6ec566e5d8b21e03538632e9fdf3d84b6e1f73"
                }
            },
            "integrityStatus": "validated",
            "created": "2023-01-04T16:04:23.268Z",
            "host": "<host-ip>"
        },
        {
            "schemas": ["urn:hid:scim:api:idp:2.0:AuditRecord"],
            "id": "API-test-company",
            "targetUserId": {
                "id": "afiuser1",
                "immutableId": "11072",
                "session": {
                    "authenticationMethod": "AT_EMPOOB"
                }
            },
            "action": {
                "actionName": "registerUserForOutOfBand",
                "actionParameters": {
                    "ATC": "AT_EMPOOB",
                    "Action": "registerUserForOutOfBand",
                    "DSN": "11297",
                    "DID": "11294",
                    "CHC": "OPERATOR"
                }
            },
            "message": "Registration successful",
            "result": "RESPONSE_SUCCESS",
            "return_value": {
                "response": "SUCCESS"
            },
            "tenantId": "tdf1808f3d368517208759",
            "actingUserId": {
                "id": "SAXLGROUU9npqp4M5A1gO4kE",
                "immutableId": "10033",
                "session": {
                    "id": "9c21b4689c0e59196660c8af60d1c195413ce8fcc68c532fb5c5337b6f5093be"
                }
            },
            "integrityStatus": "validated",
            "created": "2022-12-15T15:18:46.983Z",
            "host": "<host-ip>"
        }
    ],
    "startIndex": 1,
    "itemsPerPage": 100
}

Where:

• resources is an array of audited records

• Each record in the response includes the integrityStatus property with one of the following values:

  • validated

  • tainted

  • unverified

Event Types

The following is a list of recorded event types (actionName):