About the Login.gov sandbox

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

The Login.gov sandbox environment is supported M-F, 8a-5p ET. The sandbox is typically available during these hours, though outages may occur.

In the sandbox environment, our partner portal is where you can manage your test applications. It is important to note that your Login.gov production account and your Login.gov sandbox account are two separate accounts.

Getting access to the Login.gov sandbox

Login.gov does not manage user accounts in the sandbox.

If you are an agency partner with a .gov or .mil account:
You can create an account in the sandbox environment on your own.

If you are a government contractor:
Ask your agency partner to help you gain access. Login.gov will not create an account or add you to a team; your partner must do this for you.

If you are with a government entity that is not a federal agency (a state or municipality) and do not have an email ending in .gov or .mil
Please submit a support ticket through the Partner Support Help Desk to get access to the Portal.

Using the sandbox

1. Visit the Partner Portal at https://portal.int.identitysandbox.gov/.
2. Create a new Login.gov test account with the test Login.gov IdP in the sandbox environment hosted at https://portal.int.identitysandbox.gov/. Your Login.gov test account is separate from your Login.gov production account.
3. If you already have a Login.gov test account, select the “Sign in” button in the upper-right corner to sign in.
4. You must create a team before you can create a new app. Create a new team by selecting the “Continue” button under “Create your first team.” If you have previously created a team you can move on to the next step.
5. If necessary, add users to that team by clicking the “Add users” button. This is the opportunity to add contractors or anyone without a .gov or a .mil email address.
6. After creating your team, select the Apps tab. This page is where you will find all of the applications you and your team create.
7. Select the “Create a new app” button and follow the steps to register a new application with the Login.gov IdP in the test sandbox environment. You can only have one app creation in progress at a time. There are links to additional information throughout the form. We recommend reading through the descriptions carefully.
8. To troubleshoot specific errors, please visit our error dictionary in the troubleshooting section of our developer documentation. If the guidance there does not resolve the error, please submit a support ticket through the Partner Support Help Desk.
9. Start testing!
10. When you’re ready to go to production, please follow our production deployment instructions. We’ll manage your application’s promotion to production. The move to production may take up to two weeks.

If you lost access to a sandbox team

Login.gov does not manage user accounts. If you have lost access to a team:

• Request someone on your team who still has access to re-add you.
• If there is no one left with access, contact the partner agency’s Login.gov Point of Contact and request that they re-add you to the team.
• If they are unable to re-add you, request that they open up a ticket through the Partner Support Help Desk explaining the situation and confirming that you need access. They must include either the issuer or the link to the application configuration.

Creating a public certificate

You can use the following OpenSSL command to generate a 2048-bit PEM-encoded public certificate for your application (with a 1-year validity period):

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

Make sure you’re using the corresponding private key in your application to sign and/or validate requests and responses to/from Login.gov.

Load Testing

Our sandbox environment is smaller than our production environment and it is shared by many of our partners. It has not been configured for load testing. For these reasons, our recommendation is to mock out the Login.gov portion of your load tests. We thoroughly load test our infrastructure and can provide data on our capabilities upon request.

Automated Testing

Login.gov cannot provide specific recommendations for automated testing. This is especially true for applications using identity verification, because we are frequently making updates to the code and the flow is likely to change and could unexpectedly break your tests.

If you are looking for recommendations for automated testing, we do not have any specific advice. There are many different frameworks and automated testing suites available to choose from, and our partners usually pick based on their own unique needs. Regardless of which suite you choose, it should be noted that you cannot bypass the MFA portion of the flow. It is intentionally designed this way for security purposes and another reason why we recommend stubbing out our flow.

While Login.gov partner support channels have provided some support for automated testing in the past, as of 09/20/2023, will no longer be able to provide assistance in this area.

Testing identity proofing

The Login.gov sandbox test environment is configured to pass most information that is entered during the proofing flow. This allows the proofing flow to be tested without the need to enter personally identifiable information (PII). There are special values that can be entered to simulate error states while testing in the Login.gov sandbox environment. Never enter PII in the sandbox environment.

Testing the IAL2-compliant process (online facial matching or in-person proofing)

If you are testing the IAL2-compliant flow and want to specifically test the online facial matching process, when you are prompted to take a photo of your ID with your phone, you can take a photo of anything that has the same shape as a US driver’s license (metro card, loyalty card, arcade card, etc). You can use the front of the card for both the front and back photos. For the selfie, it’s specifically looking for a face, so you need to use your real face. The photos are not sent to any external vendors.

If your main goal is to end up with an IAL2-compliant account to test with, and you’re not specifically testing the online facial matching process, then you can choose the in-person proofing option, and enter fake information. After the phone verification step, you will be presented with your USPS barcode, but you will not need to go to any post office. In the sandbox, you will automatically be verified at this point, and you should receive an email letting you know you were verified.

Testing document upload for the Basic IdV Service (without facial matching)

Login.gov prompts users to upload the front and back of their documents during proofing through a few different methods. In the sandbox environment, any image file that is uploaded will pass.

Data testing

⚠️ Only the YAML file in the back upload box is used on submission. For that reason, it’s good practice to upload the same yaml file in all three upload boxes to avoid confusion when testing.

A YAML file can be uploaded instead of a State ID image to trigger different behaviors. You will upload the same YAML file for the front and back of the State ID, and also the selfie (if that field appears). Different YAML files can be used to simulate the reading of certain attributes from the State ID or selfie. Here is an example YAML file that does that:

document:
  first_name: Susan
  last_name: Smith
  middle_name: Q
  address1: 1 Microsoft Way
  address2: Apt 3
  city: Bayside
  state: NY
  zipcode: '11364'
  dob: '1938-10-06'
  phone: +1 314-555-1212
  state_id_number: '123456789'
  state_id_type: drivers_license
  state_id_jurisdiction: 'NY'
  state_id_expiration: '2030-01-01'
  state_id_issued: '2020-01-01'
  issuing_country_code: 'US'

Download .yml

A YAML file can also be used to simulate an error reading or validating the document. Here are a couple of simple example YAML files:

image_metrics:
  back:
    HorizontalResolution: 100

Download .yml

failed_alerts:
  - name: Document Classification
    result: Attention

Download .yml

Here is an example YAML file that contains the full structure with annotations for expected values:

doc_auth_result: Passed # values: Passed, Failed, Attention, Unknown
image_metrics:
  back:
    HorizontalResolution: 300 # values: 0-600
    VerticalResolution: 450 # values: 0-600
    GlareMetric: 77 # values: 0-100
    SharpnessMetric: 88 # values: 0-100
  front:
    HorizontalResolution: 450
    VerticalResolution: 450
    GlareMetric: 100
    SharpnessMetric: 99
failed_alerts:
  - name: 1D Control Number Valid # See list of valid names below
    result: Failed # values: Passed, Failed, Attention, Caution
  - name: 2D Barcode Content
    result: Attention
passed_alerts:
  - name: Visible Pattern
    result: Passed
portrait_match_results:
  FaceMatchResult: Pass # returns the portrait match result - values: Pass, Fail
  FaceErrorMessage: 'Successful. Liveness: Live' # returns the liveness result - values: 'Successful. Liveness: Live', 'Liveness: NotLive', 'Liveness: PoorQuality'

Download .yml

There are not any required values from the above example file, you only need to include the values you are changing. The only exception is that alerts must be passed with both a name and a result as seen above. Anything not included will be given reasonable defaults for testing purposes.

Alert names with attention or failed values show under failed_alerts. Only passed values show under passed_alerts. The list of currently handled alert names for failed_alerts and passed_alerts are:

      - name: 1D Control Number Valid
      - name: 2D Barcode Content
      - name: 2D Barcode Read
      - name: Birth Date Crosscheck
      - name: Birth Date Valid
      - name: Control Number Crosscheck
      - name: Document Classification
      - name: Document Crosscheck Aggregation
      - name: Document Expired
      - name: Document Number Crosscheck
      - name: Expiration Date Crosscheck
      - name: Expiration Date Valid
      - name: Full Name Crosscheck
      - name: Issue Date Crosscheck
      - name: Issue Date Valid
      - name: Layout Valid
      - name: Near-Infrared Response
      - name: Physical Document Presence
      - name: Sex Crosscheck
      - name: Visible Color Response
      - name: Visible Pattern
      - name: Visible Photo Characteristics

NOTES:

• There are configurations of the above yaml file that cannot happen in real vendor responses. It is possible there will be unexpected outcomes in those cases.

Personal information verification

Login.gov collects and verifies personal information during the proofing process. The Login.gov sandbox environment only accepts social security numbers starting with “900” and “666” as valid to prevent users from accidentally entering real personal information. These prefixes are used because they are not valid according to the Social Security Administration.

To simulate a failure, enter a social security number that does not start with “900” or “666”, such as “123-45-6789”.

You can simulate failure to contact a proofing vendor by entering a social security number of “000-00-0000”. See “proofing vendor errors” for more ways to simulate vendor errors.

Proofing vendor errors

To simulate issues with proofing vendor responses, create a YAML file that includes a specific first_name field, as specified below. Save the example YAML file below and edit the first_name field to give the result you want.

To simulate failure to verify a zipcode, enter 00000 for the user’s zipcode.

See also: Individual state MVA errors

Sample YAML file:

document:
  first_name: Parse
  last_name: Smith
  middle_name: Q
  address1: 1 Microsoft Way
  address2: Apt 3
  city: Bayside
  state: WA
  zipcode: '99237'
  dob: '1938-10-06'
  phone: +1 206-555-1212
  state_id_number: '123456789'
  state_id_type: drivers_license
  state_id_jurisdiction: 'WA'
  state_id_expiration: '2030-01-01'
  state_id_issued: '2020-01-01'
  issuing_country_code: 'US'

Download .yml

Issuing source verification for ID documents

Login.gov collects the document number of a drivers license or state ID card automatically during the proofing process. This document is checked against issuing source data, along with user information, such as address.

To simulate a verification failure, submit 00000000 as the state_id_number and any jurisdiction where issuing source verification is enabled for state_id_jurisdiction.

Individual state MVA errors

To simulate an individual state yielding an error when asked to verify a drivers license, use mvatimeout for state_id_number and WA for state_id_jurisdiction. You can use any jurisdiction where issuing source verification is enabled for state_id_jurisdiction, for example WA.

Sample YAML file:

document:
  first_name: Susan
  last_name: Smith
  middle_name: Q
  address1: 1 Microsoft Way
  address2: Apt 3
  city: Bayside
  state: NY
  zipcode: '11364'
  dob: '1938-10-06'
  phone: +1 314-555-1212
  state_id_number: "mvatimeout"
  state_id_type: "drivers_license"
  state_id_jurisdiction: "WA"
  state_id_expiration: '2030-01-01'
  state_id_issued: '2020-01-01'
  issuing_country_code: 'US'

Download .yml

Phone number verification

Login.gov collects a phone number during the proofing process. In the production environment, Login.gov checks that this phone number is associated with the applicant. The following phone numbers simulate specific events:

• 703-555-5555 - simulates a phone number that couldn’t be verified as belonging to the user
• 703-555-5888 - simulates a timeout during verification
• 703-555-5999 - simulates a phone number that couldn’t be contacted

Use any other phone number for typical testing purposes.