Transmitters

Overview

This guide connects a Shared Signals Framework (SSF) transmitter to Britive, and sends a test event end to end. The worked example uses caep.dev, a public SSF test transmitter. The same Britive settings apply to any transmitter.

What you’ll accomplish:

• Add the transmitter in Britive and map an event to a Britive action
• Point the transmitter at the Britive event endpoint
• Send a session-revoked event and confirm Britive logged the user out

Before You Begin

• A Britive user who can manage Shared Signals, for example through TenantAdminRole or SecurityAdminRole. See Permissions.
• A Britive user to receive the test event, with at least one active checkout so you can see the check-in
• A transmitter that can deliver events by push (HTTP POST). For the worked example, a caep.dev access token
• For the API steps, a Britive API token for the user who manages Shared Signals

How It Works

The transmitter sends each event to Britive as a signed Security Event Token (SET). The signed SET is the credential. There is no Authorization header.

    sequenceDiagram
    participant T as Transmitter
    participant B as Britive (/sse/events)
    participant U as Britive user
    T->>B: POST signed SET (application/secevent+jwt)
    B->>T: Fetch signing keys from the issuer's discovery document
    B-->>T: 202 Accepted
    B->>U: Run the mapped Britive action
    Note over B: Result recorded in Shared Signals > Events
  

Britive validates every SET before acting on it:

Britive finds the transmitter’s signing keys from jwks_uri, which it reads from {iss}/.well-known/openid-configuration or, if that is not available, {iss}/.well-known/ssf-configuration. The SET must be signed with RS256, RS384, RS512, ES256, ES384, or ES512.

Britive Actions

Each event you map runs one Britive action on the user. The actions are stacked: each one includes everything the action before it does.

• Force Checkin ends the user’s privileged access. The user stays signed in and can check out again.
• Force Logout also ends the user’s sessions, so the user must sign in again. It does not revoke the user’s API tokens.
• Disable User also disables the account. The user cannot sign in or use their API tokens until an administrator enables the account again.

For Force Logout and Disable User, Britive runs every part of the action even if an earlier part fails.

Recommended mappings:

Confirm the Event Endpoint Is Reachable

Send an empty request to your tenant’s event endpoint. The path is /sse/events, not /ssf/events.

curl -i -X POST https://<your-tenant-domain>/sse/events \
  -H "Content-Type: application/secevent+jwt" \
  --data "x"

A 400 response with Invalid SET format means the request reached the endpoint.

Add the Transmitter in Britive

Use the iss value exactly as it appears in the transmitter’s SETs. caep.dev sends https://ssf.caep.dev/ with a trailing slash. Its discovery document lists the issuer without the slash.

The Issuer URL cannot be changed later. To use a different URL, delete the transmitter and add it again.

Name:        caep.dev
Issuer URL:  https://ssf.caep.dev/

Event:   caep-session-revoked
Action:  Force Logout

curl -s "https://$BRITIVE_TENANT/api/ssf/admin/catalog" \
  -H "Authorization: TOKEN $BRITIVE_API_TOKEN" | jq '.actions'

ISSUER_ID=$(curl -s -X POST "https://$BRITIVE_TENANT/api/ssf/admin/issuers" \
  -H "Authorization: TOKEN $BRITIVE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"issuerUrl": "https://ssf.caep.dev/", "displayName": "caep.dev"}' \
  | jq -r '.issuerId')

curl -s -X PUT "https://$BRITIVE_TENANT/api/ssf/admin/issuers/$ISSUER_ID/mappings" \
  -H "Authorization: TOKEN $BRITIVE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mappings": [
      {
        "eventUri": "https://schemas.openid.net/secevent/caep/event-type/session-revoked",
        "action": "force logout"
      }
    ]
  }'

Send a Test Event

Delivery method:  Push (urn:ietf:rfc:8935)
Endpoint URL:     https://<your-tenant-domain>/sse/events
Audience:         https://<your-tenant-domain>

"sub_id": {
  "format": "email",
  "email": "test.user@example.com"
}

Verify

A 202 response from Britive means the event was accepted, not that the action succeeded. Check the result.

curl -s "https://$BRITIVE_TENANT/api/ssf/results?subjectValue=test.user@example.com&direction=RECEIVED" \
  -H "Authorization: TOKEN $BRITIVE_API_TOKEN" \
  | jq '.items[0] | {eventUri, action, status, outcome, receivedAt}'

Troubleshoot

Failed actions are not retried. Send the event again after fixing the cause.

Next Steps

• Map the other events your transmitter sends. See Britive Actions for the recommended mappings.
• Events: review received events and their results