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
audienceyou registered. - Events: the CAEP event types the stream accepts.
- Subject format: one your
subject_matchsetting resolves, usuallyemail.
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:
- Rejects a body over 64 KB.
- Reads the unverified
issonly to find the registered stream. An unknown issuer is refused withinvalid_issuer; a stream that is notenabledwithaccess_denied. - 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.
- Requires
issandaudto match the stream, andiatwithin the last 5 minutes, allowing 60 seconds of clock drift in either direction. SETs carry noexp, so this is the only freshness limit. - Requires the JWS header
typto besecevent+jwt(orapplication/secevent+jwt). - Requires a
jtiand aneventsclaim 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-changeis 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