# Login.gov OIDC single sign-on

<!-- Generated by scripts/generate.ts. Do not edit. -->

Create an OpenID Connect app in Login.gov, add the redirect URI from this setup, assign your users and enter the app's issuer and credentials here.

:::caution[Only for government partners]
Login.gov is available to US government agencies and the partners they work with under an agreement. Your agency's Login.gov team account must own the app.
:::

:::caution[Verification]
Not yet verified on a real Login.gov tenant. It was written from the public Login.gov documentation, so labels in the admin console may differ slightly.
:::

The values in braces, such as `{redirect_uri}`, are specific to your connection. The setup link from the application you are connecting shows them with a copy button. The same steps appear there.

## Steps

<ol class="idp-steps">

<li class="idp-step">

<a id="create-app"></a>

### Create an OIDC app

In the Login.gov Partner Portal, create an app for this integration in the sandbox first, and choose OpenID Connect with private_key_jwt as the authentication method.

:::caution[Labels not confirmed in step 1]
The Login.gov page read on 2026-10-29 names the Partner Portal and certificate upload but not its form labels.
:::

</li>

<li class="idp-step">

<a id="redirect-uri"></a>

### Add the redirect URI

Add `{redirect_uri}` to the app's sign-in redirect URIs, exactly as shown. A redirect URI that differs by one character is refused.

<div class="setup-values">

Paste into Login.gov:

- Redirect URI: `{redirect_uri}`

</div>

Fixes: [`oidc_token_exchange_failed`](/errors/oidc_token_exchange_failed/)

</li>

<li class="idp-step">

<a id="certificate"></a>

### Upload the public certificate

Login.gov does not use client secrets. Upload the public certificate this setup gives you to the app in the Partner Portal. This app signs its token requests with the matching private key, which never leaves it.

Fixes: [`oidc_token_exchange_failed`](/errors/oidc_token_exchange_failed/)

</li>

<li class="idp-step">

<a id="scopes"></a>

### Allow the sign-in scopes

Allow the openid and email scopes. This setup asks for the authentication-only assurance level (urn:acr.login.gov:auth-only) on every sign-in, so you do not set acr_values yourself.

Fixes: [`oidc_email_missing`](/errors/oidc_email_missing/), [`oidc_email_not_verified`](/errors/oidc_email_not_verified/)

</li>

<li class="idp-step">

<a id="client-id"></a>

### Enter the issuer and client ID

Enter the app's client ID (the issuer string you chose in the Partner Portal) in this setup. The provider's issuer URL is "https://secure.login.gov/" in production; the sandbox uses its own address, listed in Login.gov's developer documentation.

Fixes: [`oidc_discovery_unreachable`](/errors/oidc_discovery_unreachable/), [`oidc_id_token_invalid`](/errors/oidc_id_token_invalid/)

</li>

<li class="idp-step">

<a id="test"></a>

### Test the connection

Run a test sign-in in this setup, signing in as a user you assigned to the app.

</li>

<li class="idp-step">

<a id="production"></a>

### Move to production

When test sign-ins work in the sandbox, request a production deployment of the app through the Partner Portal, then update the issuer URL and certificate in this setup if they changed.

:::caution[Labels not confirmed in step 7]
The production deployment request was not checked against a public Login.gov page.
:::

</li>

</ol>

## Sources

- [OpenID Connect (Login.gov developer documentation)](https://developers.login.gov/oidc/getting-started/), read on 2026-10-29
- [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html), read on 2026-10-29
