Shared Signals Framework (SSF) CAEP Events provide real-time security event streaming capabilities that enable Continuous Access Evaluation Protocol (CAEP) for dynamic access control decisions. Unlike traditional Systems of Record that synchronize static data, the CAEP Events integration receives real-time security events that signal changes in user security posture, device compliance, session status, and authentication context across your identity ecosystem.
The CAEP Events integration processes security events including session establishment and revocation, credential changes, assurance level modifications, device compliance changes, and token claims updates. These events provide immediate visibility into security state changes that can trigger real-time access control adjustments, enabling truly dynamic Zero Trust access control that responds to changing security conditions as they occur.
This integration is particularly valuable for organizations implementing Continuous Access Evaluation where access decisions must adapt in real-time to security events. By processing CAEP events from identity providers, security tools, and endpoint management systems, SGNL can immediately adjust access policies based on current security posture rather than relying solely on periodic authentication or static policy evaluation.
Important Event Retention Characteristics: Unlike traditional Systems of Record that maintain persistent data, CAEP events are retained in the SGNL graph for a maximum of 30 days. Additionally, each subject (as identified by the sub_id
in the SSF event) can have a maximum of 50 events associated with it - older events will automatically drop off when this limit is exceeded. This event-based retention model is designed to provide real-time security context while maintaining system performance.
To successfully configure the SSF CAEP Events integration, you need the ability to configure event sources and establish secure event delivery mechanisms.
Event Source Configuration: You need administrative access to the systems that will generate CAEP events, including identity providers, security tools, and endpoint management systems. This includes the ability to configure event destinations and event filtering.
Network and Security Configuration: You need the ability to configure network routing and security policies to enable event sources to deliver events to SGNL endpoints, including any necessary firewall rules, proxy configurations, or network security policies.
The CAEP Events integration supports several standardized event types that provide different aspects of security context:
Session Events: Session Established and Session Revoked events provide real-time visibility into user session lifecycle, including session creation with authentication context, IP addresses, and user agent information, as well as session termination events that can trigger immediate access revocation.
Credential Events: Credential Change events signal modifications to user authentication credentials including password changes, certificate updates, FIDO2 key registration, and other credential lifecycle events that may require access policy adjustments.
Security Posture Events: Assurance Level Change events indicate changes in authentication assurance levels, while Device Compliance Change events signal modifications to device security compliance status, both of which are critical for risk-based access control.
Token Events: Token Claims Change events indicate modifications to identity token claims and Session Presented events provide ongoing session activity context, enabling fine-grained access decisions based on current session characteristics.
Before configuring SGNL, you need to prepare your event sources to generate properly formatted CAEP events and deliver them securely to SGNL.
CAEP events follow the OpenID Shared Signals Framework specification and are delivered as JSON Web Tokens (JWTs) containing standardized event payloads. Each event includes standard JWT claims (issuer, audience, issued at, JWT ID) plus event-specific claims that provide security context.
Events must be properly structured according to the CAEP specification, with event types identified by their schema URIs (e.g., https://schemas.openid.net/secevent/caep/event-type/session-revoked
) and containing appropriate event-specific claims such as authentication context, device information, or credential details.
The CAEP Events integration supports two verification methods that can be used individually or in combination:
Bearer Token Authentication: Event sources authenticate using SGNL-generated bearer tokens included in the Authorization header. This method provides authentication for event sources and is managed through the “Require Authentication” setting in SGNL.
JWT Signature Verification: Event sources sign CAEP events using JSON Web Signature (JWS) with keys distributed through JWKS endpoints or well-known configuration endpoints. This method provides cryptographic verification of event authenticity and integrity and is managed through the “Require Signed Events” setting in SGNL.
Combined Verification: For maximum security, both authentication and signature verification can be required, ensuring that events include valid bearer tokens AND valid cryptographic signatures.
Unlike traditional SoR integrations that use authentication credentials to pull data, the CAEP Events integration is configured as an event push system that receives events from external sources.
Delivery Method: The integration is pre-configured with deliveryMethod: "eventPush"
and pushType: "SSF"
, indicating that it receives Shared Signals Framework events through push delivery rather than polling for data.
Event Endpoint: SGNL will provide a specific endpoint URL where event sources should deliver CAEP events. This endpoint is configured in the SoR settings and must be shared with all systems that will send CAEP events to SGNL.
Configure how SGNL will verify incoming CAEP events using the Event Transmitter Verification section:
Require Authentication: Enable this option to require that event sources authenticate to SGNL when delivering events.
Require Signed Events: Enable this option to require that events are cryptographically signed by the event source.
Combined Verification: You can enable both authentication and signature verification for maximum security. When both are enabled, events must include valid bearer tokens AND valid cryptographic signatures to be processed.
Configure which CAEP event types should be processed and how they should be handled:
Supported Event Types: The integration includes pre-configured entities for standard CAEP event types including SessionRevoked, TokenClaimsChange, CredentialChange, AssuranceLevelChange, DeviceComplianceChange, SessionEstablished, and SessionPresented.
Event Entity Selection: Enable synchronization for the event types that are relevant to your access control policies. Each event type captures different security context and may be used for different policy scenarios.
Custom Attribute Configuration: Use JSON Path expressions to extract additional attributes from event payloads beyond the standard pre-configured attributes. This allows you to process organization-specific event claims or custom security context.
Each CAEP event type is represented as a separate entity within SGNL, with attributes that capture both standard JWT claims and event-specific security context.
Standard Event Attributes: All CAEP events include standard attributes such as event ID (jti), subject identifier (typically email), issuer, audience, issued at timestamp, and SGNL processing metadata including raw event payload and processing timestamp.
Event-Specific Context: Each event type includes attributes specific to the security context it represents. For example, SessionEstablished events include IP addresses, user agent fingerprints, and authentication method references, while CredentialChange events include credential type, change type, and credential-specific identifiers.
Security Context Attributes: Events include optional security context such as event timestamps, initiating entities, and human-readable reason descriptions that provide additional context for access control decisions.
Raw Event Preservation: The integration preserves the complete raw event payload and JWT token, enabling forensic analysis and custom processing of event data that may not be captured in the standard attribute mapping.
After configuring the SSF CAEP Events integration, systematic testing ensures that events are being received, authenticated, and processed correctly.
As recommended in the integration notes, use caep.dev to test your CAEP Events integration:
Once events are being received successfully, you can monitor and validate event processing through multiple interfaces:
Event Stream Logs: Access comprehensive event processing logs through Logs → Event Streams in the SGNL console:
DataLens Analysis: Use DataLens to explore your CAEP event data:
Note: Remember that events are retained for a maximum of 30 days and each subject can have up to 50 events, so DataLens queries will reflect this retention model.
Events Not Received: If SGNL is not receiving events, verify that event sources are configured with the correct SGNL endpoint URL and that network connectivity exists between event sources and SGNL. Check firewall rules, proxy configurations, and DNS resolution.
Authentication Failures: If events are being rejected due to authentication errors, verify that JWT signature verification is configured correctly with the appropriate JWKS endpoints or that bearer tokens are valid and properly included in event delivery.
Event Format Errors: If events are being rejected due to format issues, verify that event sources are generating properly formatted CAEP events according to the OpenID specification. Use caep.dev to validate event structure and format.
Key Resolution Problems: If signature verification is failing, verify that JWKS endpoints are accessible from SGNL and that they contain the correct public keys. Check that key IDs in event signatures match keys available in the JWKS endpoint.
Signature Validation Errors: If signature validation is failing for correctly formatted events, verify that event sources are using the correct signing algorithms and that the private keys used for signing correspond to the public keys available in the JWKS endpoint.
Key Refresh Issues: If signature verification intermittently fails, check that SGNL is properly refreshing signing keys from JWKS endpoints and that key rotation is being handled correctly by both event sources and SGNL.
Missing Event Attributes: If expected event attributes are not being populated, verify that the event payloads contain the expected claims and that JSON Path expressions are correctly configured to extract the desired attributes. Review the SSF Documentation for further information.
Custom Attribute Configuration: If custom attributes configured using JSON Path are not being extracted, verify the JSON Path expressions against actual event payloads and ensure that the attribute paths correctly navigate the event structure.
Event Source Compatibility: Different identity providers and security tools may generate CAEP events with variations in structure or claims. If events from specific sources are not processing correctly, review the event structure and consider custom attribute configuration to handle source-specific variations.
Time Synchronization: CAEP events include timing information that may be critical for access control decisions. Ensure that event sources and SGNL have synchronized clocks to avoid issues with event timing and policy evaluation.
Event Deduplication: Some event sources may send duplicate events. SGNL will disallow event duplication where duplicate JTIs are presented.
Once your SSF CAEP Events integration is successfully configured and receiving events, you can leverage real-time security events in dynamic SGNL policies that respond immediately to changing security conditions.
Real-Time Session Management: Use SessionEstablished and SessionRevoked events to create policies that immediately respond to session changes. When a session is revoked due to security concerns, policies can instantly restrict access across all related systems, not just the originating system.
Credential-Based Access Control: Leverage CredentialChange events to create policies that respond to authentication credential modifications. Password changes, certificate updates, or FIDO2 key registrations can trigger immediate policy re-evaluation and access adjustments.
Device Compliance-Driven Policies: Use DeviceComplianceChange events to create dynamic policies that adjust access based on real-time device security posture. When a device becomes non-compliant, policies can immediately restrict access to sensitive resources until compliance is restored.
Authentication Assurance Policies: Leverage AssuranceLevelChange events to create policies that adjust access requirements based on current authentication assurance levels. Lower assurance levels can trigger additional authentication requirements or restrict access to high-value resources.
Risk-Based Dynamic Access: Use TokenClaimsChange events to respond to modifications in user risk scores, group memberships, or other identity attributes that affect access policies. Changes in user context can immediately trigger policy re-evaluation across all connected systems.
Session Activity Monitoring: Leverage SessionPresented events to create policies that consider ongoing session activity patterns. Unusual session behavior or access from unexpected locations can trigger additional verification requirements or access restrictions.
Cross-System Security Coordination: Use CAEP events to coordinate security responses across multiple systems. A security event in one system can immediately trigger policy adjustments in related systems, creating a unified security response across your entire technology ecosystem.
Audit and Compliance Integration: Leverage the comprehensive event data including raw payloads and processing timestamps to create audit trails that demonstrate real-time security response capabilities and compliance with continuous monitoring requirements.
For comprehensive guidance on creating policies with CAEP event data, refer to the SGNL Policy Management documentation. For understanding how to use JSON Path expressions to extract custom attributes from event payloads, review the JSON Path guide.