Skip to main content

OpenID Connect developer guide

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.

Contents

Getting started

Choosing an authentication method

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

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:

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:

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:

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:

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:

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:

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:

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:

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.