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

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:

./bin/smoke_test --local

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, run 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 zeus rspec:

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

Login.gov uses a tool called Mailcatcher to view email messages locally. When Mailcatcher is running, visit http://localhost:1080/ to see them.

We spin up a Mailcatcher process by default through make run, but if you want to run Mailcatcher as a standalone process, just run:

$ mailcatcher

If you would like to run the application on a different port:

Change the port number for mailer_domain_name and domain_name in config/application.yml
Run the app on your desired port like make run PORT=1234

Translations

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:

Viewing outbound SMS messages and phone calls

To see outbound SMS messages and phone calls, visit http://localhost:3000/test/telephony.

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 geo_data/GeoLite2-City.mmdb. 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 192.168.1.x or 10.0.0.x.
In config/application.yml, replace localhost in the domain_name setting with the IP address discovered in the previous step. Leave the trailing port :3000 unchanged.
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, http://192.168.1.131:3000).

Testing the application over HTTPS

$ make run-https

Or, to run on a different host:

$ HOST=0.0.0.0 make run-https

The 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.

konklone/identity-idp