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.

Https

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.

Authentication

Authentication request

To authenticate a user with Login.gov, direct them to our authentication URL with a SAML authentication request as a GET param.

The `SAMLRequest` parameter is a url-encoded, base64-encoded, deflate-compressed XML payload of a

<samlp:AuthnRequest>:SAML_REQUEST = urlEncode(base64(deflate(payload)))

Note: We strongly encourage you to cryptographically sign authentication requests, unless there are technical limitations on your side that prevent this. In addition to providing increased security, this allows for seamless rotation of your application’s public certificate in the future. All signatures must use RSA SHA-256.

Specifying attributes and assurance levels

The <saml:AuthnContextClassRef> tags (nested under //samlp:AuthnRequest/samlp:RequestedAuthnContext/) specify the type of identity verification, AAL (Authentication Assurance Level) and attributes requested.

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.

To request specific attributes, list them (comma-separated) as the query parameter for http://idmanagement.gov/ns/requested_attributes?ReqAttr=. See the user attributes for the list of attributes that can be requested.

Example specifying IAL, AAL, and attributes

A proofed identity request at AAL2, with phishing resistent MFA, for email, phone, first name, last name, and SSN might look like:

<samlp:AuthnRequest ...>
  <!-- ... -->
  <samlp:RequestedAuthnContext Comparison='exact'>
    <saml:AuthnContextClassRef>urn:acr.login.gov:verified</saml:AuthnContextClassRef>
    <saml:AuthnContextClassRef>http://idmanagement.gov/ns/assurance/aal/2?phishing_resistant=true</saml:AuthnContextClassRef>
    <saml:AuthnContextClassRef>http://idmanagement.gov/ns/requested_attributes?ReqAttr=email,phone,first_name,last_name,ssn</saml:AuthnContextClassRef>
  </samlp:RequestedAuthnContext>
</samlp:AuthnRequest>

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 to urn:acr.login.gov:auth-only.

  • http://idmanagement.gov/ns/assurance/ial/2
    Requires that the user has gone through basic identity verification. Equivalent to urn:acr.login.gov:verified.

    Does not meet NIST 800-63-3 IAL2 standard.

  • http://idmanagement.gov/ns/assurance/loa/1
    Equivalent to urn:acr.login.gov:auth-only.

  • http://idmanagement.gov/ns/assurance/loa/3
    Equivalent to urn:acr.login.gov:verified.

RelayState

If you need to pass any information about the request back to your application after the authentication process is complete (e.g. the path to direct the user to), you can include a RelayState query parameter with up to 80 bytes of information. This will be included in the response back to your application as per section 3.4.3 of the SAML 2.0 bindings spec.

https://idp.int.identitysandbox.gov/api/saml/auth2023?SAMLRequest=${SAML_REQUEST}&RelayState=${RELAY_STATE}

Language Selection

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 Login.gov should use (either es for Spanish or fr for French), e.g.:

https://idp.int.identitysandbox.gov/api/saml/auth2023?SAMLRequest=${SAML_REQUEST}&locale=es

https://idp.int.identitysandbox.gov/api/saml/auth2024?SAMLRequest=${SAML_REQUEST}

Authentication response

After the user authenticates, Login.gov will redirect and POST a form back to your registered Assertion Consumer Service URL:

The SAMLResponse is a base64-encoded XML payload that contains encrypted data.

Next step: Logout 
POST ${ASSERTION_CONSUMER_SERVICE_URL}
SAMLResponse=${SAML_RESPONSE}
Next step: Logout
Edit this page
Return to top