Add a Login.gov Identity Provider

This document explains how to configure Login.gov as an external Identity Provider for your application by creating an Identity Provider in Okta, creating an application at Login.gov, testing the configuration, and creating a Login.gov sign-in option.

Learning outcomes

Configure Login.gov as an external Identity Provider so that your users can quickly sign up or sign in to your application using their Login.gov account.

What you need

Okta Developer Edition organization (opens new window)
An application that you want to add authentication to. You can create a new app integration using AIW (opens new window) or use an existing one.
An account at Login.gov (opens new window). You also need a testing account at Login.gov's identity sandbox. See Login.gov - Partner Dashboard (opens new window).

About the connection to the IdP for your application

Okta manages the connection to the Identity Provider (IdP) for your application. The connection sits between your application and the IdP that authenticates your users. The industry-standard term for this is Inbound Federation. Okta uses the OpenID Connect (OIDC) protocol with private key JWT for inbound federation with Login.gov. When a user signs in, you can link the user's Identity Provider account to an existing Okta user profile or choose to create a user profile using Just-In-Time (JIT) provisioning.

Note: Okta also supports other services, such as directories and credential providers. See the Okta Integration Network Catalog (opens new window) to browse all integrations by use case.

Create an Identity Provider in Okta

Login.gov requires you to test your app integration (opens new window) in their identity sandbox before you can enable it in production. As a result, you have to first create a Login.gov IdP (Sandbox) configuration in Okta to test your app integration. When you're ready for Login.gov production deployment (opens new window), you can then create the production Login.gov IdP configuration in Okta.

Note: See the Identity Providers API for request and response examples of creating an Identity Provider in Okta using the API.

In the Admin Console, go to Security > Identity Providers.
Select Add Identity Provider and then select Login.gov IdP (Sandbox) for identity sandbox testing or Login.gov IdP for production. Click Next.
In the configure dialog, define the following:
- Name: Enter a name for the IdP configuration.
- Client ID: Specify an identifier for your IdP integration with Login.gov. This can be any string value, but must match the issuer value from Login.gov's configuration. You can use your Okta org URL as the client ID. For example: https://${yourCompanySubdomain}.okta.com
- Private key: The public/private key is available for download when you click Finish.
- Scopes: Leave the defaults (profile, profile:name, email) for IAL1 assurance. These scopes are included when Okta makes an OpenID Connect request to the IdP. See Login.gov OIDC scopes for required attributes (opens new window).
- Type of Identity Verification: The type of service level (opens new window) available for this application. Select ial/1 for standard MFA-protected email-based sign-in flows.
- AAL value: Select the authentication assurance level (opens new window) required.
  
  Note: If you leave the default value, the IdP requires a user to be authenticated with a second factor: urn:gov:gsa:ac:classes:sp:PasswordProtectedTransport:duo.
In the optional Authentication Settings section:
- IdP username: This is the expression (written in Okta Expression Language) that is used to convert an IdP attribute to the application user's username. This IdP username is used for matching an application user to an Okta User.
  
  For example, the value idpuser.email means that it takes the email attribute passed by the IdP and maps it to the Okta application user's username property.
  
  You can enter an expression to reformat the value, if desired. For example, if the IdP username is john.doe@mycompany.com, then you could specify the replacement of mycompany with endpointA.mycompany to make the transformed username john.doe@endpointA.mycompany.com. See Okta Expression Language.
- Match against: Specifies which attributes of existing users in Okta are compared to the IdP username to determine if an account link needs to be established. If an existing account link is found, no comparison is performed.
- Account link policy: Specifies whether Okta automatically links an incoming IdP user to the matched Okta user. If disabled, Okta doesn't link an incoming IdP user to an existing Okta user and relies solely on manually or previously linked accounts. See Account link.
Click Finish. A page appears that displays the IdP's configuration.
Copy both the Authorize URL and the Redirect URI, and then paste into a text editor for use in the upcoming steps.
Click Download public key to download the JSON-formatted public key for your Login.gov configuration.

Note: You need to configure two IdPs in Okta:

Login.gov IdP (Sandbox) for testing

Login.gov IdP for production

Optional attribute mappings

When you create the Login.gov IdP configuration in Okta, the Login.gov attributes are already mapped to Okta user profile attributes. However, these Login.gov attributes aren't mapped: ial and aal. If you need these attributes in Okta, use the Profile Editor to map them to Okta custom attributes. See App to Okta attribute mapping in About attribute mappings (opens new window).

Account link

You can automatically link external IdP accounts to Okta accounts when the user signs in using the external IdP. If Account Link Policy is set to Automatic (AUTO), then Okta searches the Universal Directory for a user's profile to link. The user profile is found when the IdP username value (email) passed by the IdP matches the Match against value (username). See Account Linking and JIT Provisioning.

To remove an existing account link or validate account linking with every sign-in flow, Okta recommends that you make a DELETE call to the /api/v1/idps/${idpId}/users/${userId} endpoint to remove the link between the Okta user and the IdP user before authentication.

If Account Link Policy is disabled, no account linking occurs. You can manually create an account link without a transaction by making a POST call to the /api/v1/idps/${idps}/users/${userId} endpoint.

See Add an Identity Provider for API examples of account-linking JSON payloads.

For security best practices, consider disabling account linking after all existing users from the external IdP have signed in to your Okta org. At this point, all links have been created. After you disable linking and JIT provisioning is enabled, Okta adds new users that are created in the external IdP.

Create an app at the Identity Provider

At Login.gov, you need to first register your app integration in Login.gov's identity sandbox for testing before you can enable it for production. See Testing your app (opens new window).

Sign in to the Partner Dashboard (opens new window) and register your app for testing.
Follow the instructions at Testing your app (opens new window) to create a team and add users to that team.
Click Create a new test app from the Apps tab and specify the following attributes specific to the Okta test integration:
- Production Configuration: Select No for testing.
- App Name: Specify the app name.
- Friendly name: Specify a friendly name to display during the sign-in flow.
- Team: Select the previously configured team to test the integration.
- Authentication protocol: Select OpenID Connect Private Key JWT.
- Identity Assurance Level (IAL): Select the maximum level of identity assurance available for your app. Ensure that this value matches the Type of Identity Verification value specified in Create an Identity Provider in Okta.
- Default Authentication Assurance Level (AAL): Select AAL required. Ensure that this value matches the AAL value specified in Create an Identity Provider in Okta.
  Note: If you leave the default value, Login.gov requires a user to be authenticated with a second factor: urn:gov:gsa:ac:classes:sp:PasswordProtectedTransport:duo. See AAL Values (opens new window).
- Attribute bundle: Select the default attributes for Login.gov to return during authentication. Select at least email, profile, and profile:email.
- Issuer: Specify a string that matches the Client ID value in your Okta Login.gov IdP configuration from Create an Identity Provider in Okta. Typically, your Okta org URL is used. For example, if your Okta subdomain is company, then specify https://company.okta.com.
- Certificates: Upload the public key file that you downloaded from Create an Identity Provider in Okta.
- Redirect URIs: Specify the Okta Redirect URI that you copied from Create an Identity Provider in Okta. For example, if you don't have a custom domain, this value is usually https://${yourCompanySubdomain}.okta.com/oauth2/v1/authorize/callback.
Click Create test app.

Note: Login.gov configures the production deployment for you. You can request Login.gov for a production deployment (opens new window) after you finish testing.

Test the integration

To test your integration, you need to first configure a routing rule (opens new window) to use Login.gov as the Identity Provider.

There are four ways to initiate the IdP sign-in flow:

Use an embedded Okta Sign-In Widget
Use a custom Okta-hosted Sign-In Widget
Use an HTML link
Use the AuthJS SDK

Okta also offers an easily embeddable JavaScript widget that reproduces the look and behavior of the standard Okta sign-in page for your client app. See Embedded Sign-In Widget use cases for Okta Identity Engine or Embedded Okta Sign-In Widget fundamentals for Okta Classic Engine.

To test the Login.gov IdP sign-in flow with your embedded widget app, navigate to your app's sign-in page and click the Sign in with Login.gov option. This option directs you to the Login.gov sign-in page. Use your Login.gov credentials to test the sign-in flow.

If you're using Identity Engine, the Sign in with Login.gov option is available on the widget after you create an Identity Provider in your Okta org and configure the routing rule (opens new window). No additional code is required.

If you're using Classic Engine, you still need to configure the routing rule (opens new window). Additionally, you need to add the following code to your Okta Sign-In Widget configuration to display the Sign in with Login.gov button:

    config.idps= [
        { type: 'LOGINGOV_SANDBOX', id: 'Your_IDP_ID' }
    ];
    config.idpDisplay = "SECONDARY";

You can find out more about the Okta Sign-In Widget on GitHub (opens new window). Implementing sign-in flows with an Identity Provider uses the widget's OpenID Connect authentication flow (opens new window).

Note: For a production environment, use the following Okta Sign-In Widget configuration:
   config.idps= [
       { type: 'LOGINGOV', id: 'Your_IDP_ID' }
   ];
   config.idpDisplay = "SECONDARY";

If your client app uses Okta redirect authentication, then to test the Login.gov IdP sign-in flow, navigate to your app's sign-in page and click the Sign in with Login.gov option. This option directs you to the Login.gov sign-in page. Use your Login.gov credentials to test the sign-in flow.

If you're using Classic Engine, you still need to configure the routing rule (opens new window). Additionally, you need to customize your Okta-hosted Sign-In Widget to display the Sign in with Login.gov option.

Add the following code beneath the var config = OktaUtil.getSignInWidgetConfig(); line in the Custom Sign in tab:

config.idps= [
  {type: 'LOGINGOV_SANDBOX', id: 'Your_IDP_ID'}
];
config.idpDisplay ="SECONDARY";

Note: For a production environment, use the following code beneath the var config = OktaUtil.getSignInWidgetConfig(); line:
   config.idps= [
       { type: 'LOGINGOV', id: 'Your_IDP_ID' }
   ];
   config.idpDisplay = "SECONDARY";

Use an HTML link

You can use the authorize URL to simulate the authorization flow from your browser. Test this in your browser's privacy or incognito mode to avoid false positive or negative results. If everything is configured properly:

The user is redirected to the Identity Provider's sign-in page.
After successful authentication, the user is redirected to the redirect URI that you specified, along with an #id_token= fragment in the URL. The value of this parameter is your Okta OpenID Connect ID token.

If something is configured incorrectly, the authorization response contains error information to help you resolve the issue.

The Okta Identity Provider that you created generates an authorize URL with a number of blank parameters that you can fill in to test the flow with the Identity Provider. For example:

https://${yourOktaDomain}/oauth2/v1/authorize?
  idp=${yourIdPId}&
  client_id=${clientId}&
  response_type=${responseType}&
  response_mode=${responseMode}&
  scope=${scopes}&
  redirect_uri=${redirectUri}&
  state=${state}&
  nonce=${nonce}

Note: If you are using Authorization Code with PKCE as the grant type for your client app, you must generate and store the PKCE. See Implement authorization by grant type. Okta recommends that you use the AuthJS SDK (opens new window) with this grant type.

In the URL, replace ${yourOktaDomain} with your org's base URL, and then replace the following values:

idp: Your ${yourIdPId} value that you obtained from Create an Identity Provider in Okta.
client_id: Use the ${clientId} value that you obtained from your OpenID Connect client application. This isn't the Client ID value from the Identity Provider.
response_type: Determines which flow is used. For the Implicit flow, use id_token. For the Authorization Code flow, use code.
response_mode: Determines how the authorization response is returned. Use fragment.
scope: Determines the claims that are returned in the ID token. Include the scopes that you want to request authorization for and separate each by a space. You need to include at least the openid scope. You can request any of the standard OpenID Connect scopes about users, such as profile and email, as well as any custom scopes specific to your Identity Provider.
redirect_uri: The location where Okta returns a browser after the user finishes authenticating with their Identity Provider. This URL must start with https and must match one of the redirect URIs that you configured in the previous section.
state: Protects against cross-site request forgery (CSRF). Can be any value.
nonce: A string included in the returned ID token. Use it to associate a client session with an ID token and to mitigate replay attacks. Can be any value.

Note: When Okta sends the authorize request to Login.gov, it adds the required acr_values based on the type of identity verification that you specified in the Login.gov IdP configuration.

For a full explanation of all of these parameters, see: /authorize Request parameters.

Create a link that the user clicks to sign in. The HREF for that link is the authorize URL with your specified values. For example:

`<a href="https://${yourOktaDomain}/oauth2/v1/authorize?idp=0oaaq9pjc2ujmFZexample&client_id=GkGw4K49N4UEE1example&response_type=id_token&response_mode=fragment&scope=openid&redirect_uri=${yourAppRedirectUrl}&state=WM6D&nonce=YsG76jo">Sign in with Login.gov</a>`

After the user clicks the link, they are prompted to sign in with Login.gov. After successful sign in, the user is returned to the specified redirect_uri along with an ID token in JWT format.

Use the AuthJS SDK

If you don't want pre-built views, or need deeper levels of customization, then you can use the same AuthJS SDK that the Sign-In Widget is built with. See the idp option in the AuthJS SDK GitHub repo (opens new window).

Next steps

You should now understand how to add the Login.gov Identity Provider and have successfully added and tested the integration.

To map Okta attributes to app attributes, use the Profile Editor (opens new window).

To add another Identity Provider, start by choosing an external Identity Provider.

Edit This Page On GitHub

On this page

Add a Login.gov Identity Provider

Learning outcomes

What you need

About the connection to the IdP for your application

Create an Identity Provider in Okta

Optional attribute mappings

Account link

Create an app at the Identity Provider

Test the integration

Embedded widget with Identity Engine

Embedded widget with Classic Engine

Okta-hosted widget with Identity Engine

Okta-hosted widget with Classic Engine

Use an HTML link

Use the AuthJS SDK

Next steps

On this page

Add a Login.gov Identity Provider

Learning outcomes

What you need

About the connection to the IdP for your application

Create an Identity Provider in Okta

Optional attribute mappings

Account link

Create an app at the Identity Provider

Test the integration

Use an embedded Okta Sign-In Widget

Embedded widget with Identity Engine

Embedded widget with Classic Engine

Use a custom Okta-hosted Sign-In Widget

Okta-hosted widget with Identity Engine

Okta-hosted widget with Classic Engine

Use an HTML link

Use the AuthJS SDK

Next steps