Skip to content

Using the Login.gov sandbox

To test an enrollment flow that utilizes Login.gov as the Identity Provider (IdP), you will need an account in the Login.gov sandbox:

The Login.gov sandbox is an open environment to create and test integrations between Login.gov and your applications

This tutorial walks you through the process of setting up a Login.gov sandbox account that can be used for testing the Benefits app.

You will need

To create a full identity-proofed Login.gov sandbox account, you will need:

  • a real email address that can receive email
  • a real cell phone number that can receive an SMS
  • a specially formatted test account YAML file (see more below)

Read the Login.gov Testing identity proofing docs for complete details.

Test account YAML files

The specially formatted YAML files are used in place of a state ID document upload during the Login.gov sandbox account identity proofing flow. The Login.gov sandbox will use information from an uploaded YAML file in place of the real identity verification required for Production Login.gov.

The Benefits Test Data document links to a few pre-made YAML files that can be used for various scenarios:

  • Older Adult
  • U.S. Veteran
  • CalFresh recipient

Login.gov also provides more information and sample YAML files in their Testing document upload for Basic IdV Service docs.

Create a basic account

  1. Navigate to the Login.gov sandbox account creation page
  2. Enter a unique email address for this test case, e.g. realemail+older_adult@provider.com. Gmail supports adding suffixes to your email address.
  3. Select a language and check I read and accept the Login.gov Rules of Use and submit.
  4. Check your email for a confirmation link and click it.
  5. Create a strong, unique password for use with this test account only. Save this (ideally with a password manager).
  6. Continue to setup a multi-factor authentication method. Selecting Backup codes is perfectly fine especially if this is a temporary test account, but note that you only get 10 one-time-use codes. You will get a fresh 10 after using the first batch. Authentication application or Text or voice message may be better options if you plan to use the test account frequently, for some time.

At this point, you will be shown your Login.gov sandbox account page, and you are signed in.

You now have a (non identity proofed) Login.gov sandbox account.

Try it!

Sign out of your Login.gov sandbox account. Then sign back from the same screen.

Are you able to get back to the account page?

Upgrade basic account to identity proofed

The basic sandbox account does not have enough details to allow for eligibility checks with the Benefits app (like date of birth, address, etc.)

The easiest way to upgrade the sandbox account is to attempt to use it for a particular enrollment flow in the Benefits app.

This process will prompt you through the identity proofing flow before taking you back to the Benefits app.

  1. Download or create the YAML file for the specific user-type you are testing (Older Adult, U.S. Veteran, etc.)
    • The information in the YAML file should be sample information only.
    • The information in the YAML file does not need to match later information you will provide in the flow (e.g. phone number)
  2. Start in a non-prod environment of the Benefits app (e.g. dev or test).
  3. Select a transit agency, and select the Login.gov flow corresponding to the user-type you are testing.
  4. Sign in to Login.gov sandbox using the basic account details you set up previously.
  5. Continue through the confirmation screens that outline the identity proofing process.
  6. On the Choose how to verify your ID page, select Upload photos under Continue on this computer.
  7. On the Choose your ID type page, select U.S. driver’s license or state ID and continue.
  8. Upload the YAML file as the Front and Back image of the ID and submit.
  9. Enter a fake Social Security number following the on-screen instructions (must start with 900- or 666-). DO NOT enter real PII in this field.
  10. Verify the (sample) information was processed from the YAML file and submit.
  11. Enter your real cell phone number to receive a verification SMS. (The same phone number can be used for multiple accounts.)
  12. Check your text messages for a message from Login.gov. The message should specify idp.int.identitysandbox.gov.
  13. Enter the code into the browser.
  14. Re-enter your Login.gov sandbox account password.
  15. Save the displayed Personal Key somewhere safe (this can be used for account recovery).
  16. Confirm that you want to connect the verified information in your Login.gov sandbox account to the Benefits app.

At this point, you will be redirected back into the Benefits app.

If the Login.gov sandbox account was created with sample data sufficient to pass eligibility for the chosen enrollment flow (e.g. a date of birth making the sandbox account 65 or older for the Older Adult flow), you are shown the “eligibility verified” message and can continue with contactless card enrollment.

Success!

You now have an identity proofed Login.gov sandbox account that can be used for future testing.