Login.gov OAuth Provider
Descope provides the flexibility to add custom Social Login (OAuth) providers, including services like Login.gov for government-based authentications. 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 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 friendly 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:
urn:gov:gsa:openidconnect.profiles:sp:sso:agency_name:app_name
. You cann fill inapp_name
andageny_name
with your own values. - Logo - Upload a logo if you wish.
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
You shouldn't need a redirect URI, as by default the request should return to wherever the flow is hosted, however if you want to configure this you can.
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
Advanced Settings (Optional)
Configure advanced options as per your application requirements, such as token management, callback domain, and account merging based on email addresses.
Implementing in Descope Flows
Integrate the custom Login.gov provider into your Descope flows, updating login screens and actions to utilize this new authentication method.
Utilize within Descope SDK
When utilizing your Login.gov custom provider within the Descope SDKs, you will pass
the provider as Login.gov
which is the name of the provider which you configured. Note that
this is case sensitive to how you configured here.