Set up Login.gov single sign-on

Use this process to let customers sign in to your store with Login.gov, the US General Services Administration’s shared sign-in service for federal government websites. Choose Login.gov when your store serves a US federal agency whose users already hold Login.gov accounts.

Login.gov differs from other OpenID Connect providers in one way: Login.gov does not use a client secret. Instead, you create an RSA keypair, register the public certificate with Login.gov, and store the private key on the Authentication Provider record. StoreConnect uses the private key to sign each token request.

For the other login methods and the login behavior they all share, see authentication providers and single sign-on (SSO).

Before you start

• You need access to a team in the Login.gov Partner Portal. Federal agency staff with a .gov or .mil email address can create a sandbox account at https://portal.int.identitysandbox.gov/. Contractors must be added to a team by their agency partner.
• You need access to edit the Store record in Salesforce.
• You need a machine with the openssl command available to generate the keypair.
• Decide whether to keep username and password login. Once a Login.gov provider is active, the store’s login page shows only the Login.gov button. To offer both, the store also needs an active StoreConnect Username / Password provider record, as described in StoreConnect authentication.
• If Login.gov does not appear in the Provider picklist on Authentication Provider records, add it in Setup > Object Manager > Authentication Provider > Fields & Relationships > Provider. Enter the value login_gov exactly, in lowercase, because StoreConnect matches on this value.
• For production, your agency needs an Interagency Agreement (IAA) with Login.gov that lists this integration. Allow up to 6 weeks if no IAA exists yet, plus around 2 weeks of deployment notice, so start early.

Step 1: Create the RSA keypair

You create the keypair yourself. The public certificate goes to Login.gov, and the private key goes on the Authentication Provider record.

1. On a machine with openssl, generate a 2048-bit keypair and a self-signed certificate:

   openssl req -nodes -x509 -days 365 -newkey rsa:2048 -keyout private.pem -out public.crt

2. Encode the private key as base64, and keep the output for Step 3. On macOS:

   base64 -i private.pem

   On Linux, use base64 -w 0 private.pem so the output stays on a single line.

3. Store private.pem securely. Anyone holding the private key can impersonate your store to Login.gov.

Step 2: Register your application in the Login.gov Partner Portal

Do this step in the Login.gov Partner Portal (https://portal.int.identitysandbox.gov/ for the sandbox).

1. In your team, create a new application.
2. Set the protocol to OpenID Connect with private_key_jwt.
3. Set the issuer string for your application. Login.gov uses reverse-domain style issuer strings, for example urn:gov:gsa:openidconnect.profiles:sp:sso:youragency:yourstore. Record the issuer string for Step 3. It is your client ID.

4. Add the redirect URI for your store domain. For a store at shop.example.com, the redirect URI is:

   https://shop.example.com/logins/auth/login_gov/callback

   If the store is served on a path rather than its own bare domain, StoreConnect adds the path to the redirect URI as a query string. Register the redirect URI with the query string included. For a store at shop.example.com/eu, the redirect URI is:

   https://shop.example.com/logins/auth/login_gov/callback?store_path=eu

5. Upload the public.crt certificate from Step 1.
6. Save the application.

Step 3: Create the authentication provider record

1. On the Store record, go to the Authentication Providers related list, and select New.

2. Configure the record as follows.

   StoreConnect Field	Value
   Provider	Login.gov
   Authorised Domains	Leave blank. Login.gov does not use this field
   Client Id	The issuer string from Step 2, for example urn:gov:gsa:openidconnect.profiles:sp:sso:youragency:yourstore
   Client Secret	Leave blank. Login.gov does not use client secrets
   Provider URL	https://idp.int.identitysandbox.gov for the sandbox, https://secure.login.gov for production
   Reset Password URL	https://secure.login.gov/account to send customers who select the store’s forgot-password link to their Login.gov account page. Otherwise, leave blank
   Api Options	See the next step

3. Set Api Options to the base64-encoded private key from Step 1:

   ```yaml

   private_key_base64: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUV2UUlCQURBTkJna3Fo… ```

4. Select Active.
5. Save the record.
6. Confirm the provider works. Open your store in a private browser window, select Sign in or up via Login.gov on the login page, and complete a sign-in with a Login.gov sandbox account.

The store’s login page now shows a Sign in or up via Login.gov button. Completing the sign-in signs the customer in and creates or links their Contact record.

Step 4: Move to production

The sandbox and production are separate Login.gov environments with separate registrations.

1. Confirm your agency’s Interagency Agreement lists this integration.
2. Create a production application in the Partner Portal with the production configuration, a production certificate (repeat Step 1 with a new keypair), and your production redirect URI.
3. Submit a launch request through the Login.gov Partner Support Help Desk, and wait for deployment confirmation. Login.gov deploys new integrations on a roughly two-week cycle.
4. On the Authentication Provider record, set Provider URL to https://secure.login.gov.
5. In Api Options, replace private_key_base64 with the production key.

Customers now sign in on your store with their production Login.gov accounts.

Request a higher assurance level (optional)

By default, StoreConnect requests authentication only, with the customer’s email address. This suits most stores. If your agency requires identity-verified users or stricter second factors, add acr_values to Api Options:

```yaml

private_key_base64: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUV2UUlCQURBTkJna3Fo… acr_values: urn:acr.login.gov:verified scope: openid email profile ```

acr_values	What Login.gov requires of the user
urn:acr.login.gov:auth-only	Sign-in only. This is the default
urn:acr.login.gov:verified	Identity-verified account (the user completes Login.gov’s identity proofing)
http://idmanagement.gov/ns/assurance/aal/2	A stricter second factor at sign-in

The scope value sets which customer attributes Login.gov releases to your store. The default is openid email. Login.gov releases name attributes (profile scope) only for identity-verified requests. With the default settings, new customers are asked to complete their name on the store after their first sign-in.

Rotate the certificate before it expires

The certificate you upload expires after the number of days set when you created it (365 days in the Step 1 example). Login.gov stops accepting an expired certificate, which blocks all sign-ins for the provider, so track the expiry date.

The Partner Portal accepts more than one certificate at a time, so you can rotate the certificate without downtime:

1. Generate a new keypair and certificate, as in Step 1.
2. In the Partner Portal, upload the new certificate alongside the old one.
3. On the Authentication Provider record, replace private_key_base64 in Api Options with the new base64-encoded key.
4. In the Partner Portal, remove the old certificate.

Customers keep signing in without interruption, and StoreConnect now signs token requests with the new key.

Behavior notes

• Login.gov always asks the customer to confirm which account or email to use during sign-in. This screen belongs to Login.gov and cannot be skipped.
• Login.gov manages the customer’s password and second factor. As with every SSO provider, after a customer signs in through Login.gov, the customer’s password cannot be reset or changed inside StoreConnect. See the password reset section in authentication providers and single sign-on (SSO).
• On logout, StoreConnect clears its own session, but the customer’s Login.gov session stays active in their browser. On shared devices, customers should also sign out at Login.gov or close the browser.
• Login.gov identifies each customer by a unique ID tied to your client ID. If you register a new application and change Client Id, returning customers are matched by email address instead on their next sign-in.
• If private_key_base64 is missing or malformed, the Sign in or up via Login.gov button still shows, but every sign-in fails with a “Could not authenticate you from Login.gov” notice. Check that Api Options holds the complete base64 output from Step 1.