Audit Events
Descope exposes a set of audit events that you can query through the Descope UI, and also using the SDK. The audit events document Descoper and also end-user activity, providing the visibility you need to ensure your Descope project is traced, monitored, and secured. We cover this topic more thoroughly in this article.
Audit Events
Note
When the action performed is considered sensitive, the type is defined as "Warning".
| Name | Type | More information |
|---|---|---|
| UserCreated | Information | If self registration is available, the "Actor ID" will be the same as the "User ID". Otherwise, the actor will be the Descoper or the used Management Key. |
| UsersCreated | Information | Multiple users created. |
| UserDeleted | Information | User deleted. |
| UserModified | Information | User modified. |
| UsersModified | Information | Multiple users modified. |
| UsersDeleted | Information | Multiple users deleted. |
| AccessKeyCreated | Information | Access key created. |
| AccessKeyDeleted | Information | Access key deleted. |
| AccessKeyModified | Information | Access key modified. |
| AccessKeysDeleted | Information | Multiple Access Keys Deleted. |
| LoginSucceed | Information | If impersonation was performed, the "Method" field will be "Impersonate". |
| LoginFailed | Warning | Reason for failure is shown inside the "Data" section, under "error_message". |
| LoginExceedMaxAttempts | Warning | Indicates that max attempts for user has been reached, user is disabled. |
| LoginStarted | Information | Indicates that a login process has started for multi-step authentication methods, like SSO, passkey, OTP and more. |
| LoginStartedFailed | Warning | Indicates that the LoginStarted event had failed. When the user did not complete the process correctly, or there is a problem with the authentication setup. |
| UserRefresh | Information | Only available in verbose mode. |
| ProjectDeleted | Warning | Project deleted. |
| PermissionCreated | Information | Permission created. |
| PermissionModified | Information | Permission modified. "Data" contains the "permission_id" that has been affected. |
| PermissionDeleted | Warning | Permission deleted. "Data" contains the "permission_id" that has been affected. |
| RoleCreated | Information | Role created. |
| RoleModified | Information | Role modified. "Data" contains the "role_id" that has been affected. |
| RolesDeleted | Warning | Role deleted. "Data" contains the "role_id" that has been affected. |
| RolesImported | Warning | Role imported. "Data" contains the "role_id" that has been affected. |
| ProjectSettings | Information | Project Settings modified. |
| TenantSettings | Information | Contains the tenant's ID in the "data" section. |
| MagicLinkSettings | Information | Magic Link related settings were changed. |
| EnchantedLinkSettings | Information | Enchanted Link related settings were changed. |
| OTPSettings | Information | OTP related settings were changed. |
| SAMLSettings | Information | SAML related settings were changed. |
| OAUTHSettings | Information | OAuth related settings were changed. |
| WebauthnSettings | Information | Webauthn related settings were changed. |
| TOTPSettings | Information | TOTP related settings were changed. |
| MessageProviderSettings | Information | Message Provider related settings were changed. |
| PasswordSettings | Information | Password Settings / Policy Changed. |
| CustomAttributeAdded | Information | Custom Attribute created. |
| CustomAttributeDeleted | Information | Custom Attribute deleted. |
| ConnectorModified | Information | A connector has been modified. |
| ConnectorCreated | Information | A connector has been created. |
| ConnectorDeleted | Information | A connector has been deleted. |
| CustomAttributesMissing | Error | Missing User / Tenant Custom Attribute. This indicates that the tenant or user selected does not have the required attribute that was used inside a flow / SDK. |
| TenantDeleted | Information | A tenant has been deleted. |
| TenantCreated | Information | A tenant has been created. |
| TenantCustomAttributeModified | Information | A Tenant's custom attribute has been modified. |
| TenantDomainModified | Information | A tenant's email domain has been modified. |
| TenantProvisioningModified | Information | A Tenant's Provisioning Settings has been modified. |
| TenantCustomAttributeAdded | Information | A Tenant's custom attribute has been added. |
| TenantCustomAttributeDeleted | Information | A Tenant's custom attribute has been deleted. |
| FlowsDeleted | Information | Contains the flow id & name that has been deleted in the data. |
| ThemeUpdated | Information | A theme has been updated. |
| FlowCreated | Information | Contains the flow id & name that has been created in the data. |
| FlowUpdated | Information | Contains the flow id & name that has been changed in the data. |
| CreatePassword | Information | A password has been created for a user. |
| ChangePassword | Information | A password has been changed for a user. |
| ExpirePassword | Information | A password has been expired for a user. |
| RemovePasskeys | Information | A passkey has been removed for a user. |
| SignKeyGeneratedRevoked | Information | The project's JWK (signing key for validating JWTs) has been rotated. |
| SSOConfigurationLinkGenerated | Information | SSO configuration link was generated. The generated link can be found inside data under "link". The link's expiration time can be found inside data under "expiration_time". |
| SSOConfigurationLinkRevoked | Information | SSO configuration link was revoked. The revoked link can be found inside data under "link". |
Fields
- Actor ID - contains the user that performed the action on the entity/ies in case it was done by a Descoper. If the action was performed by SDK, the "Actor ID" will contain the management key that is linked to the management action.
- User ID - The destination user that the action was performed on.
- Action - The action performed.
- Occurred - Date of occurrence.
- Device - The source device of the action, could be "Desktop", "Mobile", etc. Can also reflect the SDK that was used - e.g. "NodeJS".
- Method - The authentication method used.
- Remote Address - IP address (v4/v6) of the origin of the request.
- Login IDs - The primary identification for the authentication.
- Country - Origin of the request, most of the times, bound to the IP Address.
- Data - Holds the entire request sent to Descope's API in a JSON format. Displays raw information about the entire request including more details about the user, their device, the flow ID and execution ID, etc.
- SP SAML / OIDC request - Only For LoginStarted Event. Contains details of the SP request initiated by Descope for SSO.
- IdP SAML / OIDC response - Only for LoginSucceed / LoginFailed events. Contains the IdP response for SSO.
- Generated user from IdP SAML / OIDC response - Only for LoginSucceed. Contains the generated user object from the IdP response for SSO.
- Generated roles from IdP SAML / OIDC response - Only for LoginSucceed. Contains the generated roles from the IdP response for SSO.
Verbose
The "Verbose" option allows the "User Refresh" event to be audited, which is not audited by default.
Creating Custom Audit Events
At some point in your customer's lifecycle, you will need to add more and more events to support your product's transparency. With Descope, you can create audit events using the Management API.
Shipping Logs
You can use our out-of-the-box connectors to ship the audit event to different third-party applications, such as DataDog, Segment and HubSpot to orchestrate the user journey.
Audit Widget
When your project supports multiple tenants, Descope lets you hand over the audit logs to your customers using the audit log management widget. This widget helps you automate exposing this kind of audit logs to your customers by embedding an out-of-the-box component in your app. To read more about the widget, click here.
Correlating audit and troubleshooting logs
When debugging issues that users might face, it is crucial to know the context of the user’s actions, whether they tried to log in with a specific authentication method or even if they reached the point in the flow where OTP is involved. The troubleshooting logs contain a ‘Flow execution ID.’ Matching this value with the audit’s ‘correlation_id’ (inside the data field) is a powerful tool that provides you with the context of what the user did and where they encountered an issue, making your troubleshooting process more efficient