IAM Identity Domains SSF Transmitter

Use Oracle Cloud Infrastructure Identity and Access Management (OCI IAM) Identity Domains as a Shared Signals Framework (SSF) transmitter to configure streams, verify receivers, and deliver signed Security Event Tokens.

This document describes a proposed contract that might change before release. The examples use https://idcs.example.com and fictional identifiers. These values aren't credentials or live endpoints.

Overview

IAM Identity Domains (referred to as IAM in this guide) acts as a Shared Signals Framework (SSF) Event Transmitter for an identity domain. It exposes transmitter discovery metadata, manages SSF streams, and pushes signed Security Event Tokens (SETs) to configured receivers.

The event set includes CAEP session-revoked and credential-change. A receiver creates one or more streams, selects the event types it wants, and provides an HTTPS endpoint. When the feature is available for the domain, IAM sends matching SETs to each enabled stream.

Before You Begin

Before integrating a receiver, confirm that SSF transmitter access is available for the identity domain and that the final Admin API contract has been published. Then:

Obtain a control-plane access token with the approved stream-management scope. See Authorization Model.
Deploy an HTTPS receiver endpoint that can accept a compact SET and return the documented success response.
Read discovery metadata and retrieve the advertised JWKS so the receiver can validate signed SETs.
List existing streams, then create or update the intended stream configuration.
Trigger verification and confirm at the receiver that the echoed state value is received and validated before relying on live-event delivery.

Source Event Mappings to CAEP Events

The following IAM source event is mapped to the CAEP Session Revoked event:
- sso.session.delete.success
The following IAM source events are mapped to the CAEP Credential Change event:
- admin.user.password.change.success
- admin.user.password.reset.success
- admin.me.password.change.success
- admin.me.password.reset.success
- admin.user.mfa.reset.success

Supported CAEP Events


Event	URI	OCI IAM Source Coverage
Session revoked	https://schemas.openid.net/secevent/caep/event-type/session-revoked	Implementation-derived source coverage; pending customer-contract confirmation.
Credential change	https://schemas.openid.net/secevent/caep/event-type/credential-change	Implementation-derived source coverage; pending customer-contract confirmation.

Under the proposed contract, unsupported event types must not be supplied in events_requested.

Authorization Model

The proposed stream-management APIs use an OAuth 2.0 bearer access token. The exact scope-to-operation mapping below requires generated-API-contract confirmation before publication:


Scope	Permitted Operations
ssf.read	List and retrieve SSFStreams.
ssf.manage	Create, update/replace, delete, change `status`, and trigger verification.

Discovery Metadata

When the feature is available, call the public discovery endpoint to obtain domain-specific transmitter URLs and signing-key location.

GET /.well-known/ssf-configuration HTTP/1.1
Host: idcs.example.com
Accept: application/json

Illustrative response:

{
  "issuer": "https://<identity-domain-host>",
  "configuration_endpoint": "https://<identity-domain-host>/admin/v1/SSFStreams",
  "verification_endpoint": "https://<identity-domain-host>/admin/v1/SSFStreamVerifier",
  "delivery_methods_supported": [
    "urn:ietf:rfc:8935"
  ],
  "spec_version": "1_0-ID1",
  "authorization_schemes": [
    {
      "issuer": "https://<identity-domain-host>",
      "authorization_server": "https://<identity-domain-host>/oauth2/v1/token",
      "spec_urn": "urn:ietf:rfc:6750",
      "name": "oauth-bearer-token",
      "scopes_supported": [
        "ssf.read",
        "ssf.manage"
      ]
    }
  ],
  "default_subjects": "ALL",
  "jwks_uri": "https://<identity-domain-host>/admin/v1/SigningCert/jwk"
}

Stream Configuration Contract

SSFStreams is a proposed SCIM-style Admin resource. IAM is expected to permit multiple streams per identity domain.


Field	Direction	Meaning
`stream_id`	Read-only	IAM-assigned canonical stream identifier.
`iss`	Read-only	Issuer used in SETs for the stream.
`aud`	Create; immutable after creation	One or more receiver audience values used in SET aud.
`delivery`	Required, read/write	Contains `method` and endpoint_url.
`delivery.method`	Required	Must be urn:ietf:rfc:8935.
`delivery.endpoint_url`	Required	HTTPS receiver endpoint used for both live `delivery` and verification.
`events_requested`	Required, read/write	Event URIs requested by the stream; only supported values are accepted.
`events_delivered`	Read-only	OCI IAM-derived intersection of requested and supported events.
`events_supported`	Read-only	Event URIs supported by OCI IAM.
`format`	Read-only	iss_sub for CAEP user events.
`status`	Required, read/write	ENABLED or DISABLED.

aud mutability and endpoint validation behavior shown here are implementation-derived and require API-contract confirmation.

Stream API Operations

The management sequence is: discover the transmitter, list or retrieve existing streams, create or update a stream, verify it, and then monitor receiver delivery. Endpoint paths and response codes in the following examples are illustrative until the external Admin API contract is approved.


Operation	Proposed Method and Path	Intended Scope	Expected Outcome
Listing streams	GET /admin/v1/SSFStreams	ssf.read	Stream collection
Retrieving a stream	GET /admin/v1/SSFStreams/{`id`}	ssf.read	Stream representation
Creating a stream	POST /admin/v1/SSFStreams	ssf.manage	Created stream
Replacing or patch a stream	PUT or PATCH /admin/v1/SSFStreams/{`id`}	ssf.manage	Updated stream
Deleting a stream	DELETE /admin/v1/SSFStreams/{`id`}	ssf.manage	Deletion accepted
Verifying a stream	POST /admin/v1/SSFStreamVerifier	ssf.manage	Verification accepted

Retrieving the SSF Stream Configuration

Listing Streams

Use this operation to retrieve the stream collection.

GET /admin/v1/SSFStreams HTTP/1.1
Host: idcs.example.com
Authorization: Bearer <ssf.read-access-token>
Accept: application/json

Retrieving a Stream

Use this operation to retrieve one stream, including its status and delivery configuration.

GET /admin/v1/SSFStreams/9d3f1fb1a7d24f2aa6d3a8d0c6f7b901 HTTP/1.1
Host: idcs.example.com
Authorization: Bearer <ssf.read-access-token>
Accept: application/json

Illustrative Response

[
  {
    "schemas": [
      "urn:ietf:params:scim:schemas:oracle:idcs:SSFStream"
    ],
    "stream_id": "<stream-id>",
    "iss": "https://<identity-domain-host>",
    "aud": [
      "<receiver-audience>"
    ],
    "delivery": {
      "method": "urn:ietf:rfc:8935",
      "endpoint_url": "https://<receiver-host>/<receiver-events-path>"
    },
    "events_requested": [
      "https://schemas.openid.net/secevent/caep/event-type/session-revoked",
      "https://schemas.openid.net/secevent/caep/event-type/credential-change"
    ],
    "events_delivered": [
      "https://schemas.openid.net/secevent/caep/event-type/session-revoked",
      "https://schemas.openid.net/secevent/caep/event-type/credential-change"
    ],
    "events_supported": [
      "https://schemas.openid.net/secevent/caep/event-type/session-revoked",
      "https://schemas.openid.net/secevent/caep/event-type/credential-change"
    ],
    "format": "iss_sub",
    "min_verification_interval": 0,
    "status": "ENABLED"
  }
]

Creating a Stream

Use this operation to create one stream.

POST /admin/v1/SSFStreams HTTP/1.1
Host: idcs.example.com
Authorization: Bearer <ssf.manage-access-token>
Content-Type: application/json

{
  "schemas": ["urn:ietf:params:scim:schemas:oracle:idcs:SSFStream"],
  "aud": ["https://receiver.example.com/ssf"],
  "delivery": {
    "method": "urn:ietf:rfc:8935",
    "endpoint_url": "https://receiver.example.com/ssf"
  },
  "events_requested": [
    "https://schemas.openid.net/secevent/caep/event-type/session-revoked",
    "https://schemas.openid.net/secevent/caep/event-type/credential-change"
  ],
  "status": "ENABLED"
}

201 response:

{
  "id": "9d3f1fb1a7d24f2aa6d3a8d0c6f7b901",
  "stream_id": "urn:ocid:stream:9d3f1fb1a7d24f2aa6d3a8d0c6f7b901",
  "iss": "https://idcs.example.com",
  "aud": ["https://receiver.example.com/ssf"],
  "delivery": {
    "method": "urn:ietf:rfc:8935",
    "endpoint_url": "https://receiver.example.com/ssf"
  },
  "events_requested": [
    "https://schemas.openid.net/secevent/caep/event-type/session-revoked",
    "https://schemas.openid.net/secevent/caep/event-type/credential-change"
  ],
  "events_delivered": [
    "https://schemas.openid.net/secevent/caep/event-type/session-revoked",
    "https://schemas.openid.net/secevent/caep/event-type/credential-change"
  ],
  "events_supported": [
    "https://schemas.openid.net/secevent/caep/event-type/session-revoked",
    "https://schemas.openid.net/secevent/caep/event-type/credential-change"
  ],
  "format": "iss_sub",
  "min_verification_interval": 300,
  "status": "ENABLED"
}

Replacing a Stream

Use PUT to replace mutable stream configuration. Include the immutable aud value from the current resource.

PUT /admin/v1/SSFStreams/9d3f1fb1a7d24f2aa6d3a8d0c6f7b901 HTTP/1.1
Host: idcs.example.com
Authorization: Bearer <ssf.manage-access-token>
Content-Type: application/json

{
  "schemas": ["urn:ietf:params:scim:schemas:oracle:idcs:SSFStream"],
  "aud": ["https://receiver.example.com/ssf"],
  "delivery": {
    "method": "urn:ietf:rfc:8935",
    "endpoint_url": "https://receiver.example.com/ssf/v2"
  },
  "events_requested": [
    "https://schemas.openid.net/secevent/caep/event-type/session-revoked"
  ],
  "status": "DISABLED"
}

PATCH support, update timing, and whether re-verification is required after a delivery change remain pending API and product confirmation.

Updating a Stream

Use PATCH to update supported stream properties, such as status.

PATCH /admin/v1/SSFStreams/{id} HTTP/1.1
Authorization: Bearer <ssf.manage-access-token>
Content-Type: application/json

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "path": "delivery",
      "value": {
        "method": "urn:ietf:rfc:8935",
        "endpoint_url": "https://<receiver-host>/<receiver-events-path>"
      }
    },
    {
      "op": "replace",
      "path": "status",
      "value": "ENABLED"
    }
  ]
}

Getting or Updating Stream Status

A stream is either ENABLED or DISABLED. Enabled streams are eligible to receive matching events; disabled streams aren't eligible for delivery. Read status through the stream resource and change it with the normal stream update operation.

For example, this SCIM patch disables the stream:

PATCH /admin/v1/SSFStreams/9d3f1fb1a7d24f2aa6d3a8d0c6f7b901 HTTP/1.1
Host: idcs.example.com
Authorization: Bearer <ssf.manage-access-token>
Content-Type: application/json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [{"op": "replace", "path": "status", "value": "DISABLED"}]
}

Verifying a Stream

See Verification Flow.

Deleting a Stream

Delete a stream when it's no longer needed. Disable a stream first when you need an explicit delivery stop before deletion.

DELETE /admin/v1/SSFStreams/9d3f1fb1a7d24f2aa6d3a8d0c6f7b901 HTTP/1.1
Host: idcs.example.com
Authorization: Bearer <ssf.manage-access-token>

The final deletion semantics, response code, and any restoration behavior remain pending API-contract confirmation. Administrators should disable a stream before deleting it when they need an explicit delivery stop before the delete operation completes.

Stream Lifecycle and Status

A stream is either:

ENABLED: Intended to be eligible for delivery when it requests the mapped event type and the feature is available for the domain.
DISABLED: Not eligible for delivery.

The intended behavior is that disabled and deleted streams aren't used for future delivery. Exact timing and in-flight delivery behavior remain pending confirmation.

Verification Flow

Verification is recommended and operates independently of the stream lifecycle. Send an opaque state value; \IAM includes it in the verification SET delivered to the receiver. A 204 No Content response means the verification was accepted or queued, not necessarily delivered synchronously.n.

An administrator calls the verification endpoint with ssf.manage.
IAM is expected to validate the request and accept an asynchronous handoff.
The delivery path is expected to post a signed verification SET to delivery.endpoint_url.
A request-acceptance response doesn't by itself prove receiver delivery; the receiver must validate the verification SET and its echoed state value.

POST /admin/v1/SSFStreamVerifier HTTP/1.1
Host: idcs.example.com
Authorization: Bearer <ssf.manage-access-token>
Content-Type: application/json

{
  "stream_id": "urn:ocid:stream:9d3f1fb1a7d24f2aa6d3a8d0c6f7b901",
  "state": "receiver-check-20260722"
}

The state value is intended to be opaque receiver-supplied data and echoed in the verification event body. The final verification interval, throttling behavior, and response codes remain pending confirmation.

SET Delivery Behavior

OCI IAM is intended to construct a signed SET for each matching stream and source event, then send it over HTTPS to the stream's delivery.endpoint_url.

The HTTP content type is application/secevent+jwt.
Receiver responses and redirect behavior need API-contract confirmation.
A stream is intended to be enabled and subscribed to the mapped event type when delivery is attempted.
Multi-stream delivery behavior remains pending confirmation.

SET Signing and JWKS

IAM is expected to reuse its existing tenant/IDCS JWT signing infrastructure rather than introduce a separate SSF signing key.

Receivers must:

Obtain jwks_uri from SSF discovery.
Resolve the JWT signing key by kid.
Validate the JWS signature and JWT claims, including iss, aud, iat, and jti.
Validate the event URI and subject format before applying the signal.

The final JWT header values, including typ, require generated-contract or implementation approval before publication.


Claim	Validation
iss	Must identify the expected OCI IAM issuer.
aud	Must match an audience configured for the receiver.
iat	Must be acceptable under the receiver time-validation policy.
jti	Use to prevent duplicate processing.
sub_id	Validate the subject identifier format and value.
events	Validate the event URI and event-specific payload before processing.

Example SET Payloads

These are decoded JWT payload examples. Actual delivery sends the signed compact JWT, not JSON.

Verification SET

A verification SET uses an opaque stream subject instead of an OCI IAM user subject. Confirm that the state value matches the value supplied in the verification request.

{
  "iss": "https://idcs.example.com",
  "aud": ["https://receiver.example.com/ssf"],
  "iat": 1784736000,
  "jti": "verification-stream-9d3f1fb1-source-7a1c",
  "sub_id": {
    "format": "opaque",
    "id": "urn:ocid:stream:9d3f1fb1a7d24f2aa6d3a8d0c6f7b901"
  },
  "events": {
    "https://schemas.openid.net/secevent/ssf/event-type/verification": {
      "state": "receiver-check-20260722"
    }
  }
}

CAEP Session-Revoked SET

The following subject shape is implementation-derived. Confirm the user identifier and sub_id representation before publishing it as a customer contract.

{
  "iss": "https://idcs.example.com",
  "aud": ["https://receiver.example.com/ssf"],
  "iat": 1784736000,
  "jti": "session-revoked-stream-9d3f1fb1-event-7a1c",
  "sub_id": {
    "format": "iss_sub",
    "iss": "https://idcs.example.com",
    "sub": "ocid1.user.oc1..exampleuniqueid"
  },
  "events": {
    "https://schemas.openid.net/secevent/caep/event-type/session-revoked": {
      "event_timestamp": 1784735990,
      "reason_user": {"en": "Logout"},
      "session_id": "example-session-id",
      "current_ip": "198.51.100.42",
      "current_user_agent": "ExampleReceiverTest/1.0"
    }
  }
}

The optional session_id, current_ip, and current_user_agent members are omitted when unavailable.

CAEP Credential-Change SET

{
  "iss": "https://idcs.example.com",
  "aud": ["https://receiver.example.com/ssf"],
  "iat": 1784736000,
  "jti": "credential-change-stream-9d3f1fb1-event-3e9b",
  "sub_id": {
    "format": "iss_sub",
    "iss": "https://idcs.example.com",
    "sub": "ocid1.user.oc1..exampleuniqueid"
  },
  "events": {
    "https://schemas.openid.net/secevent/caep/event-type/credential-change": {
      "event_timestamp": 1784735990,
      "credential_type": "password",
      "change_type": "update",
      "initiating_entity": "admin",
      "reason_admin": {"en": "User Password Change"},
      "current_ip": "198.51.100.42",
      "current_user_agent": "ExampleAdminClient/1.0"
    }
  }
}

For a self-service password operation, IAM uses initiating_entity: user and reason_user. For an MFA reset, it uses credential_type: ALL_FACTORS, change_type: revoke, and the MFA-reset reason. Optional IP and user-agent members are omitted when not available.

Oracle Cloud Infrastructure Documentation