Support

Login.gov support desk

If you have technical questions that are not covered by these FAQ’s, submit a ticket to the Partner Support Help Desk.

Frequently Asked Questions

: We encourage you to create an account directly on Login.gov or an agency partner like USAJobs to see Login.gov in action.

Generally, a site will place a login button on their site. When the user clicks this button they redirect to Login.gov where they can sign in or create an account. The Login.gov site will be branded with the agency logo and can include help text for migrating existing users. After authenticating with Login.gov they are redirected back to the agency with a unique UUID or email address that identifies the user.
Please see our overview documentation for more details.
: We offer email address and UUID. Since a user can change their email address we recommend tracking users by UUID.
: Yes. We recommend using UUID as the primary key to track users because the email address can change.
: Every user has a unique UUID per agency for privacy reasons. This means that the same user can return a different UUID depending on which agency they are signing in to. These UUIDs are also globally unique. We do offer sharing of UUIDs between agencies with user consent on a case by case basis.
: Once a user is authenticated on Login.gov and passed back to the agency it is up to the agency to manage the user's session.
We do not remotely invalidate or expire a user's session.
: Login.gov makes no guarantees on IP addresses or ranges. Please use the DNS when querying Login.gov for the latest IPs.
: Check the error that was returned. Generally we return the specific errors in the HTML, JSON, or in the redirect url.
: Please contact the engineers at Login.gov via Zendesk. They can help diagnose your problem further.
: No.
: No. Login.gov only works via redirects to and from an agency site.
: No. Login.gov only handles authentication. Granting users specific access and permissions is handled on the agency side. For example, some agencies use Active Directory to store what applications a user can access.
: For our Login.gov basic authentication accounts (IAL1), we rely on the user having access to an email address, password, and a secure multi-factor authentication method (AAL2 or higher) such as a phone, authentication app or PIV/CAC where they can receive a secure code to use to sign in to their account.

For identity proofing, in addition to meeting the above requirements for IAL1/AAL2, we ask users to upload a photograph of their state-issued ID and share their address, phone number and other personal information which is then verified against authoritative sources.
: Login.gov has a public status page available at https://status.login.gov/ where you can subscribe to incident notifications via email, SMS, Slack, or RSS.

Troubleshooting

OpenID Connect Errors

Authorization

Why it’s happening

The issuer (also known as the client id) provided does not match a service provider registered in the IdP.

What to do:

Ensure the authentication request has a client_id value
Ensure that the client_id sent in the authentication request matches the one registered in your application on the Partner Portal.
Ensure that the application configuration’s active value is set to true.

Why it’s happening

No IAL Service Levels are present in the acr_values parameter of the authentication request.

What to do:

Check the acr_values parameter in your authentication request and ensure that you are passing either:

urn:acr.login.gov:auth-only for Authentication Only applications, OR;
urn:acr.login.gov:verified for Identity-Verification Permitted applications.
Learn more about IAL Service Level values here: https://developers.login.gov/oidc/authorization/#service_level

Why it’s happening

Your authentication request specified an Identity Verification (IdV) level of service, but your application is registered as “Authentication Only.”

What to do:

If your application is Authentication Only, check the value of your acr_values parameter and ensure that it does not include http://idmanagement.gov/ns/assurance/ial/2.
If you believe your application SHOULD be set to Identity Verification Permitted, please:

Reach out to your account manager to make sure your application is authorized for IdV. If it isn’t, they can work with you to determine the right service level for your application.
If your application is authorized for IdV, go to the portal and update the Level of Service value to “Identity Verification Permitted.”
If this is a production instance, submit a Zendesk request to deploy that change to production.

Why it’s happening

No AAL levels are present in the acr_values parameter of the authentication request.

What to do:

Check the acr_values parameter in your authentication request.
Ensure that you are passing in the appropriate IAL Service Level value as well as any Authentication Assurance (AAL) values you might want for your application.
More information about the acr_values parameter can be found here: https://developers.login.gov/oidc/authorization/#acr_values

Why it’s happening

No valid attributes were passed in the scope parameter of the authentication request.

What to do:

Check the scope parameter in your authentication request.
Ensure you are passing in openid as well as at least one other attribute.
More information about the different types of attributes can be found here: https://developers.login.gov/attributes/

Why it’s happening

No valid attribute was passed in the prompt parameter of the authentication request.

What to do:

Check the prompt parameter in your authentication request.
Ensure you are passing select_account as the value.
More information about the prompt request parameter can be found here: https://developers.login.gov/oidc/authorization/#prompt

Why it’s happening

You have registered a redirect URI that cannot be parsed.

What to do:

Check your application’s configuration on the Partner Portal.
Ensure that all registered redirect_uris are propertly formatted and use https protocol.

Why it’s happening

You have not registered the redirect_uri that you sent in your authentication request.

What to do:

Check your application’s configuration on the Partner Portal and the redirect_uri passed through your authentication request.
Ensure the redirect_uri that you are sending as part of your authentication request is registered. You must register every redirect uri that your application redirects through.

Why it’s happening

You have requested attributes that your Service Level does not allow.

What to do:

Check the scope parameter in your authentication request.
If your application is an Authentication Only application, ensure you are only passing in IAL1 attributes.
More information about the different types of attributes can be found here: https://developers.login.gov/attributes/

Logout

Why it’s happening

The issuer (also known as the client id) provided does not match a service provider registered in the IdP.

What to do:

Ensure the logout request has a client_id value.
Ensure that the client_id sent in the logout request matches the one registered in your application on the Partner Portal.
Ensure that the application configuration’s active value is set to true.

Why it’s happening

The issuer (also known as the client id) was not found.

What to do:

Ensure the logout request has a client_id value.

Why it’s happening

We are no longer supporting the id_token_hint attribute as a method of logging out.

What to do:

Update your logout request to utilize the client_id attribute.
More information about the logout request parameters can be found here: https://developers.login.gov/oidc/logout/#logout-request.

Token

Why it’s happening

In the authentication response, a code value is returned that is then used in the token endpoint request. The code must be used within 15 minutes after it is generated. This error may mean that the user paused for too long during the authentication attempt.

What to do:

Try another authentication attempt without pausing.

Why it’s happening

The aud value in the client_assertion JWT is not correct.

What to do:

Check the aud key in the client_assertion JWT that is being sent in your token request.
Integration environment value: https://idp.int.identitysandbox.gov/api/openid_connect/token
Production environment value: https://secure.login.gov/api/openid_connect/token

More information about the client assertion values can be found here: https://developers.login.gov/oidc/token/#client_assertion.

Why it’s happening

OpenID Connect authentications must use either a PKCE or a private_key_jwt authentication menthod. Both methods require specific values to be sent in token endpoint request.

What to do:

If your integration is PKCE:

Ensure you are sending the code_verifier attribute as part of your token request. The value of this attribute is the original value of the code_challenge parameter sent in your original authentication request.

If your integration is private_key_jwt:

Ensure you are sending client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer as part of your token request.

More information about token request values can be found here: https://developers.login.gov/oidc/token/#request-parameters.

Why it’s happening

The code value being passed in the token request does not match any users. This typically happens when the code value is being reused in multiple token requests, or because the code value is not being passed in the token request.

What to do:

Ensure you are passing a code parameter in your token request.
Ensure there is no possibility of the code value in the token request being sent multiple times.

Reasons can include:

Browser is forcing an unexpected refresh
User refreshes browser

Why it’s happening

If you are using the PKCE protocol, the code_verifier value being passed in the token request does not match the decoded code_challenge value passed in the authentication request.

What to do:

Ensure that the code_challenge parameter is a URL-safe Base64 encoding of the SHA256 digest of the code_verifier parameter.

Why it’s happening

The iat value in the client_assertion JWT is the time at which the JWT was issued. It takes the format of an integer timestamp representing the number of seconds since the Unix Epoch. This error means that it is:

Not an integer or floating point Unix timestamp, OR
It is not an integer/timestamp that is in the past.

What to do:

Ensure your application is correctly generating the iat value in the client_assertion JWT.
If you are correctly creating the value, your server may be experiencing server time drift. Time drift can happen slowly over time. You may need to update or reset your server’s clock. We recommend syncing your system with a timeserver like https://time.gov/.

Why it’s happening

There is no registered certificate that matches the signature of the client_assertion JWT that is being passed as part of the token. request.

What to do:

Ensure that the public certificate that matches the private key used to sign the JWT is registered in your application’s configuration in the Partner Portal.

Userinfo endpoint

Why it’s happening

The userinfo endpoint requires an Authorization Header that includes a Bearer token. The Bearer token value is the access_token value from the token endpoint response.

What to do:

Ensure you are sending an Authorization header in your request to the userinfo endpoint.
Ensure the value of the header is Bearer followed by the access_token that was returned by the token endpoint.

Why it’s happening

The userinfo endpoint requires an Authorization Header.

What to do:

Ensure you are sending an Authorization header in your request to the userinfo endpoint.
Ensure the value of the header is Bearer followed by the access_token that was returned by the token endpoint.

Why it’s happening

The Bearer token value that is being passed as part of the userinfo endpoint request does not match a live user session. The value may be wrong, or there may have been a long pause during the authentication attempt.

What to do:

Ensure the Authorization header value is Bearer followed by the access_token that was returned by the token endpoint.
Try another authentication attempt without pausing.

Login.gov Errors

Background

Login.gov recognizes incoming requests from Service Providers by validating the Issuer (for SAML) or ClientID (for OIDC) field sent in the request and checking it against Service Providers registered with Login.gov. The Issuer for each Service Provider is defined in the Issuer field on the Login.gov Portal.

Screenshot of issuer field on Login.gov portal

This error occurs when Login.gov receives a request from a Service Provider that contains an Issuer/ClientID field that is not registered with Login.gov. The Issuer/ClientID defined in the request must match EXACTLY the Issuer defined in the Portal.

Solution:

Double check the SAML/OIDC request to Login.gov and confirm that the Issuer/ClientID field matches exactly what is defined in the Login.gov Portal. See Other Tips & Tools for help with decoding SAML Requests.

Note that certain Service Providers will not allow partners to set or change the Issuer value after the application is configured (e.g. MS Power Apps Portal). In this case, the best option would be to create the Login.gov Portal configuration after the Service Provider application has defined the Issuer and use that Issuer in the Portal.

SAML Request Example

​​<samlp:AuthnRequest AssertionConsumerServiceURL='https://sp.int.identitysandbox.gov/auth/saml/callback?utf8=%E2%9C%93&amp;loa=1'
                    Destination='https://idp.int.identitysandbox.gov/api/saml/auth'
                    ID='_6fca7b78-9ab7-49f5-bd62-18c48eac3c68'
                    IssueInstant='2017-02-23T20:36:17Z'
                    Version='2.0'
                    xmlns:saml='urn:oasis:names:tc:SAML:2.0:assertion'
                    xmlns:samlp='urn:oasis:names:tc:SAML:2.0:protocol'>
  <saml:Issuer>urn:gov:gsa:SAML:2.0.profiles:sp:sso:rails-int</saml:Issuer>
  <!-- ... -->
</samlp:AuthnRequest>

OIDC Request Example:

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

Background:

For both SAML and OIDC, the Authentication Context Class Reference field can be used to define the Identity Assurance Level (IAL) and Authentication Assurance Level (AAL) on a per-request basis. It can also be used to define which user attributes should be returned from Login.gov upon successful authentication.

This error occurs when Login.gov receives a request containing an unrecognized or unauthorized Authentication Context Class Reference value.

Solution:

Refer to the Login.gov Developer’s Guide for a list of accepted Authentication Context Class Reference values and ensure one or more of these values (and no others) are being sent in all authentication requests:

OIDC IAL Values

OIDC AAL Values

OIDC User Attributes - see "scope"

SAML IAL Values

SAML AAL Values

SAML User Attributes

Important Note for SAML Service Providers:

Login.gov requires AAL2 at minimum by default and so cannot accept AAL1 values for the Authentication Context Class Reference value unless the incoming requests allows Login.gov to increase the AAL to 2. For SAML requests, this means defining the optional Comparison field in the RequestedAuthContext SAML field as “minimum” or “better”. See below for a sample SAML request with an AAL of 1 and the optional Comparison field.

<samlp:AuthnRequest ...>
  <!-- ... -->
  <samlp:RequestedAuthnContext Comparison='minimum'>
    <saml:AuthnContextClassRef>urn:acr.login.gov:verified</saml:AuthnContextClassRef>
    <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef>
    <saml:AuthnContextClassRef>http://idmanagement.gov/ns/requested_attributes?ReqAttr=email</saml:AuthnContextClassRef>
  </samlp:RequestedAuthnContext>
</samlp:AuthnRequest>

Service Providers that cannot accommodate either sending a specific Authentication Context Class Reference or sending the optional Comparison field cannot currently be integrated with Login.gov.

See Section 3.3.2.2.1 of the SAML spec for more information.

Background:

For SAML Identity Providers, NameID is the unique identifier used to identify users across multiple sessions. The NameID Format field specifies the format of the NameID field and is defined and/or restricted by the Identity Provider.

This error occurs when Login.gov receives a SAML request with a NameIDPolicy who’se Format field does not match the NameIDFormat specified by Login.gov.

<samlp:NameIDPolicy AllowCreate='true'
                      Format='urn:oasis:names:tc:SAML:1.1:nameid-format:transient'/>

Solution:

Refer to the Login.gov Developers Guide for the acceptable values for the NameIdFormat SAML field. Update the Login.gov Identity Provider configuration within your Service Provider to specify the correct NameIDFormat field.

For SAML Service Providers, see Other Tips & Tools for help with decoding SAML Requests.

Browser Console Errors

: Background:

Content Security Policy (CSP) is a modern web browser defense for Cross-Site Scripting (XSS) attacks. For more information about CSP and XSS attacks, refer to the MDN documentation on CSP.

The CSP form-action directive restricts which URLs can be used as the target of form submissions from a given context. Certain Chromium-based internet browsers (e.g. Google Chrome and Microsoft Edge) enforce the form-action directive through the entire redirect chain (if any). Other non-Chromium-based browsers only check the first redirect in the chain (e.g. Firefox). For Chromium-based browsers, upon form submission, any attempts to redirect to a url not explicitly listed as a form-action source will violate the CSP directive and cause a failure to load and a console error.

This error occurs when Service Providers attempt to redirect users to a url that is not registered in the Redirect URLs field in the Login.gov Portal configuration. All urls that users could be redirected to, even as a passthrough, need to be included in the list of Redirect URLs.

Solution:

Use the Network tab of your web browser to identify which redirect (302) is hanging or failing. Add that uri to the list of Redirect URIs in your Login.gov Portal configuration.
: Login.gov uses the US Web Design System (USWDS) components on our websites. The current version (USWDS 3) supports the newest versions of Chrome, Firefox, and Safari. Internet Explorer 11 (IE11) is no longer officially supported and therefore is not recommended for use with Login.gov. If you experience issues connecting with Login.gov, try using one of the recommended browsers before contacting technical support.

Other Application Issues

: Background:

Any web application that authenticates its users must manage user sessions in order to avoid requiring their users to constantly re-authenticate. Often, this is done using a browser session token that gets passed back and forth between application resources. Session tokens can be valid for variable amounts of time and when they expire, users are required to re-authenticate. Login.gov does not provide a session token for Service Providers as Login.gov is an authentication service, not an authorization service. The authentication token returned from Login.gov is not a session token and should not be used as one.

Solution:

When Service Providers receive a successful authentication response from Login.gov, they should create their own session tokens within their application in order to track their users’ sessions.

Other Tips & Tools

SAML requests from browser consoles are URI encoded, base-64-encoded, and deflate-compressed. Here are steps to obtain a human-readable version of your SAML request.

Copy and paste the SAML request into a URI decoder (e.g. SAML Tool). Note that you will need to remove any flags that are included in the url (flags are denoted by an &).
Take the returned value from the URI decoder and use a base-64-decode and inflate tool (eg. SAML Tool).

Login.gov uses the cryptographic signatures of authentication requests to determine which public certificate to use when encrypting data in the SAML response. If the signature is not present, or cannot be validated successfully, you will encounter problems when you rotate your application’s key pair.

Check signature is present

If you are not sure whether your application is currently signing authentication requests, the easiest way to check is through the network tab in your browser's developer tools. Look for the URL generated when your app sends the user to Login.gov's sign-in page.

The signature could be sent in one of two ways:

As a parameter within the URL,
or as a field within the authentication request’s SAML data.

If the Signature and SigAlg URL parameters (and associated values) are present, your authentication request is signed.
If the signature is not part of the URL, it may be part of the SAML request. To check this, you will need to decode the data sent via the SAMLRequest parameter. The easiest way to do this is the "SAML Tracer" browser plugin. Our web-based tool can also help with this. Once decoded, you should see a section that contains all the relevant signature-related information and should be enclosed in a tag like:

<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

If there is no indication of a signature within the request URL or the request SAML, the request is not signed.

Check the signature algorithm

One common reason for failing signature validation is the use of an unsupported hashing algorithm, like SHA1. Login.gov only supports SHA256. Using the methods described above, check whether your request either contains a SigAlg parameter indicating the use of SHA256, or your SAML includes a tag indicating this, for example:

<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>

Check validity of signature

There may be other reasons Login.gov cannot successfully validate your application’s signatures using the information you have provided in the Login.gov Partner Portal for the application. We have created a web-based tool that lets you check this easily.

If you find your signature cannot be validated using this process, you will have to investigate what may be causing these problems and make changes on your side until validation succeeds.

Contacting Partner Support

The best way to reach out to the integration experience team is via our Zendesk portal. We understand email may be more convenient, but it is important that attachments and other information about your issue stay together. Attachments and email threads can become confusing when forwarded in a Zendesk ticket. For these reasons, we encourage partners to use our Zendesk portal rather than other methods whenever possible.

If you prefer using Slack, we have a slack channel for partners, #login-partner-support. You can request access to this channel by opening a Zendesk ticket. This channel includes other partners and Login.gov engineers that occasionally chime in. It should not be used as a substitute to Zendesk.

Before submitting your Zendesk ticket, please review the developer documentation on our website. Often the answers we will provide can be found there. When submitting a Zendesk ticket, particularly in cases when you are encountering an error, you can minimize your time to resolve the issue by providing the following information:

Link to your portal configuration
Screenshots of all error messages
What browser you were using
Time the error(s) occurred or if it is ongoing
Any relevant information recorded in your server logs

It is also highly recommended to include someone we can contact from your technical team when creating the Zendesk ticket in case we have further questions about how your application was configured.

Here is a list of common issues partners encounter that our team can assist with. This isn’t a comprehensive list but questions that fall into these categories can usually be answered.

Authentication failures while testing in sandbox environment
Questions about OIDC/SAML protocols
Problems with portal configuration (configuration not updating as expected)
Invalid PIV/CAC certificate errors (we may need to update certs on our end)
Problems updating or deploying a production configuration
Clarification about something in our developer docs
Any errors being returned by Login.gov during authentication
Suspected fraudulent activity / RISC notifications
Troubles with redirecting back to your application / Service Provider
Trouble reading or receiving expected user attributes
Users being unable to sign into production Service Provider (these are top priority to resolve, assuming it is related to Login.gov)
Feedback you want to share about your experience using the developer docs / portal (we are always looking to improve)
Any bugs you encounter in the portal or developer docs (broken links, user management issues, etc)

There are some cases where our team is unable to help, typically either for security or capacity reasons. We cannot assist with the following issues:

Setting up your integration for you (while we can provide additional tips and guidelines, we do not have the bandwidth nor access to your internal tools to provide this service)
Deleting, creating, or managing a user account (only the user themselves can access their account)
Specific programming language help (given the numerous different languages our partners use it is not possible for us to provide peer programming assistance)
Requests for network IP addresses (we use Cloudfront to manage our IP, so our IP addresses are not static)
Debugging network connection issues (if the connection isn’t going through, we cannot see it on our end and thus have very limited ability to troubleshoot)
Any kind of PII request (we do not give out PII for any reason)
Debugging your internal server setup (we can try to direct you to documentation but our server knowledge is limited)
Providing access to the portal (for security purposes, the portal is self service and anyone with a .gov / .mil address can provide access - View Product Deployment for further instructions)
You’ve found a vulnerability and want to report it (Instead, please submit through Login.gov Security Vulnerability Disclosure)

If you receive a complaint from a user having trouble logging in or managing their account, it is best to direct them to the Login.gov help center at https://www.login.gov/help/. Do not publish the Login.gov contact center phone number.

Edit this page