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.


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.

OpenID Connect

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


The authorization endpoint handles authentication and authorization of a user. To present the authorization page to a user, direct them to the /openid_connect/authorize. View an example for private_key_jwt or PKCE in the side panel.

Request Parameters

  • JWT
  • PKCE


The Authentication Context Class Reference requests can be used to specify the type of service level1 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).

A type of service level1 must be specified.

    Basic identity assurance, does not require identity verification (this is the most common value).
    Requires that the user has gone through identity verification1

We default to requiring a user to be authenticated with a second factor:

  • urn:gov:gsa:ac:classes:sp:PasswordProtectedTransport:duo
    This specifies that a user has been authenticated with a second factor. This value will be returned in the user attributes by default. We do not allow strict AAL1, because it implies that a user did not authenticate with a second factor. This setting requires users to reauthenticate with a separate second factor (i.e. not a session secret) once every 30 days at a minimum.

Stricter behavior can be specified by adding one of:

    This is the same as the default behavior except users must reauthenticate with a separate second factor (i.e. not a session secret) once every 12 hours.
    This specifies that a user has been authenticated with a crytographically secure method, such as WebAuthn or using a PIV/CAC. Users must always authenticate with a second factor.
    This specifies that a user has been authenticated with an HSPD12 credential (requires PIV/CAC). Users must always authenticate with a second factor.

These are not recommended, and only for legacy compatibility.

    Equivalent to IAL1
    Equivalent to identity verified account

1. continues to work toward achieving certification of compliance with NIST’s IAL2 standard from a third-party assessment organization. 1 2 3


The unique identifier for the client. This will be registered with the IdP in advance.


This must be select_account


This must be code


The URI will redirect to after a successful authorization.


A space-separated string of the scopes being requested. (Keep in mind the blank space “ “ should be encoded with “+”.) 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
  • all_emails
  • phone
  • profile:birthdate
  • profile:name
  • profile:verified_at
  • profile
  • social_security_number
  • x509
  • x509:issuer
  • x509:presented
  • x509:subject


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.


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.


optional, for identity verified requests only
Specifies how recently the user’s 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 verification process again before continuing back to your application.

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

The format for this value is nD, where n 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)


If you know that a user would prefer one of our alternative language translations (currently Spanish or French), you can include the locale parameter to specify the language should use (either es for Spanish or fr for French).
JWT Request

Authorization response

After an authorization, 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. Validate that the value is the same.

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. The error_description parameter will provide a description.
  • error_description — A description of the error.
  • state — The state value originally provided by the client.
Next step: Token
Next step: Token
Edit this page
Return to top