Using 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. 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 adoption and also meet the agency where they are for any other Identity-proofing approaches they take.

If 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

What is 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, enables people to access public benefits programs with the same username and password for participating government agencies. As of September 2022, is helping 41 million people keep their information safe when they access government services online.

How does Okta connect to applications?

Okta enables 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, 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 credentials and receive System for Cross-domain Identity Management (SCIM) or Just-In-Time (JIT) provisioning, linking the users’ 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
  4. A partner account for

Before enabling your application in production, 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 sandbox and integrate with the Identity Provider in Okta. 
  2. Production Ready - When ready, create the production partner application in 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 chicklet and click the Next button

0JYrF4rO9IjyztFq 6aca WS3s52oY0R60cbX6fMTWG749Eya5SLqyL5M 39Pdu6AzW5dW zRMO1UBjyz40K7YEoTSGlmTj rotyYHWiYeu1s H6gmuL0CjjkjxkSNm3EAhZVdEMAY 1o6fKhwyaJiE

Configuring’s integration

General Settings Configuration 


  1. Name: Enter a name for the IdP configuration.
  2. IdP Usage: This setting determines how Okta evaluates in its Authentication Policy criteria. Select SSO only if is to be considered as a knowledge factor and select Factor Only if is to be treated as a possession factor. 
  3. Client ID: Enter an identifier for your IdP integration with This can be any string value but it must match the issuer value from's configuration. You can use your Okta org URL as the client ID. For example https://${yourCompanySubdomain}
  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.

  1. 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 OIDC scopes for required attributes 
  2. 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 identities.
  3. 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

Authentication Settings Configuration

349juA5mqBxjKx9GnqYS41woNe6zT1mfNG0v0pXFabOBte1y dUwvJcLX0WpYh 3byn8rClXCtmiPftGIgoqxtf1bHGUhKJoCbhpa Rwy R30vO c XeC6Kt6wILz euGlEbHi02cMJi79DTUxs G80


  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 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 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

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

QiBcSDqI58n1WrVfcVtsoZ8Pkvftck6M7UPEyUyVESblIw1C23yslfpBuBsNqsCIr4of fnyRP3cfoSAR9o8WT1quikw qTjgfGj1xiIUL4oMfx1dY xCf0PiUx5G6dzQyxfBeCONZaLFPHdVYemTTo

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

ZytJ7XQblIJhDHiFf5LpXvJcFR2TVJ1NEBlHGVyOj 1oGs pQ8 xEVn4Tdpa jr06W4GPfkSLALoudh czFBK2v07VaYeMLuZINGewZqXJD uJuS51TehlA LW1ZmRAAJFl wvlNHlp58yRjzPGc8W4

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.

k3 G5Kpqr4LKPzS hvGxqJq1WK3lDu6e Vw9KjsMrtIDIwZ6Q31tW6 PARQR7kf1H74YQCIcifnv G73woZ5vKx5S06flJf1mQ1OzpyUjwav vaftcQV975G6qz6fWliIxvl88Mb4K4bnZdOZod Us0

  1. Select Any of the following applications: radio button and add your public application to the list.
  2. Add your IdP for the IdP(s) field.
  3. Click the Create rule button. 
  4. Click on Activate Rule.

For more information, check out Routing Rules documentation.

Adding a partner application in

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

Creating an application

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


NQw vHzQ95fIx0aaoGfw5eY0WGAuP8 VIZva7Ox7IDQlVj6tD7rIfTosfbhV9TtVbQrzYo34VZiXWXL60ZY5lP8BEUYNEl7IIGDUDsX1jInmh7bqVZOEjloMgg joMukrkmTO2oKReUrtikjmhxFH2g


 PtUg44k 1mo Py 6yphYDRcThwP3qK u5SGuuzh Ohm1hJlOZP6ooapZSQvwSX6hZZC1Asl9uh4dRQCz5adTX1OidyR uzb 4XVt Rn97sNH l76l Hgy3tSCfQSK tYYhuInmAzGeHGzn4Jde2Nrw

  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.

NGrzHspiPeP nRAADbcqYX3V snxc1DMGxgC5qsqr8 9WjA57OATtiZcmAUcldOowSGxG2sgCo41eRIQzHbhzc09NipSQ4Ov7u7J88py8Aa6zc oyfDlWaqk3NdhqeCQewdAgCDa4XjZ dbMtBzlSn4

  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) .

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

7 pPRlL8yo8ubyZ916KauhPpwn IeoPLOD38KFhT1kYV05vsgSyNnbz2 bCEgJcRmw3bEynsN2pB5HfJaEdaWk7kgScGcKAOkAFiTj3cIFbPCD5ENX fhAvUwwEYwcB0FfiNXIwxtB20EJxlpDrak0Q

  1. Issuer: Specify a string that matches the Client ID value in your Okta 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
  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 

Ktbuh3axR9YknXWnSSYhiDTR4wxZTcO0fv DWMY5xOPbiLlv8UWkd1WjI6qMO yFeE7jxyBGnLX0cYWpk4mSwtIqPY 7DXdynJgtYE2p0AkVCl7ulXuMo05keYgT gzJnwbDe45I8AvMwFOGRWZkkHY

  1. Create new file using same editor and copy paste x5c content only
  2. 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:

quPzog3k0ntf ThqllAau0su8uNyyG93Nq8X7c2Pu60qhjTY2kp Ap3kVJN4gKq8l65BaY9YKgxnn58FhzQZcn59r4UNj0yEjJDyPmKsS p6Z8n3PsvVmGzauZoumhFnRXL6CEnZ3c3olkDiZ0U0Gj4

  1. Save this file as a .pem extension.
  1. 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}

4. Click the Create a Test App button.

Testing your new IdP as 

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


  1. Valid certificate in Tenant app
  2. Redirect URL is configured properly in 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 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 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].