Audit Webhook Connector

Descope's Audit Webhook Connector allows Descopers to stream audit logs to their own API.

1. Deploy an API to Capture Webhook Events

Deploy an API to a service of your choice that accepts HTTP requests. This API will be used to receive the audit logs from Descope.

export async function POST(request: Request) {
    const body = await request.json();
 
    // Handle audit logs
 
    return new Response(JSON.stringify(body), {
        headers: { 'content-type': 'application/json' },
    });
}

2. Configuring the Webhook Audit Connector

Navigate to the Descope's Audit Webhook Connector configuration page and fill in the required parameters:

• Connector Name: Provide a unique name for your connector. This assists in distinguishing it, especially when multiple connectors are derived from the same template.
• Connector Description: Briefly explain the purpose of this connector.
• Base URL: Input the API URL where you'd like to send audit events to. This should start with either http:// or https://. Use the URL from Step 1.
• Authentication Type: Descope supports various methods to authenticate with your service. Choose the method that suits your API:
  • Bearer Token: Used for access keys such as JWTs.
  • API Key: This usually involves a key-value pair.
  • Basic Authentication: The traditional username and password method.
  • None: Select this if your API doesn't require any authentication.
• Headers (Optional): Some APIs need specific headers, usually key-value pairs, to provide more details about the impending action.
• HMAC Secret (Optional): HMAC is a symmetric key method for message signing. The provided secret will be used to sign the payload. The outcome signature will be sent in the x-descope-webhook-s256 header. The recipient service should use this secret to validate the payload's integrity and authenticity by verifying the supplied signature.
• Trust Any Certificate: By default, this option is turned off. If enabled, the client will overlook any certificate errors. While convenient for testing, it's crucial to remember that this is an insecure choice for production.
• Stream Audit Events: Options for which events (including tenant selection) will be sent to the external audit service:
  • Stream all audit events: Select this if you want to stream all audit events without filtering.
  • Stream filtered audit events only: Select this if you want to stream filtered audit events only. Filter by Key (Action or Tenants), then by Operator (Includes or Excludes), and finally by Value (Specific event).

3. View Audit Logs

Once you've configured the Audit Webhook Connector, your events will be sent to the API you specified. You can view the audit logs in the Audit page, which should match the events you receive in your API.

Use Cases

Roles Revoked From A User

As a security best practice, monitoring changes in the association of roles to users is crucial. As the identity provider, Descope can provide the role name as part of the "UserModified" audit event.

{
    "Change": {
        "removed_multi_tenant_roles": {
            "T2lTcqSm7f5GD8lRwCyo4aHvC6wo": [
                {
                    "id": "ROL2lKYLkbHroW5IntCAYTWPX86rRs",
                    "name": "test1"
                }
            ]
        }
    },
    "browser": "Chrome",
    "correlation_id": "2nQJ0PEyu5EHrMJChqNgPC4AeVp",
    "device": "Desktop",
    "os": "macOS",
    "osVersion": "10.15.7"
    ...
}

In this example the role name "test1" was removed from the user.

Flow Modified In Production

Monitoring when authentication flows are modified is critical for maintaining security and compliance. As the identity provider, Descope can provide the modified flow and associated user as part of the "FlowUpdated" audit event.

{
    "action": "FlowUpdated",
    "actor_id": "user@company.com",
    "occurred": "2024-01-15T14:30:22Z",
    "device": "Desktop",
    "browser": "Chrome",
    "correlation_id": "3mQK1PFzv6FIsNKDhrOhQD5BfWq",
    "data": {
        "flow_id": "FL2mLZYMlcIsqX6JouDBZUXQY97sSt",
        "flow_name": "Production Login Flow",
        "changes": {
            "modified_steps": ["email_verification", "mfa_setup"]
        }
    },
    "os": "macOS",
    "osVersion": "10.15.7"
    ...
}

In this example the user user@company.com modified the "Production Login Flow".

Project Setting Modified

Tracking changes to project-level configurations helps maintain security posture and compliance. Descope can provide the modified setting and associated actor as part of the "ProjectSettings" audit event.

{
    "action": "ProjectSettings",
    "actor_id": "admin@company.com",
    "occurred": "2024-01-15T16:45:18Z",
    "device": "Desktop",
    "browser": "Chrome",
    "correlation_id": "4nRL2QGzw7GJtOLEisPiRE6CgXr",
    "data": {
        "settings_changed": {
            "jwt_expiration": {
                "old_value": "3600",
                "new_value": "7200"
            },
            "allowed_origins": {
                "added": ["https://newapp.company.com"],
                "removed": []
            }
        }
    },
    "os": "Windows",
    "osVersion": "11"
    ...
}

In this example the user admin@company.com edited the "jwt_expiration" and "allowed_origins" settings.