Login.gov Identity Provider (IdP)
Login.gov is the public's one account for government. Use one account and password for secure, private access to participating government agencies.
This repository contains the core code base and documentation for the identity management system powering secure.login.gov.
Contributing to this code base
Thank you for your interest in contributing to the login.gov IdP! For complete instructions on how to contribute code, please read through our CONTRIBUTING.md documentation.
Creating your local development environment
Installing on your local machine
This installation method is meant for those who are familiar with setting up local development environments on their machines.
- To start, make sure you have the following dependencies installed and a working development environment:
We recommend using Homebrew, rbenv, nvm or other version management tooling when installing your dependencies. While we don't anticipate changing these frequently, this will ensure that you will be able to easily switch to different versions as needed.
- Test that you have Postgres and Redis running.
For example, if you've installed with Homebrew, you can start the services like this:
$ brew services start redis $ brew services start postgresql
- Create the development and test databases:
$ psql -c "CREATE DATABASE upaya_development;" $ psql -c "CREATE DATABASE upaya_test;"
Q: Why "Upaya"?
A: "skill in means" https://en.wikipedia.org/wiki/Upaya
- Run the following command to set up your local environment:
$ make setup
This command copies sample configuration files, installs required gems and sets up the database. Check out our Makefile commands to learn more about what this command does: https://github.com/18F/identity-idp/blob/main/Makefile
- Now that you have you have everything installed, you can run the following command to start your local server:
$ make run
You should now be able to go to open up your favorite browser, go to
localhost:3000 and see your local development environment running.
Running tests locally
Login.gov uses the following tools for our testing:
To run our full test suite locally, use the following command:
$ make test
Use the following command to run a subset of our test suite, excluding slower tests:
$ make fast_test
Check out our Makefile commands learn more about how you can customize this command to run specific tests using rspec: https://github.com/18F/identity-idp/blob/main/Makefile#L41
Showing the Browser
By default, the acceptance specs use a headless browser for speed. If you want to see the browser, run the specs with
SHOW_BROWSER=true environment variable:
$ SHOW_BROWSER=true bundle exec rspec spec/features/
Running smoke tests
The smoke tests are a series of RSpec tests designed to run against deployed environments. To run them against the local Rails server:
To run the smoke tests against a deployed server, make sure you set up a
.env file with the right configuration values, see monitor_config.rb for the full list of environment variables used. The script below will
source that file and add the variables to the environment.
MONITOR_ENV=INT ./bin/smoke_test --remote
For remote smoke tests, we save a screenshot of failed test scenarios to help debugging in
tmp/capybara, and they are exported to CircleCI as build artifacts as well.
Speeding up local development and testing
To automatically run the test that corresponds to the file you are editing,
bundle exec guard with the env var
GUARD_RSPEC_CMD set to your preferred
command for running
rspec. For example, if you use Zeus,
you would set the env var to
GUARD_RSPEC_CMD="zeus rspec" bundle exec guard
If you don't specify the
GUARD_RSPEC_CMD env var, it will default to
bundle exec rspec.
We also recommend setting up a shell alias for running this command, such as:
alias idpguard='GUARD_RSPEC_CMD="zeus rspec" bundle exec guard'
Viewing email messages
We spin up a Mailcatcher process by default through
make run, but if you want to run Mailcatcher as a standalone process, just run:
If you would like to run the application on a different port:
- Change the port number for
- Run the app on your desired port like
make run PORT=1234
Login.gov translates the IdP into English, French and Spanish. To help us handle extra newlines and make sure we wrap lines consistently, we have a script that helps format YAML consistently. After importing translations (or making changes to the
*.yml files with strings, run this for the IdP app:
$ make normalize_yaml
If you would like to preview the translations on a particular page, use the Language dropdown in the footer of the website. To manually override a locale, add the locale as the first segment of the URL:
- http://localhost:3000 becomes http://localhost:3000/es
- http://localhost:3000/sign_up/enter_email becomes http://localhost:3000/es/sign_up/enter_email
Viewing outbound SMS messages and phone calls
To see outbound SMS messages and phone calls, visit
Setting up Geolocation
Login.gov uses MaxMind Geolite2 for geolocation. To test geolocation locally, you will need to add a copy of the Geolite2-City database to the IdP.
The Geolite2-City database can be downloaded from MaxMind's site at https://dev.maxmind.com/geoip/geoip2/geolite2/.
Download the GeoIP2 Binary and save it at
The app will start using that Geolite2 file for geolocation after restart.
Testing on a mobile device or in a virtual machine
By default, the application binds to
localhost. To test on a network device or within a virtual machine, you can bind to
0.0.0.0 instead, using the following instructions:
- Determine your computer's network IP address. On macOS, you can find this in the "Network" system settings, shown under the "Status: Connected" label. This often takes the format of
domain_namesetting with the IP address discovered in the previous step. Leave the trailing port
- Start the server using the command
HOST=0.0.0.0 make run
- Assuming that your phone or virtual machine computer is connected on the same network, visit the application using the domain name configured in the second step (for example,
Testing the application over HTTPS
$ make run-https
Or, to run on a different host:
$ HOST=0.0.0.0 make run-https
run-https Makefile target will automatically provision a self-signed certificate and start the built-in Rails server.
You can now navigate to https://localhost:3000/ .
It's likely that you'll be prompted with a screen with warnings about an unsafe connection. This is normal. Find the option on the screen to bypass the warning. It may be hidden under an "Advanced" toggle button. In Chrome, you may not see an option to bypass this screen. In these situations, type the letters
thisisunsafe while the screen is active, and you will be redirected automatically.
Installing with Docker
There was an initial attempt to dockerize the IDP but it is currently deprecated, mostly non-functional, and not maintained. There is ongoing work to make the IDP more 12 Factor compliant which will eventually lead to better support for containerization.
If you'd like to work with the previous implementation see the Docker documentation to install the IdP as a container.