SSF Security Event Tokens

This feature is only available with Identity Threat Protection in Identity Engine.

The Shared Signals Framework (SSF) Security Event Tokens API allows third-party security event providers to send Security Event Tokens (SETs) to Okta. The provider must be configured in Okta as a Security Events Provider instance before transmitting a SET to Okta. See Create a Security Events Provider. After the token is verified, any appropriate action is performed upon ingestion.

Okta uses the Shared Signals Framework (SSF) defined by the OpenID Shared Signals and Events Framework specification. A risk signal is ingested as a Security Event Token (SET), a type of JSON Web Token (JWT) that must comply with the SET standard: RFC 8417 - Security Event Token(SET). The security.events.provider.receive_event System Log event is created when a SET is published to Okta successfully.

Security Event Token JWT body payload

JSON Web Token body payload for a Security Event Token

iss
required
string

Token issuer

aud
required
string

Audience

jti
required
string

Token ID

iat
required
integer <int64>

Token issue time (UNIX timestamp)

required
object (SecurityEventTokenRequestJwtEvents)

A non-empty collection of events

object (OktaDeviceRiskChangeEvent)

The device risk level changed

event_timestamp
required
integer <int64>

The time of the event (UNIX timestamp)

required
object (SecurityEventSubject)

The event subjects

current_level
required
string

Current risk level of the device

Enum: "low" "medium" "high" "secure" "none"
previous_level
required
string

Previous risk level of the device

Enum: "low" "medium" "high" "secure" "none"
initiating_entity
string

The entity that initiated the event

Enum: "admin" "user" "policy" "system"
object

A localized administrative message intended for logging and auditing.
Either reason_admin or reason_user is required.

object

A localized message intended for the end user.
Either reason_admin or reason_user is required.

object (OktaIpChangeEvent)

IP changed for the subject's session

event_timestamp
required
integer <int64>

The time of the event (UNIX timestamp)

required
object (SecurityEventSubject)

The event subjects

current_ip_address
required
string

Current IP address of the subject

previous_ip_address
required
string

Previous IP address of the subject

initiating_entity
string

The entity that initiated the event

Enum: "admin" "user" "policy" "system"
object

A localized administrative message intended for logging and auditing.
Either reason_admin or reason_user is required.

object

A localized message intended for the end user.
Either reason_admin or reason_user is required.

object (OktaUserRiskChangeEvent)

The user risk level changed

event_timestamp
required
integer <int64>

The time of the event (UNIX timestamp)

required
object (SecurityEventSubject)

The event subjects

current_level
required
string

Current risk level of the user

Enum: "low" "medium" "high" "secure" "none"
previous_level
required
string

Previous risk level of the user

Enum: "low" "medium" "high" "secure" "none"
initiating_entity
string

The entity that initiated the event

Enum: "admin" "user" "policy" "system"
object

A localized administrative message intended for logging and auditing.
Either reason_admin or reason_user is required.

object

A localized message intended for the end user.
Either reason_admin or reason_user is required.

object (CaepDeviceComplianceChangeEvent)

The subject's device compliance was revoked

event_timestamp
required
integer <int64>

The time of the event (UNIX timestamp)

required
object (SecurityEventSubject)

The event subjects

current_status
required
string

Current device compliance status

Enum: "compliant" "not-compliant"
previous_status
required
string

Previous device compliance status

Enum: "compliant" "not-compliant"
initiating_entity
string

The entity that initiated the event

Enum: "admin" "user" "policy" "system"
object

A localized administrative message intended for logging and auditing.
Either reason_admin or reason_user is required.

object

A localized message intended for the end user.
Either reason_admin or reason_user is required.

object (CaepSessionRevokedEvent)

The session of the subject was revoked

event_timestamp
required
integer <int64>

The time of the event (UNIX timestamp)

required
object (SecurityEventSubject)

The event subjects

current_ip
string

Current IP of the session

current_user_agent
string

Current User Agent of the session

initiating_entity
string

The entity that initiated the event

Enum: "admin" "user" "policy" "system"
last_known_ip
string

Last known IP of the session

last_known_user_agent
string

Last known User Agent of the session

object

A localized administrative message intended for logging and auditing.
Either reason_admin or reason_user is required.

object

A localized message intended for the end user.
Either reason_admin or reason_user is required.

object (RiscIdentifierChangedEvent)

The subject's identifier has changed, which is either an email address or a phone number change

event_timestamp
required
integer <int64>

The time of the event (UNIX timestamp)

required
object (SecurityEventSubject)

The event subjects

new-value
string

The new identifier value

{
  • "aud": "https://receiverexample.okta.com/",
  • "events": {
    • "https://schemas.okta.com/secevent/okta/event-type/device-risk-change": {
      },
    • "https://schemas.okta.com/secevent/okta/event-type/ip-change": {
      },
    • "https://schemas.okta.com/secevent/okta/event-type/user-risk-change": {
      },
    • "https://schemas.openid.net/secevent/caep/event-type/device-compliance-change": {
      },
    • "https://schemas.openid.net/secevent/caep/event-type/session-revoked": {
      },
    • "https://schemas.openid.net/secevent/risc/event-type/identifier-changed": {
      }
    },
  • "iat": 1702448550,
  • "iss": "https://transmitter.example.com",
  • "jti": "24c63fb56f ... a9fa24"
}

Security Event Token JWT header

JSON Web Token header for a Security Event Token

kid
required
string

Key ID used to sign or encrypt the JWT

typ
required
string

The type of content being signed or encrypted

alg
required
string

Algorithm used to sign or encrypt the JWT

{
  • "alg": "RS256",
  • "kid": "string",
  • "typ": "secevent+jwt"
}

Publish a Security Event Token
Identity Engine

Publishes a Security Event Token (SET) sent by a Security Events Provider. After the token is verified, Okta ingests the event and performs any appropriate action.

Request
Request Body schema: application/secevent+jwt
required

The request body is a signed SET, which is a type of JSON Web Token (JWT).

For SET JWT header and body descriptions, see SET JWT header and SET JWT body payload.

string
Responses
202

Accepted

400

Bad Request

post/security/api/v1/security-events
Request samples
application/secevent+jwt
eyJraWQiOiJzYW1wbGVfa2lkIiwidHlwIjoic2ZXZlbnQra ... mrtmw
Response samples
application/json
{
  • "description": "Failed claim validation in security event token. 'events.mediationDeviceComplianceChangeEvent.previousStatus': The field cannot be left blank",
  • "err": "invalid_request"
}