Using Login.gov as a Custom Identity Verification and Authentication Service in Okta

The impact of the pandemic continues to demonstrate the need to improve the security and user experience of public-facing government digital services. Beneficiaries demand and deserve both, and the US Government is responding with strategy and funding to improve fraud prevention and reduce identity theft. Part of that commitment involves simpler access that provides benefits to the intended beneficiary. Login.gov is expected to have a leading role as a whole-of-government modernization effort of identity verification systems to support stronger preventative steps.

Okta can accelerate and enable Login.gov adoption and also meet the agency where they are for any other Identity-proofing approaches they take.

If Login.gov is your preferred Identity Provider (IdP), Okta provides a streamlined, simple, and automated onboarding process for developers and a social sign-on option for government customers. In this post, you will learn how to create and set up Okta with Login.gov.

What is Login.gov?

Login.gov is a component of the U.S. General Services Administration’s (GSA) Technology Transformation Services (TTS) under the Federal Acquisition Service (FAS). A secure and trusted single sign-on service for U.S. government websites, Login.gov enables people to access public benefits programs with the same username and password for participating government agencies. As of September 2022, Login.gov is helping 41 million people keep their information safe when they access government services online.

How does Okta connect Login.gov to applications?

Okta enables Login.gov to be an IdP for government applications, similar to the private sector’s social logins (e.g. signing in with your Apple account). For inbound federation with Login.gov, Okta employs the OpenID Connect (OIDC) protocol. Users can integrate their public-facing apps using the Okta Integration Network (OIN). With Okta as a broker, users can add asynchronous workflows, access control policies, and additional authentication factors. The public can then authenticate with their Login.gov credentials and receive System for Cross-domain Identity Management (SCIM) or Just-In-Time (JIT) provisioning, linking the users’ Login.gov account to the applications.

Getting started 

To get started with this tutorial, you will need the following prerequisites 

1. Okta Developer Edition Tenant 
2. Enable "Private Key JWT Client Authentication for OIDC IdP" under Okta Tenant Settings > Features.
3. Create an application in Okta Tenant for which you want to add Login.gov
4. A partner account for Login.gov

Before enabling your application in production, Login.gov requires that you test it in their Identity sandbox.

1. Sandbox Testing - To test your app integration, you must first set up Okta as a partner application in the Login.gov sandbox and integrate with the Login.gov Identity Provider in Okta. 
2. Production Ready - When ready, create the production partner application in Login.gov and the corresponding production Identity Provider configuration in Okta.

Pro Tip - The process of configuring both types of IdP applications is the same. 

Adding an Identity provider 

1. Log in to your Okta console and navigate to Security –> Identity Providers 
2. Click on Add Identity Provider 
3. Select the Login.gov chicklet and click the Next button

Configuring Login.gov’s integration

General Settings Configuration 

1. Name: Enter a name for the IdP configuration.
2. IdP Usage: This setting determines how Okta evaluates Login.gov in its Authentication Policy criteria. Select SSO only if Login.gov is to be considered as a knowledge factor and select Factor Only if Login.gov is to be treated as a possession factor. 
3. Client ID: Enter an identifier for your IdP integration with Login.gov. This can be any string value but it 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
4. Private key: The public/private key is available for download when you click Finish.

NOTE: If you see Client Secret instead of Private Key, cancel, and complete the prerequisite step of enabling Private Key JWT Client Authentication for OIDC IdP.

5. 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 
6. Type of Identity Verification: The required level of identity assurance available for this application. Select ial/1 to allow self-asserted users without identity verification. Select ial/2 to require identity-proofed Login.gov identities.
7. AAL value: Select the authentication assurance level. 
   1. Select default to allow users with only a single factor.
   2. Select aal/2 to require users to have authenticated with a second factor, but allow non-cryptographically-based factors like one-time pin (TOTP) from mobile authenticators. Users must authenticate with a different second factor every 12 hours.
   3. Select aal/3 if users are required to authenticate with cryptographically-based solutions like WebAuthN or PIV/CAC.
   4. Select aal/3?hspd12=true for PIV/CAC only.

Note - The access token will be populated with a claim of "login_aal": urn:gov:gsa:ac:classes:sp:PasswordProtectedTransport:duo if the user has authenticated with a second factor at Login.gov.

Authentication Settings Configuration

1. 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.
   • For example, if the IdP username is [email protected], but your Okta username format is [email protected], you can use the Okta Expression Language to transform the username from Login.gov automatically to match the value in Okta.
2. Match against: This specifies which attributes of existing users in Okta are compared to the IdP username for establishing account linking. If a link to an existing account is discovered, no comparison is carried out.
3. Account link policy:  This specifies whether Okta automatically associates an incoming IdP user with the corresponding Okta user. If disabled, Okta will not link an incoming IdP user to an existing Okta user, instead relying on manually or previously linked accounts.
4. Click on Finish

Pro Tip: Copy both the Authorize URL and the Redirect URL, and then paste them into a text editor to use in the upcoming steps.

Downloading the Public Key 

You need to download the Public Key to configure the partner application in Login.gov

1. Select Security > Identity Providers > Your Login.gov IdP
2. Click on Actions > Configure Identity Provider 

3. Scroll the page and go to Private key > Download public key

Pro Tip: Save this key at a safe place and generate the PEM file, which you will need for the next step in the Login.Gov partner tenant. 

Update the Routing Rules 

To make this work or test as default flow, you need to update the routing rules

1. Select Security > Identity Providers
2. Click on the Routing rules tab.
3. Click on the Add Routing Rule button.

4. Select Any of the following applications: radio button and add your public application to the list.
5. Add your Login.gov IdP for the IdP(s) field.
6. Click the Create rule button. 
7. Click on Activate Rule.

For more information, check out Routing Rules documentation.

Adding a partner application in Login.gov

According to the Login.gov partner process, we will first make the app for testing and then move it to production. Complete the following steps at Login.gov.

Creating an application

1. Login into your Login.gov Partner Dashboard. 
2. Click on Apps at the top right navigation bar.
3. Click on the Create a new test app button.

1. Production Configuration: Select No for testing.
2. App Name: Specify app name.
3. Friendly name: Specify a friendly name to display during the sign-in flow.
4. Team: Select the previously configured team to test the integration.

1. Authentication protocol: Select OpenID Connect Private Key JWT.
2. Level of service : Select the level of service as per your need. (Authentication only is IAL1 standard)

Pro tip: Make sure this value is the same as the Type of Identity Verification value you chose when you set up an identity provider in Okta(You Okta IdP Configuration) .

3. Attribute bundle: Select the default attributes for Login.gov to return during authentication. Select at least email, profile, and profile:email.

1. Issuer: Specify a string that matches the Client ID value in your Okta Login.gov IdP configuration from the Create an Identity Provider in Okta step. Typically, your Okta org URL is used. For example, if your Okta subdomain is company, then specify https://company.okta.com.
2. Certificates: Upload the public key file that you downloaded during the Create an Identity Provider in Okta step. (see below steps for creating a .pem file.)

How to create PEM file

1. Open the json file you have downloaded from Okta IdP Integration setting in any text editor 

2. Create new file using same editor and copy paste x5c content only
3. Making sure to not add any additional carriage returns, add the following line before the pasted content -----BEGIN CERTIFICATE----- and the following line -----END CERTIFICATE----- after the pasted content. The finished product should look like the following:

4. Save this file as a .pem extension.

3. Redirect URIs: Specify the Okta redirect URL that you copied during the Create an Identity Provider in Okta step. If you don't have a custom domain, this value is usually https://${yourCompanySubdomain}.okta.com/oauth2/v1/authorize/callback.

4. Click the Create a Test App button.

Testing your new IdP as Login.gov 

You have now completed all the tasks; let's test our integration. But make sure to do a few checks first.

Checks:

1. Valid certificate in Login.gov Tenant app
2. Redirect URL is configured properly in Login.gov Tenant app
3. Routing Rule updated in your Okta Tenant and has precedence
4. The application you are using to conduct this test is operating without any issues

Let's test now:

1. Open your end-user application in a browser 
2. Click on the login button 
3. As per setup, it should now redirect to the Login.gov URL and ask for credentials 
4. Enter credentials 
5. Enter MFA (If applicable)
6. Log in

You can also check out this recording for a full demonstration of the above steps:

Learn more

If your goal is to adopt Login.gov as your preferred IdP and reduce sign-up friction and major security vulnerabilities, Okta makes it easy with our out-of-the-box integration, which can be set up and running in a few clicks. For a personal demonstration, please contact us at [email protected].