Creating and Configuring an SSF CAEP Event System of Record

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.

Prerequisites

  • Understanding of Shared Signals Framework (SSF) and Continuous Access Evaluation Protocol (CAEP)
  • Systems capable of generating and transmitting SSF CAEP events (identity providers, security tools, endpoint managers)
  • Network connectivity for event push delivery to SGNL endpoints
  • Understanding of which CAEP event types are most relevant for your access control policies

Permissions Required

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.

Understanding CAEP Event Types

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.

Configuring Event Sources

Before configuring SGNL, you need to prepare your event sources to generate properly formatted CAEP events and deliver them securely to SGNL.

Event Format and Structure

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.

Authentication Methods

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.

Configuring SGNL

Setting Up the SSF CAEP Events System of Record

  1. Access SGNL Console: Login to the SGNL Console with appropriate administrative privileges
  2. Navigate to Identity Data Fabric: From the left menu, select “Identity Data Fabric”
  3. Add New System of Record: Click “Add System of Record” or “Add” to open the SoR catalog
  4. Select CAEP Events Template: Locate and click on “CAEP Events” in the SGNL SoR Catalog to open the configuration screen with pre-populated event streaming settings

Event Streaming Configuration

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.

Event Transmitter Verification

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.

  1. Check “Require Authentication”: Enable authentication requirements for incoming events
  2. Add Token: Click “Add Token” to generate a new SGNL authentication token
  3. Configure Event Sources: Provide the generated token to your event sources to include in the Authorization header as a Bearer token when sending events

Require Signed Events: Enable this option to require that events are cryptographically signed by the event source.

  1. Check “Require Signed Events”: Enable signature verification for incoming events
  2. Add Signing Configuration: Click “Add” to configure JWT signature verification settings
  3. Configure Key Source: Specify how SGNL should obtain public keys for signature verification:
    • JWKS Endpoint: Provide the URL of a JSON Web Key Set endpoint that contains the public keys used to sign events
    • Well-Known Configuration: Provide the URL of an OpenID Connect well-known configuration endpoint that references the JWKS endpoint

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.

Event Processing Configuration

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.

Understanding CAEP Event Entity Structure

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.

Testing and Verification

After configuring the SSF CAEP Events integration, systematic testing ensures that events are being received, authenticated, and processed correctly.

Initial Configuration Test

  1. Save Configuration: Click “Continue” to save your CAEP Events System of Record configuration
  2. Verify Endpoint: SGNL will provide the event delivery endpoint URL that must be configured in your event sources
  3. Check Authentication Setup: Verify that JWT signature verification or bearer token authentication is properly configured based on your chosen authentication methods
  4. Review Event Types: Confirm that the relevant CAEP event entities are enabled for the event types you expect to receive

Event Source Configuration

  1. Configure Event Delivery: Update your event sources (identity providers, security tools, endpoint managers) to deliver CAEP events to the SGNL endpoint URL
  2. Set Authentication Method: Configure event sources to use either JWT signing with your established keys or bearer token authentication with your SGNL-issued tokens
  3. Test Connectivity: Verify that event sources can successfully connect to the SGNL endpoint and that network routing is properly configured
  4. Validate Event Format: Ensure that event sources are generating properly formatted CAEP events according to the OpenID specification

Event Processing Verification

  1. Send Test Events: Generate test CAEP events from your event sources to verify end-to-end event processing
  2. Monitor Event Receipt: Use SGNL’s interface to confirm that events are being received and processed successfully
  3. Verify Authentication: Confirm that events are properly authenticated using your configured signature verification or bearer token methods
  4. Check Event Parsing: Verify that event attributes are being correctly extracted from event payloads and that standard and custom attributes are populated as expected

Use CAEP.dev for Testing

As recommended in the integration notes, use caep.dev to test your CAEP Events integration:

  1. Generate Test Events: Use caep.dev to generate properly formatted CAEP events for testing purposes
  2. Validate Event Structure: Verify that your event sources generate events that match the expected CAEP specification format
  3. Test Authentication: Use caep.dev to test both JWT signature verification and bearer token authentication methods
  4. Verify Event Processing: Send test events through caep.dev to confirm that SGNL processes them correctly and extracts the expected attributes

Monitor Event Processing with DataLens and Event Stream Logs

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:

  1. Monitor Event Receipt: View real-time logs showing events being received from your event sources
  2. Verify Event Acceptance: Confirm that events are being accepted and stored successfully in the SGNL graph
  3. Check Failed Events: Identify events that failed processing and review failure reasons
  4. Examine Message Context: Inspect detailed event content, headers, and processing metadata
  5. Troubleshoot Issues: Use log details to diagnose authentication failures, signature verification problems, or event format issues

DataLens Analysis: Use DataLens to explore your CAEP event data:

  1. Query Recent Events: Search for recent CAEP events to verify that they are being processed and stored correctly
  2. Analyze Event Patterns: Review event frequency, types, and sources to understand your security event landscape
  3. Validate Event Context: Confirm that security context such as IP addresses, authentication methods, and device compliance information is being captured accurately
  4. Test Event Filtering: If you’ve configured custom attributes using JSON Path, verify that additional event data is being extracted correctly

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.

Troubleshooting

Event Delivery Issues

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.

JWT Signature Verification Issues

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.

Event Processing Challenges

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.

Integration-Specific Issues

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.

Integration with SGNL Policies

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.