Skip to main content
U.S. flag

An official website of the United States government

Dot gov

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Https

Secure .gov websites use HTTPS
A lock ( Https ) or https:// means you've safely connected to the .gov website. Share sensitive information only on official, secure websites.

Getting started

Login.gov allows partners and Relying Parties (RPs) to notify us of various security-related events through our API.

Submitting a Security Event Token (SET)

Login.gov supports Push-Based SET Token Delivery Using HTTP. The SETs are signed JWTs (JSON Web Tokens), similar to those used in the OpenID Connect Authorization flow.

The OpenID RISC Profile defines some very specific properties of these JWTs, and Login.gov will validate against them, providing clear error messages where possible.

Auto-discovery

Login.gov provides a JSON endpoint for OpenID Connect auto-discovery at /.well-known/risc-configuration. In our agency integration environment, this is available at https://idp.int.identitysandbox.gov/.well-known/risc-configuration

Supported Incoming Events

Login.gov accepts custom events, based on the OpenID RISC Event Types, but not specific events from that list at this time.

Authorization Fraud Detected

RPs should submit this event when they believe a user’s credentials have been compromised, that somebody who is not the user was able to sign in to a user’s account. Login.gov may force reset of the user’s password when we receive this event.

The event_type for this is:

https://schemas.login.gov/secevent/risc/event-type/authorization-fraud-detected

Identity Fraud Detected

RPs should submit this event when they suspect an account has been used to commit identity theft or related fraudulent activity. Login.gov may reset the user’s profile and verified attributes data when we receive this event.

The event_type for this is:

https://schemas.login.gov/secevent/risc/event-type/identity-fraud-detected

Request

To submit a SET, send an HTTP POST request to the /api/risc/security_events endpoint. The body of the request is a signed JWT.

JWTs must be signed by the client application’s private key using RS256, the same one used for the private_key_jwt flow for OpenID Connect.

HTTP Request

  • Content-Type (required)
    The request must have a Content-Type of application/secevent+jwt

JWT Headers

  • alg (required)
    The JWT must be signed with the RS256 algorithm.

  • typ (required)
    The type header must be set to secevent+jwt

JWT Claims

  • aud (required)
    The audience for this JWT, which is the full URL for the /api/risc/security_events endpoint. In the agency integration environment, this is https://idp.int.identitysandbox.gov/api/risc/security_events

  • iat
    Time at which the JWT was issued, an integer timestamp representing the number of seconds since the Unix Epoch.

  • iss (required)
    The issuer of this SET, which should be your client application’s client ID. For example: urn:gov:gsa:openidconnect:test:risc:sets

  • jti (required)
    JWT Identifier. This should be a unique identifier for this event, Login.gov will attempt to de-duplicate events by this key.

  • events

    An object containing an event, keyed by event type. See Supported Incoming Events for possible keys.

    The event (the value) contains:

    • subject (required)
      An event should contain a subject object, with the following keys:

      • subject_type
        Must be iss-sub, this indicates the sub is the subject provided by the original issuer (Login.gov)

      • iss
        This is Login.gov’s issuer, the root URL for Login.gov. In the agency integration environment, this is https://idp.int.identitysandbox.gov

      • sub
        The UUID identifying the user. This is provided as the sub inside the id_token JWT in the OpenID Token endpoint.

    • occurred_at
      Time at which the security event occurred, an integer timestamp representing the number of seconds since the Unix Epoch. This optional field can be used to back-date reports of events, if they are not detected immediately.

    Example:

    {
  "<$EVENT_TYPE>": {
    "subject": {
      "subject_type": "iss-sub",
      "iss": "https://idp.int.identitysandbox.gov",
      "sub": "<$SUB>"
    },
    "occurred_at": 1590000000
  }
}

Example request

For a Security Event like this:

{
  "iss": "urn:gov:gsa:openidconnect:test:risc:sets",
  "jti": "abcdefghijklmnopqrstuvwxyz",
  "iat": 1595532178,
  "aud": "https://idp.int.identitysandbox.gov/api/risc/security_events",
  "events": {
    "https://schemas.login.gov/secevent/risc/event-type/authorization-fraud-detected": {
      "subject": {
        "subject_type": "iss-sub",
        "iss": "https://idp.int.identitysandbox.gov",
        "sub": "123d4f56-jkl7-891011-t12vw-y13a1415d1617ghi18"
      },
      "occurred_at": 1590000000
    }
  }
}

With the JWT headers of:

{
  "typ": "secevent+jwt",
  "alg": "RS256"
}

After being encoded as a JWT and signed with a private key, the entire request would look like:

POST /api/risc/security_events
Content-Type: application/secevent+jwt
Accept: application/json
eyJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJSUzI1NiJ9
.
eyJpc3MiOiJ1cm46Z292OmdzYTpvcGVuaWRjb25uZWN0OnRlc3Q6cmlzYzpzZXRzIiwianRpIjoiYWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoiLCJpYXQiOjE1OTU1MzIxNzgsImF1ZCI6Imh0dHBzOi8vaWRwLmludC5pZGVudGl0eXNhbmRib3guZ292L2FwaS9yaXNjL3NlY3VyaXR5X2V2ZW50cyIsImV2ZW50cyI6eyJodHRwczovL3NjaGVtYXMubG9naW4uZ292L3NlY2V2ZW50L3Jpc2MvZXZlbnQtdHlwZS9hdXRob3JpemF0aW9uLWZyYXVkLWRldGVjdGVkIjp7InN1YmplY3QiOnsic3ViamVjdF90eXBlIjoiaXNzX3N1YiIsImlzcyI6Imh0dHBzOi8vaWRwLmludC5pZGVudGl0eXNhbmRib3guZ292Iiwic3ViIjoiMTIzZDRmNTYtamtsNy04OTEwMTEtdDEydncteTEzYTE0MTVkMTYxN2doaTE4In0sIm9jY3VycmVkX2F0IjoxNTkwMDAwMDAwfX19
.
O-B3WJwITdMYWaEf0MNErEdy-Hy33DQ6wi7uMYgYHkFgq4hDoIoee4_sgsaYELqEA7zehljn_7FHFVN6sQYKVBQh3OVg281i2aRFUk9SjL8dsnecV_wxz9sYLm4ndO9IOSRjX5sZ7pv6zVTjz1-pTfaYHXx0nuqzRTlm5WZ4NP47XgDXEwsiv6Z1s4VLAqnPl7yuXu_ZNIqj0ww0v6xWA2Zkt_NM8F9grZ0kx5imbVrX2zoXnO7nkBzJThUuZh_CTNRItMolY2IblzHyHYxWRvkEjCLFjtI4vtAvhGN8ZEPk16yUZ2EnY8ptvacI3ZBoG12On-POsIltZekW7JpOqg

Response

Successful response

A successful SET submission will receive an empty response body with a 202 “Accepted” status.

HTTP/1.1 202 Accepted

Error response

An unsuccessful SET submission will receive a 400 “Bad Request”, with a JSON body containing error information.

  • err (string)
    An error code defined by Security Event HTTP Push spec.

  • description (string)
    A more human-readable description of the error.

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "err":"jwtHdr",
  "description":"typ header must be secevent+jwt"
}

Receiving a Security Event Token (SET)

Configuration

To configure your application to receive notifications from Login.gov, you must supply Login.gov with a URL.

The URL must:

  • Be publicly accessible with HTTPS,
  • Allow POST requests from Login.gov,
  • Use a certificate signed by a trusted certificate authority, and
  • Must use port 443 (if specifying a port).

Agency integration environment:

  • Use the portal to register the push_notification_url for your application
  • Your push_notification_url will be automatically added to the integration environment’s outbound proxy allowlist by 5PM UTC.

Production environment:

  • The push_notification_url will be deployed as part of the application promotion process. Please specify in the
    promotion request that you are including a SET configuration so that we know to add your URL to our outbound proxy allowlist.
  • It may require three weeks notice to allow the domain for outbound communication.

Supported Outgoing Events

Login.gov notifies for these events from the OpenID RISC Event Types:

Account Disabled

Login.gov pushes this event when a user account suspended.

For more information, see the specification for Account Disabled.

The event_type for this is:

https://schemas.openid.net/secevent/risc/event-type/account-disabled

The event payload has:

  • subject
    An event will include a subject object, with the following keys

    • subject_type (string)
      Will be iss-sub, this indicates the sub is the subject provided by the original issuer (Login.gov)

    • iss (string)
      This is Login.gov’s issuer, the root URL for Login.gov. In the agency integration environment, this is https://idp.int.identitysandbox.gov

    • sub (string)
      The UUID identifying the user. This is the same as the sub inside the id_token JWT in the OpenID Token endpoint.

  • reason (string)
    Optional, describes why was the account disabled.

Example:

{
  "https://schemas.openid.net/secevent/risc/event-type/account-disabled": {
    "subject": {
      "subject_type": "iss-sub",
      "iss": "https://idp.int.identitysandbox.gov",
      "sub": "<$SUB>"
    },
    "reason": "account-suspension"
  }
}

Account Enabled

Login.gov pushes this event when a user account reinstated.

For more information, see the specification for Account Enabled.

The event_type for this is:

https://schemas.openid.net/secevent/risc/event-type/account-enabled

The event payload has:

  • subject
    An event will include a subject object, with the following keys

    • subject_type (string)
      Will be iss-sub, this indicates the sub is the subject provided by the original issuer (Login.gov)

    • iss (string)
      This is Login.gov’s issuer, the root URL for Login.gov. In the agency integration environment, this is https://idp.int.identitysandbox.gov

    • sub (string)
      The UUID identifying the user. This is the same as the sub inside the id_token JWT in the OpenID Token endpoint.

Example:

{
  "https://schemas.openid.net/secevent/risc/event-type/account-enabled": {
    "subject": {
      "subject_type": "iss-sub",
      "iss": "https://idp.int.identitysandbox.gov",
      "sub": "<$SUB>"
    }
  }
}

Account Locked Due to MFA (Multi-Factor Authentication) Limit Reached

Login.gov pushes this event when a user fails MFA with their second factor enough times to hit the rate limit, and is subsequently locked out of their account for a period of time.

The event_type for this is:

https://schemas.login.gov/secevent/risc/event-type/mfa-limit-account-locked

The event payload has:

  • subject
    An event will include a subject object, with the following keys

    • subject_type (string)
      Will be iss-sub, this indicates the sub is the subject provided by the original issuer (Login.gov)

    • iss (string)
      This is Login.gov’s issuer, the root URL for Login.gov. In the agency integration environment, this is https://idp.int.identitysandbox.gov

    • sub (string)
      The UUID identifying the user. This is the same as the sub inside the id_token JWT in the OpenID Token endpoint.

Example:

{
  "https://schemas.login.gov/secevent/risc/event-type/mfa-limit-account-locked": {
    "subject": {
      "subject_type": "iss-sub",
      "iss": "https://idp.int.identitysandbox.gov",
      "sub": "<$SUB>"
    }
  }
}

Account Purged

Login.gov pushes this event when a user deletes their account.

For more information, see the specification for Account Purged.

The event_type for this is:

https://schemas.openid.net/secevent/risc/event-type/account-purged

The event payload has:

  • subject
    An event will include a subject object, with the following keys

    • subject_type (string)
      Will be iss-sub, this indicates the sub is the subject provided by the original issuer (Login.gov)

    • iss (string)
      This is Login.gov’s issuer, the root URL for Login.gov. In the agency integration environment, this is https://idp.int.identitysandbox.gov

    • sub (string)
      The UUID identifying the user. This is the same as the sub inside the id_token JWT in the OpenID Token endpoint.

Example:

{
  "https://schemas.openid.net/secevent/risc/event-type/account-purged": {
    "subject": {
      "subject_type": "iss-sub",
      "iss": "https://idp.int.identitysandbox.gov",
      "sub": "<$SUB>"
    }
  }
}

Identifier Changed

Login.gov pushes this event when a user changes the email address associated with their account.

For more information, see the specification for Identifier Changed.

The event_type for this is:

https://schemas.openid.net/secevent/risc/event-type/identifier-changed

The event payload has:

  • subject
    An event will include a subject object, with the following keys

    • subject_type (string)
      Will be email

    • email (string)
      This is the email address that no longer belongs to any user.

Example:

{
  "https://schemas.openid.net/secevent/risc/event-type/identifier-changed": {
    "subject": {
      "subject_type": "email",
      "email": "<$EMAIL>"
    }
  }
}

Identifier Recycled

Login.gov pushes this event when a user removes an email address from their account, freeing up the email address as an identifier.

For more information, see the specification for Identifier Recycled.

The event_type for this is:

https://schemas.openid.net/secevent/risc/event-type/identifier-recycled

The event payload has:

  • subject
    An event will include a subject object, with the following keys

    • subject_type (string)
      Will be email

    • email (string)
      This is the email address that no longer belongs to any user.

Example:

{
  "https://schemas.openid.net/secevent/risc/event-type/identifier-recycled": {
    "subject": {
      "subject_type": "email",
      "email": "<$EMAIL>"
    }
  }
}

Password Reset

Login.gov pushes this event when a user completes a password reset, either as part of account recovery or intentionally through the account page.

The event_type for this is:

https://schemas.login.gov/secevent/risc/event-type/password-reset

The event payload has:

  • subject
    An event will include a subject object, with the following keys

    • subject_type (string)
      Will be iss-sub, this indicates the sub is the subject provided by the original issuer (Login.gov)

    • iss (string)
      This is Login.gov’s issuer, the root URL for Login.gov. In the agency integration environment, this is https://idp.int.identitysandbox.gov

    • sub (string)
      The UUID identifying the user. This is the same as the sub inside the id_token JWT in the OpenID Token endpoint.

Example:

{
  "https://schemas.login.gov/secevent/risc/event-type/password-reset": {
    "subject": {
      "subject_type": "iss-sub",
      "iss": "https://idp.int.identitysandbox.gov",
      "sub": "<$SUB>"
    }
  }
}

Recovery Activated

Login.gov pushes this event when a user starts the “Forgot Password” flow for an account.

For more information, see the specification for Recovery Activated.

The event_type for this is:

https://schemas.openid.net/secevent/risc/event-type/recovery-activated

The event payload has:

  • subject
    An event will include a subject object, with the following keys

    • subject_type (string)
      Will be iss-sub, this indicates the sub is the subject provided by the original issuer (Login.gov)

    • iss (string)
      This is Login.gov’s issuer, the root URL for Login.gov. In the agency integration environment, this is https://idp.int.identitysandbox.gov

    • sub (string)
      The UUID identifying the user. This is the same as the sub inside the id_token JWT in the OpenID Token endpoint.

Example:

{
  "https://schemas.openid.net/secevent/risc/event-type/recovery-activated": {
    "subject": {
      "subject_type": "iss-sub",
      "iss": "https://idp.int.identitysandbox.gov",
      "sub": "<$SUB>"
    }
  }
}

Recovery Information Changed

Login.gov pushes this event when a user changes any of their second factor authentication methods, for example, adding or removing an email, phone address, TOTP authentication app, backup codes, or PIV/CAC.

For more information, see the specification for Recovery Information Changed.

The event_type for this is:

https://schemas.openid.net/secevent/risc/event-type/recovery-information-changed

The event payload has:

  • subject
    An event will include a subject object, with the following keys

    • subject_type (string)
      Will be iss-sub, this indicates the sub is the subject provided by the original issuer (Login.gov)

    • iss (string)
      This is Login.gov’s issuer, the root URL for Login.gov. In the agency integration environment, this is https://idp.int.identitysandbox.gov

    • sub (string)
      The UUID identifying the user. This is the same as the sub inside the id_token JWT in the OpenID Token endpoint.

Example:

{
  "https://schemas.openid.net/secevent/risc/event-type/recovery-information-changed": {
    "subject": {
      "subject_type": "iss-sub",
      "iss": "https://idp.int.identitysandbox.gov",
      "sub": "<$SUB>"
    }
  }
}

Reproofing Completed

Login.gov pushes this event when a user re-verifies their identity (with the identity proofing process). This event is only sent if they previously had an active verified profile, not for the first-time identity verification.

The event_type for this is:

https://schemas.login.gov/secevent/risc/event-type/reproof-completed

The event payload has:

  • subject
    An event will include a subject object, with the following keys

    • subject_type (string)
      Will be iss-sub, this indicates the sub is the subject provided by the original issuer (Login.gov)

    • iss (string)
      This is Login.gov’s issuer, the root URL for Login.gov. In the agency integration environment, this is https://idp.int.identitysandbox.gov

    • sub (string)
      The UUID identifying the user. This is the same as the sub inside the id_token JWT in the OpenID Token endpoint.

Example:

{
  "https://schemas.login.gov/secevent/risc/event-type/mfa-limit-account-locked": {
    "subject": {
      "subject_type": "iss-sub",
      "iss": "https://idp.int.identitysandbox.gov",
      "sub": "<$SUB>"
    }
  }
}

Request

Login.gov will make a POST request to your app’s push_notification_url, see Configuration for more details on setting that up. The JWT will be signed with Login.gov’s private key. See the OpenID Connect guide for information on how to get Login.gov’s public key from the Certificates Endpoint.

If your app had the client ID of urn:gov:gsa:openidconnect:test:risc:sets and was configured to receive events at https://agency.example.gov/events, and a user freed up email@example.com Login.gov would make a request like this.

With a JWT payload:

{
  "iss": "https://idp.int.identitysandbox.gov/",
  "jti": "abcdefghijklmnopqrstuvwxyz",
  "iat": 1595532178,
  "aud": "https://agency.example.gov/events",
  "events": {
    "https://schemas.openid.net/secevent/risc/event-type/identifier-recycled": {
      "subject": {
        "subject_type": "email",
        "email": "email@example.com"
      }
    }
  }
}

POST /events
Host: agency.example.gov
Content-Type: application/secevent+jwt
Accept: application/json
eyJ0eXAiOiJzZWNldmVudCtqd3QiLCJraWQiOiJmNWNlMTIzOWUzOWQzZGE4MzZmOTYzYmNjZDg1Zjg1ZDU3ZDQzMzVjZmRjNmExNzAzOWYyNzQzNjFhMThiMTNjIiwiYWxnIjoiUlMyNTYifQ
.
eyJpc3MiOiJodHRwczovL2lkcC5pbnQuaWRlbnRpdHlzYW5kYm94Lmdvdi8iLCJqdGkiOiJhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5eiIsImlhdCI6MTU5NTUzMjE3OCwiYXVkIjoiaHR0cHM6Ly9hZ2VuY3kuZXhhbXBsZS5nb3YvZXZlbnRzIiwiZXZlbnRzIjp7Imh0dHBzOi8vc2NoZW1hcy5vcGVuaWQubmV0L3NlY2V2ZW50L3Jpc2MvZXZlbnQtdHlwZS9pZGVudGlmaWVyLXJlY3ljbGVkIjp7InN1YmplY3QiOnsic3ViamVjdF90eXBlIjoiZW1haWwiLCJlbWFpbCI6ImVtYWlsQGV4YW1wbGUuY29tIn19fX0
.
KS0KvsV0eIRIhvg8wGdN6luIgsXi4nqp9ZY3OF2ft2fUwsk5rk2O_e2-I2Lf8yj0HN1BQ8IIAChWB9_dv-FMAFhShcCpuSHP_dQzBXLATc57PC0fAOZwqAgBuwnB08Z6o_I0OyBZCla5SctYwk1mfK0Wyup7EHdszvuc3i8K5uJV0bPii-VKbJ3YFnMcJD3OVaU3CkaJTqnmdtxYb02uWvImK5D3H9aPgQgJUYsARN-qMmcn5vUGCxWXpMmV53X-Czcf9RGBiK4ZLHL4st2Sxjza3UzC_p_S82rff_g-pJvZbIXL_II02gF9jOsMXELfaX40_SFsnyY6HDCOy3HIAw

HTTP Request

  • Content-Type (required)
    The request will have a Content-Type of application/secevent+jwt

JWT Headers

  • alg (string)
    The JWT will be signed with the RS256 algorithm.

  • typ (string)
    The type header will be set to secevent+jwt

  • kid (string)
    The kid header provides a hint indicating which key was used to sign the JWT. The keys are listed in the Certificates Endpoint.

JWT Claims

  • aud (string)
    The audience for this JWT, which is your application’s push_notification_url

  • iat (integer)
    Time at which the JWT was issued, an integer timestamp representing the number of seconds since the Unix Epoch.

  • iss (string)
    The issuer of this SET, which will be Login.gov’s issuer, the root URL for Login.gov. In the agency integration environment, this is https://idp.int.identitysandbox.gov

  • jti (required)
    JWT Identifier. This will be a random, unique identifier for this event, you should be able to de-duplicate based on this.

  • events
    An object containing an event, keyed by event type. The keys and values depend on the event types, see Supported Outgoing Events for event types and their payloads.

  • exp (integer)
    Time at which the JWT expires (12 hours after it was issued), an integer timestamp representing the number of seconds since the Unix Epoch.

Response

Login.gov will interpret any response other than a 200-level status as a failure, and will ignore any response body. Failure requests may be retried.

Edit this page
Return to top