Skip to content

Receive shared signals from your identity provider

AtmanID can act as a receiver for the OpenID Shared Signals Framework (SSF). A transmitter, typically your identity provider, pushes a signed Security Event Token (SET) to AtmanID when something changes about a person’s session or credentials, and AtmanID ends or re-challenges that person’s AtmanID sessions. This is push delivery (RFC 8935) only.

In the examples, $ATMANID_BASE_URL is the address of your AtmanID tenant.

What it does with each event

AtmanID acts on the five event types of OpenID CAEP 1.0, and only on those your stream lists as accepted. A new stream accepts only session-revoked unless you list more.

CAEP event type Payload value What AtmanID does
session-revoked (any) Suspends every live AtmanID session of the person.
credential-change change_type revoke or delete Suspends every live session.
credential-change change_type create or update Nothing.
assurance-level-change change_direction decrease Requires a fresh challenge on every active session.
assurance-level-change change_direction increase Nothing.
device-compliance-change current_status not-compliant Requires a fresh challenge on every active session.
device-compliance-change current_status compliant Nothing.
token-claims-change Nothing. It can be listed but has no action: AtmanID does not use the transmitter’s tokens for authorisation.

The full event type URIs are https://schemas.openid.net/secevent/caep/event-type/ followed by the name in the first column.

A suspended session is not resumed by a later challenge; the person signs in again. Suspending and re-challenging are audited as SESSION_SUSPENDED_BY_CAEP and SESSION_STEP_UP_BY_CAEP against the person, with the event type, the number of sessions affected and the transmitter’s issuer, even when the person had no live session.

RISC events (account disabled, credential compromise and the rest of the RISC profile) are not accepted. A stream can list only the CAEP types above, and a SET carrying any other event type is acknowledged and recorded as unsupported, with no action.

The SSF verification event is always accepted, whatever the stream lists, and recorded as verified, so you can test the connection.

How the person is found

The event’s subject (RFC 9493 subject identifier) is matched to one AtmanID user. The stream’s subject_match setting decides how:

subject_match Subject formats it resolves
email email, matched case-insensitively against the user’s email
external_id iss_sub (its iss must equal the stream’s issuer), opaque (id) and account (uri, with any acct: prefix removed), matched against the external id of an account in one application you name, synced by its connector and correlated to a user
auto (the default) The external id first, when the stream names an application, then the email

If two users or two accounts match, AtmanID refuses to choose and does nothing. An event whose subject cannot be resolved is recorded as unresolved_subject with the reason; the transmitter is still told it was accepted, because it did nothing wrong.

Register a stream

There is no page in the app for this yet, and AtmanID does not implement the SSF stream-management API, so a transmitter cannot register itself. A tenant owner or super admin registers each transmitter with the admin API while signed in to AtmanID: POST $ATMANID_BASE_URL/api/admin/ssf/inbound-streams.

Field Required Meaning
issuer Yes The transmitter’s iss value, exactly. One issuer can be registered by one tenant on the whole platform. It cannot be changed later.
jwks_uri Yes Where AtmanID fetches the transmitter’s public keys. Must be a public https address.
audience Yes The value the transmitter puts in aud. Choose a string that names your AtmanID tenant and give the same string to the transmitter.
allowed_algs No Asymmetric algorithms only: RS, PS or ES with 256, 384 or 512. Default RS256, ES256, PS256.
events_accepted No Up to 10 CAEP event type URIs. Default: session-revoked only.
subject_match No auto (default), email or external_id.
application_id For external_id The AtmanID application whose synced accounts hold the external ids.
{
"issuer": "https://example.okta.com",
"jwks_uri": "https://example.okta.com/oauth2/v1/keys",
"audience": "atmanid-acme",
"events_accepted": [
"https://schemas.openid.net/secevent/caep/event-type/session-revoked",
"https://schemas.openid.net/secevent/caep/event-type/credential-change"
],
"subject_match": "email"
}

The values above are placeholders: take the issuer and key set URL from your transmitter’s SSF configuration. AtmanID refuses a stream it could never use (a key set URL it will not fetch, a symmetric algorithm, an unknown event type, external_id without an application, or another tenant’s application) with 400 when you save it, rather than storing it.

PATCH /api/admin/ssf/inbound-streams/{id} changes any field except issuer, and sets status to enabled, paused or disabled. DELETE removes the stream. Creating, changing and deleting a stream are audited. GET /api/admin/ssf/inbound-streams lists streams with their last error and rejection count (compliance officers, CISOs, tenant owners and super admins can read it), and GET /api/admin/ssf/inbound-streams/{id}/events lists what arrived, filterable by outcome.

Configure the transmitter

In your identity provider’s shared signals settings, create a push stream to AtmanID with:

  • Delivery method: push, urn:ietf:rfc:8935.
  • Endpoint URL: $ATMANID_BASE_URL/api/ssf/receive.
  • Audience: the audience you registered.
  • Events: the CAEP event types the stream accepts.
  • Subject format: one your subject_match setting resolves, usually email.

The endpoint takes no bearer token or shared secret. The SET’s signature is the only authentication. Okta and Microsoft Entra ID expose shared signals in different places and not on every plan; check their documentation for where to create a receiver stream. Then ask the transmitter to send a verification event and confirm it appears in the stream’s events with the outcome verified.

How a SET is verified

For each POST to /api/ssf/receive, AtmanID:

  1. Rejects a body over 64 KB.
  2. Reads the unverified iss only to find the registered stream. An unknown issuer is refused with invalid_issuer; a stream that is not enabled with access_denied.
  3. Fetches the stream’s key set (cached up to 10 minutes, refetched at most every 30 seconds for an unknown key id, 5-second timeout) and verifies the signature with the stream’s algorithms only.
  4. Requires iss and aud to match the stream, and iat within the last 5 minutes, allowing 60 seconds of clock drift in either direction. SETs carry no exp, so this is the only freshness limit.
  5. Requires the JWS header typ to be secevent+jwt (or application/secevent+jwt).
  6. Requires a jti and an events claim with 1 to 10 events, each a JSON object.

Each event is then recorded under its issuer, jti and event type before it is acted on, so a replay of the same SET is acknowledged and ignored.

Responses

Status Meaning What the transmitter should do
202, empty body Verified. Includes events with no action, an unsupported type or an unresolved subject. Nothing.
400 { "err", "description" } The SET is defective: invalid_request, invalid_issuer, invalid_audience, invalid_key, authentication_failed or access_denied. Do not resend it.
429 Rate limited: 60 requests a minute per client IP. Retry after Retry-After.
503 { "error" } AtmanID could not finish: its database or your key set was unreachable, or an event could not be applied. Resend. Events already applied are recognised and skipped.

Two deliveries of the same SET at the same moment can produce a 503 for one of them; its resend is then acknowledged.

Rejections increase the stream’s rejection count and set its last error, and an accepted SET resets the count. The count never pauses or disables a stream: anyone who knows the issuer can send bad requests, so only a person changes a stream’s status.

Limits and what is not built yet

  • Push delivery only. Poll delivery (RFC 8936) is not supported.
  • No SSF stream-management API and no transmitter configuration discovery: streams are registered through AtmanID’s admin API, and there is no page in the app for them.
  • CAEP only. RISC events are not accepted.
  • token-claims-change is accepted on a stream but never acted on.
  • The action is limited to AtmanID’s own sessions. An inbound event does not suspend the person, change their access, or open revocation tickets.
  • A SET must arrive within 5 minutes of its iat, and carry at most 10 events and 64 KB.

AtmanID also transmits shared signals to other receivers. That is configured separately, and $ATMANID_BASE_URL/api/ssf/jwks is the key set for SETs AtmanID sends; it plays no part in receiving.

© AtmanID · Privacy