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
andageny_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
Production Well-Known Configuration Values
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.