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 private_key_jwt or PKCE in the side panel.
Request Parameters
acr_values
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 level must be specified.
-
urn:acr.login.gov:auth-only
Requires basic identity assurance: email address, password, and at least one MFA method. No identity verification.Meets either NIST 800-63-3 AAL1 or AAL2 standard (depending on agency integration configuration)
-
urn:acr.login.gov:verified
Requires that the user has gone through basic identity verification without facial matching.Does not meet NIST 800-63-3 IAL2 standard.
-
urn:acr.login.gov:verified-facial-match-required
Requires identity verification with facial match for all users. Even if a user has been previously verified without facial matching, they will be required to go through verification with facial match.Meets NIST 800-63-3 IAL2 standard.
-
urn:acr.login.gov:verified-facial-match-preferred
Requires identity verification. Users with no previous identity verification will be required to go through a facial match. Users with previous identity verification will use that data, even if it was done without facial match.Authentications for users who verify with facial matching will meet NIST 800-63-3 IAL2 standard. Authentication for users who do not do facial matching will not meet NIST 800-63-3 IAL2 standard.
-
-
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 remembered device) once every 30 days at a minimum.
Stricter behavior can be specified by adding one of:
http://idmanagement.gov/ns/assurance/aal/2
This is the same as the default behavior except users must authenticate with a separate second factor (i.e. not a remembered device).http://idmanagement.gov/ns/assurance/aal/2?phishing_resistant=true
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.http://idmanagement.gov/ns/assurance/aal/2?hspd12=true
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.
http://idmanagement.gov/ns/assurance/ial/1
Requires basic identity assurance, does not require identity verification. Equivalent tourn:acr.login.gov:auth-only
.-
http://idmanagement.gov/ns/assurance/ial/2
Requires that the user has gone through basic identity verification. Equivalent tourn:acr.login.gov:verified
.Does not meet NIST 800-63-3 IAL2 standard.
-
http://idmanagement.gov/ns/assurance/loa/1
Equivalent tourn:acr.login.gov:auth-only
. http://idmanagement.gov/ns/assurance/loa/3
Equivalent tourn:acr.login.gov:verified
.
client_id
prompt
select_account
response_type
code
redirect_uri
scope
-
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
state
nonce
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.
locale
optionallocale
parameter to specify the language Login.gov should use (either es
for Spanish or fr
for French).
https://idp.int.identitysandbox.gov/openid_connect/authorize?
acr_values=urn:acr.login.gov:auth-only&
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. 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. Theerror_description
parameter will provide a description.
- error_description — A description of the error.
- state — The
state
value originally provided by the client.
https://agency.gov/response?
code=12345&
state=abcdefghijklmnopabcdefghijklmnop
https://agency.gov/response?
error=access_denied&
state=abcdefghijklmnopabcdefghijklmnop