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.

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 endpoint with the following parameters:

  • acr_values
    The Authentication Context Class Reference values used to specify the LOA (level of assurance) of an account, either LOA1 or LOA3. This and the scope determine which user attributes will be available in the user info response. The possible parameter values are:
    • http://idmanagement.gov/ns/assurance/loa/1
    • http://idmanagement.gov/ns/assurance/loa/3
  • 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
    This can either be select_account (default behavior) or login (force a re-authorization even if a current IdP session is active).

  • 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, and social_security_number

  • state
    A unique value at least 32 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 32 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.

View an example for…

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

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 with the following parameters in the request body:

  • client_assertionrequired for private_key_jwt
    A JWT signed with the client’s private key 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 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

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

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. 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 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/loa/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 LOA 3 account.

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"
}

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

Logout

login.gov supports RP-Initiated Logout, allowing clients to log users out of their current login.gov session and redirect them back. 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 32 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 apps

The login.gov team has created example clients to speed up your development, all open source in the public domain.