Login.gov OAuth Provider

Descope provides the flexibility to add custom Social Login (OAuth) providers, including providers like Login.gov. This guide will help you configure a custom Login.gov OAuth provider within the Descope platform.

Creating the Login.gov Application

Before integrating the custom OAuth provider in Descope, you must first set up your application on Login.gov.

Note

Login.gov is used for government agencies. You will need to go through Login.gov's integration developer approval process to obtain a test account and get your application cleared for production. You can contact their Partner Support to get started, or if you have any Login.gov related questions.

Access Login.gov Developer Sandbox

Go to the Login.gov developer sandbox and select Create a new test app. Make sure to select PKCE as the authentication protocol and configure the necessary settings such as Level of Service and Attribute bundles.

Configuring Application Details

Add your application's details:

App Name: Specify app name.
Friendly name: Specify a name to display during the sign-in flow.
Team: Select the previously configured team to test the integration.
Authentication protocol: Select OpenID Connect PKCE
Level of service: Select the level of service as per your need. (Authentication only is IAL1 standard)
Issuer: A string in the following format. Fill in app_name and ageny_name with your own values: urn:gov:gsa:openidconnect.profiles:sp:sso:agency_name:app_name.
Logo: Optionally upload a logo for your application

A Client Secret should also be generated when you create this test app integration. You'll need this when you configure Login.gov as a custom provider in Descope.

Setting Redirect URIs

Set the redirect URI to be https://<your-base-url>/v1/oauth/callback. You can find your project's base url in our Multi-Region Support Guide.

Creating Descope Custom Provider

In Descope, navigate to the Customize Authentication Methods page and add a new custom provider. For this example, we will name the provider Login.gov.

Configure Account Settings

In the account settings:

Client ID: Use the Issuer from the Login.gov setup.
Client Secret: Generated in Login.gov App Setup.
Scopes: Configure scopes as needed for your application's access requirements. A full list of support scopes can be found here

Configure Connection Settings

Note

You can get the well known configuration URLs, for both sandbox and production here.

You'll need to input the OIDC endpoints that come from the Login.gov well known configuration. The values you'll need to input in the Console are listed below.

Identity Sandbox Well Known Configuration Values

https://idp.int.identitysandbox.gov/openid_connect/authorize
https://idp.int.identitysandbox.gov/api/openid_connect/token
https://idp.int.identitysandbox.gov/api/openid_connect/userinfo
https://idp.int.identitysandbox.gov/api/openid_connect/certs

Production Well-Known Configuration Values

https://secure.login.gov/openid_connect/authorize
https://secure.login.gov/api/openid_connect/token
https://secure.login.gov/api/openid_connect/userinfo
https://secure.login.gov/api/openid_connect/certs

Below is an example of the production well-known configuration values:

Configure User Attribute Mapping

Map the necessary user attributes based on the information provided by the Login.gov user info endpoint. For example, email and name.

Note

A full list of Login.gov supported attributes you can use to map can be found here

For more OAuth provider settings information, check out the OAuth Settings Guide. To add Login.gov Social Login to your flow, check out our Social Login In Flows Guide.

Was this helpful?

On this page