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.

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:

1. App Name - Specify app name.
2. Friendly name: Specify a friendly name to display during the sign-in flow.
3. Team - Select the previously configured team to test the integration.
4. Authentication protocol - Select OpenID Connect PKCE
5. Level of service - Select the level of service as per your need. (Authentication only is IAL1 standard)
6. Issuer - a string in the following format: urn:gov:gsa:openidconnect.profiles:sp:sso:agency_name:app_name. You cann fill in app_name and ageny_name with your own values.
7. Logo - Upload a logo if you wish.

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

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.

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.