login-dot-gov-sandbox.md

Login.gov Sandbox

Per the 0005 ADR we are using the login.gov sandbox (non-production) environment for our initial Identity Provider (IdP) implementation. This document describes what developers of the application need to know about the login.gov sandbox.

Initial Setup

For development and testing:

• Go to the login.gov sandbox.
• Create an account with a valid email address that you control
• Respond to the verification email and set up valid two-factor authentication
• Get the logindotgov-private.pem file from an existing team member.
• Copy the file to the /certs directory of the repo. It should not be checked into Git.

Managing our application registration requires a .gov email address. Once you have created your account, contact an existing team member to get yourself added to the dol-ui-claimant-sandbox team. This is an optional step.

One tip: you may eventually want multiple accounts in order to facilitate testing of various IAL2 error scenarios. If your email host supports the subaddressing feature then you can use that to indicate the identity conditions with which you set up your account.

Testing the login.gov sandbox integration

If you are running the application locally, you can test out the complete IdP integration.

• Your local server should be listening at https://sandbox.ui.dol.gov:4430/. If not, check out the sections above on HTTPS and running the Django app via make login.
• Visit https://sandbox.ui.dol.gov:4430/logindotgov/
• Sign in or Create an account, depending on whether you already have a sandbox account
• Walk through the IAL2 proofing flow (should only need to do this if you are creating an account for the first time). See https://developers.login.gov/testing/#testing-ial2 for details.
• On successful IAL2 validation, you should be redirected to https://sandbox.ui.dol.gov:4430/logindotgov/explain where you can see all the attributes that login.gov asserts to our application.

Identity Proofing

To fully login to our application, you will need to identity proof to reach IAL2. The IAL2 login.gov support allows for testing various scenarios based on special reserved values for name, phone number, etc. You can also create a YAML file locally to upload and speed up your proofing experience.

Local development

The core/.env-example has all the relevant environment variables, prefixed with LOGIN_DOT_GOV_.

You will need a certs/logindotgov-private.pem file, which you can obtain from an existing team member.

Administration

Being a part of the administration team is not required to use the login.gov sandbox when acting as a claimant with the application. You only need to pay attention to this section if you are tasked with rotating a certificate set or creating/modifying the application configuration.

Managing a login.gov application

Each installation requires a separate login.gov registration. So local development, and each WCMS environment, have separate registrations, certificates, and configuration values.

We use the naming convention: urn:gov:gsa:openidconnect.profiles:sp:sso:dol:ui-arpa-claimant-envname for the Issuer value in each application.

The "redirect_uri" address should be the HTTPS hostname of the environment, ending with /logindotgov/result.

Example from our local development configuration:

Field	Value
Friendly Name	dol-ui-claimant-sandbox
Issuer	urn:gov:gsa:openidconnect.profiles:sp:sso:dol:ui-arpa-claimant-sandbox
Redirect URI	https://sandbox.ui.dol.gov:4430/logindotgov/result
Identity Protocol	openid_connect_private_key_jwt
Attribute Bundle	check all the boxes

Every application has a x509 public/private certificate set. You can generate certificates with:

(.venv) % make x509-certs

By default the certificates expire in one year. To rotate a certificate or register one for the first time, upload the public certificate to the login.gov dashboard, and the share the private key (.pem file) via 1Password and/or a secure out-of-band channel like https://securetransfer.dol.gov/ encrypted email. The private .pem file must be configured with WCMS secrets as LOGIN_DOT_GOV_PRIVATE_KEY_FILE.

To update an application certificate:

1. In your local terminal, in the application directory, type make x509-certs and enter the environment-specific URL of the UI application and the IdP name identitysandbox.gov
2. Login to the dashboard: https://dashboard.int.identitysandbox.gov/
3. Click on the Apps menu
4. Click on the application Friendly Name
5. Scroll to the bottom and click Edit
6. Select and upload the certs/identitysandbox.gov-public.crt file you just created in step 1
7. Copy the contents of certs/identitysandbox.gov-private.pem to wherever you store secrets for the team. Be sure to give it a name to correlate with the Friendly Name of this particular application, since there are multiple private certificates to manage.
8. Click the Update button at the bottom of the page

If you need to verify the contents of a public certificate, the relevant command is:

openssl x509 -in certs/identitysandbox.gov-public.crt -noout -text

If you need the fingerprint of a public certificate:

openssl x509 -sha256 -in certs/identitysandbox.gov-public.crt -noout -fingerprint

OIDC

The OpenID Connect protocol is the exchange standard we use for IdP handshaking. The Python library uses the LOGIN_DOT_GOV_ENV environment variable to trigger which service to interrogate for its well known configuration. All our WCMS environments and local environment should use the sandbox value. The CI environment uses test in order to trigger the mock server.