Events in TideCloak: A Comprehensive Guide
This document provides an overview of the key events tracked by TideCloak and their descriptions. These events are useful for monitoring user activity and ensuring security within your system.
Login Events
These events track user authentication activities within the system.
| Event Name | Description |
|---|---|
| Login | A user successfully logs into the system. |
| Register | A new user registers an account. |
| Logout | A user logs out of the system. |
| Code to Token | A client exchanges an authorization code for a token (OAuth flow). |
| Refresh Token | A client refreshes an existing token to extend its validity. |
Use Cases:
- Login: Detect successful or failed login attempts to monitor potential unauthorized access.
- Logout: Track when users terminate their sessions for security and activity auditing.
- Token Events: Monitor token exchanges and refreshes for potential misuse of access tokens.
Account Management Events
These events are related to changes in user account settings.
| Event Name | Description |
|---|---|
| Update Profile | A user updates their account profile (e.g., name, contact info). |
| Update Email | A user changes their email address. |
| Update Password | A user updates their account password. |
| Send Password Reset | TideCloak sends a password reset email to the user. |
| Social Link | A user links their account to a social media provider. |
| Remove Social Link | A user unlinks their account from a social media provider. |
| Update TOTP | A user enables or updates two-factor authentication (TOTP). |
| Remove TOTP | A user disables two-factor authentication. |
| Verify Email | The user's email is successfully verified after registration or update. |
Use Cases:
- Update Profile: Track user-initiated changes to personal information.
- Password & Email Changes: Detect any suspicious or unauthorized changes to user credentials.
- TOTP Management: Ensure two-factor authentication (TOTP) settings are updated and managed securely.
Token and Session Events
These events help track token lifecycle and session management.
| Event Name | Description |
|---|---|
| Revoke Grant | A token or grant is revoked by the client or administrator. |
| Impersonate | An admin user impersonates another user to perform actions on their behalf. |
| Client Login | A client application logs into the system to authenticate users. |
Use Cases:
- Revoke Grant: Ensure that users or administrators revoke access tokens when no longer in use.
- Impersonation: Track any instance of an administrator impersonating a user to ensure it is authorized.
Error Events
These events capture failed or erroneous actions within the system, helping administrators troubleshoot issues.
| Event Name | Description |
|---|---|
| Failed Login | A user attempts to log in but fails due to incorrect credentials. |
| Failed Register | A user fails to register an account (e.g., invalid data). |
| Failed Code to Token | A client fails to exchange a code for a token. |
| Failed Refresh Token | A client fails to refresh a token. |
| Failed Update Profile | A user attempts to update their profile, but the update fails. |
Use Cases:
- Failed Logins: Detect multiple failed login attempts that may indicate a brute-force attack.
- Failed Token Exchanges: Track problems with the OAuth flow, such as misconfigured clients or expired codes.
Token Exchange and OAuth Events
These events provide insight into OAuth flows and how tokens are managed.
| Event Name | Description |
|---|---|
| Access Token Issued | A new access token is issued to a client after successful authentication. |
| Refresh Token Issued | A refresh token is issued, allowing clients to request new access tokens. |
| Token Revoked | An access or refresh token is revoked by the system or administrator. |
Use Cases:
- Token Lifecycle Monitoring: Track token issuance, usage, and revocation for secure token management.
- OAuth Troubleshooting: Detect issues in the OAuth flow by monitoring token exchanges and refresh actions.
Tide Events
TideCloak provides a comprehensive event system that tracks both Admin and User activities. These events are essential for monitoring system security, key management, and user interactions. Admin events typically involve critical system changes, such as key management and licensing, while user events focus on authentication and data security.
Admin Events
Admin events in TideCloak capture actions related to key management and licensing. These events are crucial for maintaining the integrity and security of the system, ensuring that cryptographic operations and licensing agreements are properly managed.
| Event Name | Description |
|---|---|
| TIDE_VENDOR_KEY - ACTION | This event occurs when the signing settings for the Vendor Key are updated. It signals changes to the cryptographic configurations that secure JWT signing. |
| TIDE_VENDOR_KEY - UPDATE | This event is typically observed during key rotation for security enhancements. Administrators should ensure the key rotation is conducted properly and that all systems are updated to trust the new VRK. |
| TIDE_VENDOR_KEY - CREATE | This event occurs when a new Vendor Verification Key (VVK) is generated, used in conjunction with the VRK for validating token signatures. |
| TIDE_LICENSE - UPDATE | Captures when a system license is renewed or created. This ensures proper compliance with licensing agreements. |
Use Cases:
- TIDE_VENDOR_KEY - ACTION: Monitor this event to ensure that any updates to signing settings are authorized and follow security policies. It is essential for maintaining the integrity of token signing.
- TIDE_VENDOR_KEY - UPDATE: This event is typically observed during key rotation for security enhancements. Administrators should ensure the key rotation is conducted properly and that all systems are updated to trust the new VRK.
- TIDE_VENDOR_KEY - CREATE: Monitor this event when expanding or updating the key management system. It's crucial to ensure that new verification keys are deployed correctly across all required systems.
- TIDE_LICENSE - UPDATE: Track this event to maintain active licenses and avoid service disruptions. Administrators can use it to verify license validity and ensure system compliance.
User Events
User events in TideCloak track user actions related to authentication and data protection. These events are essential for monitoring user access to resources and ensuring the encryption and decryption of sensitive data are securely managed.
| Event Name | Description |
|---|---|
| Authorize | This event is triggered when an access token is signed for a user following a successful authentication, granting them permission to access system resources. |
| Lock | Occurs when a user's data is encrypted to ensure its protection at rest, enhancing data security. |
| Unlock | This event happens when encrypted user data is decrypted, making it accessible for authorized actions or operations. |
Use Cases:
- Authorize: Track this event to monitor successful user authentications and ensure that only authorized users are issued access tokens.
- Lock: Monitor this event to ensure that sensitive user data is securely encrypted, especially when handling confidential information.
- Unlock: Track this event to verify that user data is decrypted only by authorized users and during necessary operations.
Best Practices for Monitoring Events
- Regular Monitoring: Regularly review login, logout, and account change events to detect unusual behavior.
- Alert Setup: Configure alerts for high-priority events like failed login attempts or unauthorized profile updates.
- Security Audits: Use event logs to perform periodic security audits and ensure compliance with security policies.
- Custom Logging: Consider adding custom events to track business-specific actions or security-critical events.