Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

OpenID Connect

OpenID Connect is a simple identity layer built on top of the OAuth 2.0 protocol. login.gov supports version 1.0 of the specification and conforms to the iGov Profile.

Getting started

Choosing an authentication method

Login.gov supports two ways of authenticating clients: private_key_jwt and PKCE.

  • private_key_jwt (preferred for web apps)
    The client sends a JSON Web Token, or JWT, signed with a private key when requesting access tokens. The corresponding public key is registered with the IdP ahead of time, similar to SAML.

  • PKCE (preferred for native mobile apps)
    Short for Proof Key for Code Exchange by OAuth Public Clients and pronounced “pixy.” In this method, the client sends a public identifier as well as a hashed random value generated by the client.

Other implementations of OpenID Connect use the “implicit flow” or the client_secret param, but login.gov does not support those methods. The implicit flow is not recommended by the OAuth group for security reasons. Similarly client_secret is not supported by login.gov because of security reasons. It requires managing a shared secret in two places: the client and the server, where private_key_jwt flow involves only sharing public keys with the server and PKCE only has a one-time secret.

Auto-discovery

Consistent with the specification, login.gov provides a JSON endpoint for OpenID Connect auto-discovery at /.well-known/openid-configuration. In our agency integration environment, this is available at https://idp.int.identitysandbox.gov/.well-known/openid-configuration

Authorization

The authorization endpoint handles authentication and authorization of a user. To present the login.gov authorization page to a user, direct them to the /openid_connect/authorize.

View an example for…

https://idp.int.identitysandbox.gov/openid_connect/authorize?
  acr_values=http%3A%2F%2Fidmanagement.gov%2Fns%2Fassurance%2Fial%2F1&
  client_id=${CLIENT_ID}&
  nonce=${NONCE}&
  prompt=select_account&
  redirect_uri=${REDIRECT_URI}&
  response_type=code&
  scope=openid+email&
  state=abcdefghijklmnopabcdefghijklmnop

Request Parameters

  • acr_values
    The Authentication Context Class Reference requests can be used to specify the IAL (Identity Assurance Level) or the AAL (Authentication Assurance Level) for the user. These and the scope determine which user attributes will be available in the user info response.

    Multiple values can be joined with a space (before being URI-escaped in the final URL)

    IAL Values

    An IAL value must be specified.

    • http://idmanagement.gov/ns/assurance/ial/1
      Basic identity assurance, does not require identity verification (this is the most common value).
    • http://idmanagement.gov/ns/assurance/ial/2
      Requires that the user has gone through identity verification
    • http://idmanagement.gov/ns/assurance/ial/2?strict=true
      Requires that the user has gone through identity verification, including a “liveness” check (this is not available in production, only in int and staging environments)

    AAL Values

    We default to requiring a user to be authenticated with a second factor. Stricter behavior can be specified by adding one of:

    • http://idmanagement.gov/ns/assurance/aal/3
      This specifies that a user has been authenticated with a crytographically secure method, such as WebAuthn or using a PIV/CAC.
    • http://idmanagement.gov/ns/assurance/aal/3?hspd12=true
      This specifies that a user has been authenticated with an HSPD12 credential (requires PIV/CAC)

    LOA Values

    These not recommended, they are for legacy compatibility only.

    • http://idmanagement.gov/ns/assurance/loa/1
      Equivalent to IAL1
    • http://idmanagement.gov/ns/assurance/loa/3
      Equivalent to IAL2
  • client_id
    The unique identifier for the client. This will be registered with the login.gov IdP in advance.

  • code_challengerequired for PKCE
    The URL-safe base64 encoding of the SHA256 digest of a random value generated by the client. The original random value is referred to as the code_verifier and is later used with the token endpoint. Generating these values in Ruby might look like this, for example:
    code_verifier = SecureRandom.hex
    => "7a5e819dd39f17242fdeeba0c1c80be6"
    code_challenge = Digest::SHA256.base64digest(code_verifier)
    => "TdzfmaWefbtaI0Wdo6lrZCXpLu1WpamnSoSHfDUiL7Y="
    
  • code_challenge_methodrequired for PKCE
    This must be S256, the only PKCE code challenge method supported.

  • promptoptional, requires administrator approval
    To force a re-authorization event when a current IdP session is active, you will need to set the prompt attribute to login, like this: prompt=login.



    Request permission for your application to do this by emailing an administrator at partners@login.gov.

    User experience

    If prompt is not specified and the user has an active IdP session, they are given the choice to continue authenticating or login with another account.

  • response_type
    This must be code.

  • redirect_uri
    The URI login.gov will redirect to after a successful authorization.

  • scope
    A space-separated string of the scopes being requested. The authorization page will display the list of attributes being requested from the user. Applications should aim to request the fewest user attributes and smallest scope needed. Possible values are:
    • openid
    • address
    • email
    • phone
    • profile:birthdate
    • profile:name
    • profile:verified_at
    • profile
    • social_security_number
  • state
    A unique value at least 22 characters in length used for maintaining state between the request and the callback. This value will be returned to the client on a successful authorization.

  • nonce
    A unique value at least 22 characters in length used to verify the integrity of the id_token and mitigate replay attacks. This value should include per-session state and be unguessable by attackers. This value will be present in the id_token of the token endpoint response, where clients will verify that the nonce claim value is equal to the value of the nonce parameter sent in the authentication request. Read more about nonce implementation in the spec.

  • verified_withinoptional, only applies to IAL2
    Specifies how recently the user’s IAL2 information must be verified. For example, if your application requires that the user’s data must have been verified within the last year, you can set the value to verified_within=1y, and customers whose data is older than that will go through the identity proofing process again before continuing back to your application.

    Possible values

    The shortest value allowed for this parameter is 30 days (30d) because of the cost of proofing, as well as the time it takes for backend proofing sources to be updated.

    The format for this value is xD, where x is an integer number and D specifies the duration. D can be:

    • d for number of days
      • Example: 45d
    • w for a number of weeks
      • Example: 8w (equivalent to 56d)
    • m for a number of months (assumed to be 30-day months)
      • Example: 18m (equivalent to 540d)
    • y for a number of years (assumed to be 365-day years)
      • Example: 2y (equivalent to 730d)

Authorization response

After an authorization, login.gov will redirect to the provided redirect_uri.

In a successful authorization, the URI will contain the two parameters code and state:

  • code — A unique authorization code the client can pass to the token endpoint.
  • state — The state value originally provided by the client.

For example:

https://agency.gov/response?
  code=12345&
  state=abcdefghijklmnopabcdefghijklmnop

In an unsuccessful authorization, the URI will contain the parameters error and state, and optionally error_description:

  • error — The error type, either:
    • access_denied — The user has either cancelled or declined to authorize the client.
    • invalid_request — The authorization request was invalid. See the error_description parameter for more details.
  • error_description — A description of the error.
  • state — The state value originally provided by the client.

For example:

https://agency.gov/response?
  error=access_denied&
  state=abcdefghijklmnopabcdefghijklmnop

Token

Clients use the token endpoint to exchange the authorization code for an id_token and access_token. To request a token, send a HTTP POST request to the /api/openid_connect/token endpoint.

View example an for…

POST https://idp.int.identitysandbox.gov/api/openid_connect/token

client_assertion=${CLIENT_ASSERTION}&
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
code=${CODE}&
grant_type=authorization_code

Request Parameters

  • client_assertionrequired for private_key_jwt
    A JWT signed with the client’s private key using the RS256 algorithm and containing the following claims:
    • iss (string) — The issuer, which must be the client_id.
    • sub (string) — The subject, which must also be the client_id.
    • aud (string) — The audience, which should be (or, in the case of multiple audience values, include) the URL of the token endpoint, for example: https://idp.int.identitysandbox.gov/api/openid_connect/token
    • jti (string) — The JWT ID, a unique identifier for the token which can be used to prevent reuse of the token. Should be an un-guessable, random string generated by the client.
    • exp (number) — The expiration time for this token. Should be an integer timestamp (number of seconds since the Unix Epoch) and be a short period of time in the future (such as 5 minutes from now).
  • client_assertion_typerequired for private_key_jwt
    When using private_key_jwt, must be urn:ietf:params:oauth:client-assertion-type:jwt-bearer

  • code
    The authorization code returned by the authorization response.

  • code_verifierrequired for PKCE
    The original value (before the SHA256) generated for the authorization request for PKCE that corresponds to the code_challenge.

  • grant_type
    Must be authorization_code

Token response

The token response will be a JSON object containing the following:

  • access_token (string)
    An opaque token used to access the user info endpoint.

  • token_type (string)
    The type of access token, which will always be Bearer.

  • expires_in (number)
    The number of seconds the access token will expire.

  • id_token (string)
    A signed JWT that contains basic attributes about the user and it is signed using the RS256 algorithm. The public key used to verify this JWT is available from the certificates endpoint.

Here’s an example token response:

{
  "access_token": "hhJES3wcgjI55jzjBvZpNQ",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJiMmQyZDExNS0xZDdlLTQ1NzktYjlkNi1mOGU4NGY0ZjU2Y2EiLCJpc3MiOiJodHRwczovL2lkcC5pbnQubG9naW4uZ292IiwiYWNyIjoiaHR0cDovL2lkbWFuYWdlbWVudC5nb3YvbnMvYXNzdXJhbmNlL2xvYS8xIiwibm9uY2UiOiJhYWQwYWE5NjljMTU2YjJkZmE2ODVmODg1ZmFjNzA4MyIsImF1ZCI6InVybjpnb3Y6Z3NhOm9wZW5pZGNvbm5lY3Q6ZGV2ZWxvcG1lbnQiLCJqdGkiOiJqQzdOblU4ZE5OVjVsaXNRQm0xanRBIiwiYXRfaGFzaCI6InRsTmJpcXIxTHIyWWNOUkdqendsSWciLCJjX2hhc2giOiJoWGpxN2tPcnRRS196YV82dE9OeGN3IiwiZXhwIjoxNDg5Njk0MTk2LCJpYXQiOjE0ODk2OTQxOTgsIm5iZiI6MTQ4OTY5NDE5OH0.pVbPF-2LJSG1fE9thn27PwmDlNdlc3mEm7fFxb8ZADdRvYmDMnDPuZ3TGHl0ttK78H8NH7rBpH85LZzRNtCcWjS7QcycXHMn00Cuq_Bpbn7NRdf3ktxkBrpqyzIArLezVJJVXn2EeykXMvzlO-fJ7CaDUaJMqkDhKOK6caRYePBLbZJFl0Ri25bqXugguAYTyX9HACaxMNFtQOwmUCVVr6WYL1AMV5WmaswZtdE8POxYdhzwj777rkgSg555GoBDZy3MetapbT0csSWqVJ13skWTXBRrOiQQ70wzHAu_3ktBDXNoLx4kG1fr1BiMEbHjKsHs14X8LCBcIMdt49hIZg"
}

The id_token contains the following claims:

  • iss (string) — The issuer of the response, which will be the URL of the login.gov IdP, for example: https://idp.int.identitysandbox.gov
  • sub (string) — The subject identifier, the UUID of the login.gov user (see user attributes).
  • aud (string) — The audience, which will be the client_id.
  • acr (string) — The Authentication Context Class Reference value of the returned claims, from the original authorization request.
  • at_hash (string) — The access token hash, a URL-safe base-64 encoding of the left 128 bits of the SHA256 of the access_token value. Provided so the client can verify the access_token value.
  • c_hash (string) — The code hash, a URL-safe base-64 encoding of the left 128 bits of the SHA256 of the authorization code value. Provided so the client can verify the code value.
  • exp (number) — The expiration time for this token, an integer timestamp representing the number of seconds since the Unix Epoch.
  • iat (number) — Time at which the JWT was issued, an integer timestamp representing the number of seconds since the Unix Epoch.
  • jti (string) — The JWT ID, a unique identifier for the token which can be used to prevent reuse of the token. Should be an un-guessable, random string generated by the client.
  • nbf (number) — The “not before” value, an integer timestamp of when the token will start to be valid (number of seconds since the Unix Epoch).
  • nonce (string) — The nonce value provided by the client in the authorization request.

Here’s an example decoded id_token:

{
  "sub": "b2d2d115-1d7e-4579-b9d6-f8e84f4f56ca",
  "iss": "https://idp.int.identitysandbox.gov",
  "acr": "http://idmanagement.gov/ns/assurance/ial/1",
  "nonce": "aad0aa969c156b2dfa685f885fac7083",
  "aud": "urn:gov:gsa:openidconnect:development",
  "jti": "jC7NnU8dNNV5lisQBm1jtA",
  "at_hash": "tlNbiqr1Lr2YcNRGjzwlIg",
  "c_hash": "hXjq7kOrtQK_za_6tONxcw",
  "exp": 1489694196,
  "iat": 1489694198,
  "nbf": 1489694198
}

User info

The user info endpoint is used to retrieve user attributes. Clients use the access_token from the token response as a bearer token in the HTTP Authorization header. To request attributes, send an HTTP GET request to the /api/openid_connect/userinfo endpoint, for example:

GET https://idp.int.identitysandbox.gov/api/openid_connect/userinfo
Authorization: Bearer hhJES3wcgjI55jzjBvZpNQ

User info response

The user info response will be a JSON object containing user attributes. login.gov supports some of the standard claims from OpenID Connect 1.0. In addition to the user attributes, the following information will also be present:

  • iss (string)
    The issuer of the response, which will be the URL of the login.gov IdP, for example: https://idp.int.identitysandbox.gov
    • Requires profile or profile:name scopes.
  • email_verified (boolean)
    Whether the email has been verified. Currently, login.gov only supports verified emails.
    • Requires the email scope.
  • phone_verified (boolean)
    Whether the phone number has been verified. Currently, login.gov only supports verified phones.
    • Requires the phone scope and an IAL2 account.
  • verified_at (number, null)
    When the user’s identity was last verified, as an integer timestamp representing the number of seconds since the Unix Epoch, or null if the account has never been verified.
    • Requires the profile or profile:verified_at scope.

Here’s an example response:

{
  "address": {
    "formatted": "123 Main St Apt 123\nWashington, DC 20001",
    "street_address": "123 Main St Apt 123",
    "locality": "Washington",
    "region": "DC",
    "postal_code": "20001"
  },
  "birthdate": "1970-01-01",
  "email": "test@example.com",
  "email_verified": true,
  "family_name": "Smith",
  "given_name": "John",
  "iss": "https://idp.int.identitysandbox.gov",
  "phone": "+1 (555) 555-5555",
  "phone_verified": true,
  "social_security_number": "111223333",
  "sub": "b2d2d115-1d7e-4579-b9d6-f8e84f4f56ca",
  "verified_at": 1577854800
}

Certificates

Login.gov’s public key, used to verify signed JWTs (such as the id_token), is available in JWK format at the /api/openid_connect/certs endpoint. For example, the URL in the agency integration environment is at https://idp.int.identitysandbox.gov/api/openid_connect/certs

This public key is rotated periodically (on at least an annual basis), so be sure to use the JWK endpoint dynamically through auto-discovery rather than hardcoding the public key. This ensures that your application will not require manual intervention when the login.gov public key is rotated.

Logout

Login.gov supports RP-Initiated Logout, allowing clients to log users out of their current login.gov session and redirect them back to the Relying Party.

Login.gov does not support Single Logout (SLO). The logout action will terminate the user’s session at login.gov but will not end any other potentially active sessions within service provider applications. For example, if a user signs in to applications A and B through login.gov, a logout request from A will end their login.gov session, but will not affect the session in application B.

To log out a user, send them to the /openid_connect/logout endpoint with the following parameters:

  • id_token_hint
    An id_token value from the token endpoint response.

  • post_logout_redirect_uri
    The URI login.gov will redirect to after logout.

  • state
    A unique value at least 22 characters in length used for maintaining state between the request and the callback. This value will be returned to the client on a successful logout.

Here’s an example logout request:

https://idp.int.identitysandbox.gov/openid_connect/logout?
  id_token_hint=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJiMmQyZDExNS0xZDdlLTQ1NzktYjlkNi1mOGU4NGY0ZjU2Y2EiLCJpc3MiOiJodHRwczovL2lkcC5pbnQubG9naW4uZ292IiwiYWNyIjoiaHR0cDovL2lkbWFuYWdlbWVudC5nb3YvbnMvYXNzdXJhbmNlL2xvYS8xIiwibm9uY2UiOiJhYWQwYWE5NjljMTU2YjJkZmE2ODVmODg1ZmFjNzA4MyIsImF1ZCI6InVybjpnb3Y6Z3NhOm9wZW5pZGNvbm5lY3Q6ZGV2ZWxvcG1lbnQiLCJqdGkiOiJqQzdOblU4ZE5OVjVsaXNRQm0xanRBIiwiYXRfaGFzaCI6InRsTmJpcXIxTHIyWWNOUkdqendsSWciLCJjX2hhc2giOiJoWGpxN2tPcnRRS196YV82dE9OeGN3IiwiZXhwIjoxNDg5Njk0MTk2LCJpYXQiOjE0ODk2OTQxOTgsIm5iZiI6MTQ4OTY5NDE5OH0.pVbPF-2LJSG1fE9thn27PwmDlNdlc3mEm7fFxb8ZADdRvYmDMnDPuZ3TGHl0ttK78H8NH7rBpH85LZzRNtCcWjS7QcycXHMn00Cuq_Bpbn7NRdf3ktxkBrpqyzIArLezVJJVXn2EeykXMvzlO-fJ7CaDUaJMqkDhKOK6caRYePBLbZJFl0Ri25bqXugguAYTyX9HACaxMNFtQOwmUCVVr6WYL1AMV5WmaswZtdE8POxYdhzwj777rkgSg555GoBDZy3MetapbT0csSWqVJ13skWTXBRrOiQQ70wzHAu_3ktBDXNoLx4kG1fr1BiMEbHjKsHs14X8LCBcIMdt49hIZg&
  post_logout_redirect_uri=${REDIRECT_URI}&
  state=abcdefghijklmnopabcdefghijklmnop

Logout response

In a successful logout, login.gov will redirect to the provided post_logout_redirect_uri with the state parameter added to the URL.

Here’s an example logout response:

https://agency.gov/response?
  state=abcdefghijklmnopabcdefghijklmnop

Example application

The login.gov team has created an example client to speed up your development,
all open source in the public domain: identity-oidc-sinatra