18F Identity Provider (IdP)
Ruby HTML JavaScript CSS Python Shell Other
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
.circleci LG43 remove equifax from application (#2434) Aug 15, 2018
.github Change the indexes in Rails link in PR template Aug 10, 2018
app Merge pull request #2438 from 18F/mb-fix-csp-on-sign-in Aug 17, 2018
bin LG43 remove equifax from application (#2434) Aug 15, 2018
certs LG-492 Add Forest Service ePermits to the production service providers Jul 18, 2018
config Merge pull request #2418 from 18F/gregc-LG460-create-more-visible-banner Aug 17, 2018
db LG-512 Add a failure to proof url to service providers for LOA3 Jul 30, 2018
deploy LG-243 Disallow indexing of certain pages May 14, 2018
docs Replace browserify-rails with rails-webpacker Feb 13, 2018
keys Allow SAML secrets to be rotated Feb 14, 2018
lib Merge pull request #2418 from 18F/gregc-LG460-create-more-visible-banner Aug 17, 2018
public LG-243 Disallow indexing of certain pages May 14, 2018
scripts Ensure load tests follow flows correctly Dec 13, 2017
spec Merge pull request #2438 from 18F/mb-fix-csp-on-sign-in Aug 17, 2018
vendor/assets LG-161 - Improve phone input selection for 2FA (#2135) May 18, 2018
.about.yml Create .about.yml Feb 1, 2016
.babelrc Replace browserify-rails with rails-webpacker Feb 13, 2018
.bummr-build.sh Make .bummr-build.sh executable May 31, 2016
.codeclimate.yml Update rubocop from 0.54.0 to 0.58.2 Jul 24, 2018
.csslintrc add normalize.css Apr 27, 2016
.dockerignore Add docker + docker-compose support Apr 26, 2016
.erdconfig Adds architecture documentantion (#625) Oct 27, 2016
.eslintignore Update js files to comply with es lint rules (#1364) Apr 13, 2017
.eslintrc Remove finance step from idv flow Dec 8, 2017
.fasterer.yml Add fasterer gem and fix performance offenses (#979) Jan 24, 2017
.gitignore LG43 remove equifax from application (#2434) Aug 15, 2018
.overcommit.yml Update Overcommit settings (#202) Jun 23, 2016
.postcssrc.yml Replace browserify-rails with rails-webpacker Feb 13, 2018
.reek Merge pull request #2235 from 18F/stevegsa-update-cloudhsm-keygen-to-… Aug 9, 2018
.rubocop.yml Merge pull request #2235 from 18F/stevegsa-update-cloudhsm-keygen-to-… Aug 9, 2018
.ruby-version Update Ruby from 2.3.5 to 2.5.0 Jun 15, 2018
.scss-lint.yml Archive old JS; start shiny, new JS Apr 27, 2016
.slim-lint.yml Capitalize TwiML tags; ignore slim-lint offense Dec 4, 2017
.snyk Update Rails from 4.2.9. to 5.0.5 Aug 10, 2017
CONTRIBUTING.md Update PR template and contribution guidelines Jul 26, 2018
Dockerfile Update Ruby from 2.3.5 to 2.5.0 Jun 15, 2018
Gemfile LG43 remove equifax from application (#2434) Aug 15, 2018
Gemfile.lock LG43 remove equifax from application (#2434) Aug 15, 2018
LICENSE.md Move upaya codebase to repository root (#28) Apr 19, 2016
Makefile LG-459 Clean up localizations Jul 24, 2018
Procfile Re-add mailcatcher to Procfile Aug 15, 2017
Procfile_dev Add a make task and Procfile for running IdP in development Apr 14, 2018
README.md LG43 remove equifax from application (#2434) Aug 15, 2018
Rakefile Enable parallel builds in Circle CI Mar 20, 2018
config.ru Use rackup in Procfile and explicit port 3000 Jan 26, 2017
docker-compose.yml Fix Docker setup Feb 13, 2018
knapsack_rspec_report.json Replace Poltergeist/PhantomJS with Headless Chrome Apr 19, 2018
logstash.conf.example Add logstash.conf.example and update README Jul 25, 2018
mac-test-passphrase-prompt.png Update testing instructions in `README.md` Mar 14, 2018
package.json LG-508 Add client-side Crockford Base32 encoding helper Aug 7, 2018
yarn.lock LG-508 Add client-side Crockford Base32 encoding helper Aug 7, 2018


Identity-IdP (Upaya)

Build Status Code Climate Test Coverage security

A Identity Management System powering login.gov.

Local development


Setting up and running the app

  1. Make sure you have a working development environment with all the dependencies installed. On OS X, the easiest way to set up a development environment is by running our Laptop script. The script will install all of this project's dependencies.

If using rbenv, you may need to alias your specific installed ruby version to the more generic version found in the .ruby-version file. To do this, use rbenv-aliases:

git clone git://github.com/tpope/rbenv-aliases.git "$(rbenv root)/plugins/rbenv-aliases" # install rbenv-aliases per its documentation

rbenv alias 2.3 2.3.5 # create the version alias
  1. Make sure Postgres and Redis are running.

For example, if you've installed the laptop script on OS X, you can start the services like this:

$ brew services start redis
$ brew services start postgresql
  1. Create the development and test databases:
$ psql -c "CREATE DATABASE upaya_development;"
$ psql -c "CREATE DATABASE upaya_test;"
  1. Run the following command to set up the environment:
$ make setup

This command copies sample configuration files, installs required gems and sets up the database.

  1. Run the app server with:
$ make run

Before making any commits, you'll also need to run overcommit --sign. This verifies that the commit hooks defined in our .overcommit.yml file are the ones we expect. Each change to the .overcommit.yml file, including the initial install performed in the setup script, will necessitate a new signature.

For more information, see overcommit

If you want to develop without an internet connection, you can set RAILS_OFFLINE=1 in your environment. This disables the mx record check on email addresses.

If you want to measure the app's performance in development, set the rack_mini_profiler option to 'on' in config/application.yml and restart the server. See the rack_mini_profiler gem for more details.

Testing Analytics

If you want to visualize and query the event and log data, you can install the latest versions of Elasticsearch, Logstash, and Kibana. On OS X, the easiest way is with Homebrew:

brew tap homebrew/services

brew install elasticsearch logstash kibana

brew services start elasticsearch
brew services start kibana

Start logstash by running this command from this repo's root directory:

logstash -f logstash.conf

When you trigger an event in the app (such as signing in), you should see some output in the logstash window.

To explore the data with Kibana, visit http://localhost:5601

Troubleshooting Kibana errors

Below are some common errors:

  • On the Kibana website: "Your Kibana index is out of date, reset it or use the X-Pack upgrade assistant."

  • In the logstash output:

    Failed to parse mapping [_default_]: [include_in_all] is not allowed for
    indices created on or after version 6.0.0 as [_all] is deprecated. As a
    replacement, you can use an [copy_to] on mapping fields to create your own
    catch all field.

Solution, assuming you don't use these services for other apps and are OK with deleting existing data:

  1. Stop all services:
  • Press ctrl-c to stop logstash if it's running
brew services stop elasticsearch
brew services stop kibana
  1. Uninstall everything:
brew uninstall --force elasticsearch
brew uninstall --force logstash
brew uninstall --force kibana
  1. Reinstall everything:
brew install elasticsearch logstash kibana
  1. Start the services:
brew services start elasticsearch
brew services start kibana
  1. Delete the old Kibana index:
curl -XDELETE http://localhost:9200/.kibana
  1. Delete the old logstash template:
  1. Start logstash in a new Terminal tab:
logstash -f logstash.conf
  1. Launch the IdP app and sign in to generate some events. You should see output in the logstash tab without any errors.

  2. Visit http://localhost:5601/ and click "Discover" on the left sidebar. If you get a warning that no default index pattern exists, copy the last pattern that appears in the list, which will have the format logstash-year.month.day. Paste it into the "Index pattern" field, then click the "Next step" button.

  3. On Step 2 of 2: Configure settings, select @timestamp from the Time Filter field name dropdown, then click "Create index pattern".

  4. Create some more events on the IdP app.

  5. Refresh the Kibana website. You should now see new events show up in the Discover section.

Using Docker

  1. Download, install, and launch Docker

  2. Set up the Docker image

$ bin/setup --docker

More useful Docker commands:

  • Start the container: docker-compose up
  • Stop this running container: docker-compose stop
  • Stop and delete the containers: docker-compose down
  • Open a shell in the web container: docker-compose run --rm web bash

See the Docker Compose docs for more information.

Viewing the app locally

Once it is up and running, the app will be accessible at http://localhost:3000/ by default.

To view email messages, Mailcatcher must be running. You can check if it's running by visiting http://localhost:1080/. To run Mailcatcher:

$ 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

If you would like to see the Spanish translations on a particular page, add ?locale=es to the end of the URL, such as http://localhost:3000/?locale=es. Currently, you'll need to add ?locale=es to each URL manually. We are working on a more robust and user-friendly way to switch between locales.

Running Tests

To run all the tests:

$ make test

To run a subset of tests excluding slow tests (such as accessibility specs):

$ make fast_test

If you are on a mac, if you receive the following prompt the first time you run the test suite, enter sekret as the passphrase:

alt text

See RSpec docs for more information.

JavaScript unit tests run using the mocha test runner. Check out the mocha documentation for more details.

Run security scanner

$ make brakeman

User flows

We have an automated tool for generating user flows using real views generated from the application. These specs are excluded from our typical spec run because of the overhead of generating screenshots for each view.

The local instance of the application must be running in order to serve up the assets (eg. make run). Then, you can specify where the assets are hosted from and generate the views with:

$ RAILS_ASSET_HOST=localhost:3000 rake spec:user_flows

Then, visit http://localhost:3000/user_flows in your browser!


The user flows tool also has an export feature which allows you to export everything for the web. You may host these assets with someting like simplehttpserver or publish to Federalist. To publish user flows for Federalist, first make sure the application is running locally (eg. localhost:3000) and run:

$ RAILS_ASSET_HOST=localhost:3000 FEDERALIST_PATH=/site/user/repository rake spec:user_flows:web

This will output your site to public/site/user/repository for quick publishing to Federalist. To test compatibility, run simplehttpserver from the app's public folder and visit http://localhost:8000/<FEDERALIST PATH>/user_flows in your browser.

Load testing

We provide some Locust.io Python scripts you can run to test how the app responds to load. You'll need to have Python and pyenv-virtualenvwrapper installed on your machine. If you're on a Mac, the easiest way to set up Python and pyenv-virtualenvwrapper is to run the laptop script.

Next, you'll need to set the following values in your local application.yml:

disable_email_sending: 'true'
enable_load_testing_mode: 'true'
telephony_disabled: 'true'

Then, run the app with make run, and in a new Terminal tab or window, run:

make load_test type=create_account

This will simulate 3 concurrent users going through the entire account creation flow and then signing out. To change the number of concurrent users, number of requests, and the rate at which users are created, modify the -c, -n, and -r Locust parameters in bin/load_test. Run locust --help for more details.

By default, the test will target the host running at http://localhost:3000. To change the target host, set the TARGET_HOST environment variable. For example:

TARGET_HOST=https://awesome.loadtesting.com make load_test type=create_account

Proofing vendors

Some proofing vendor code is located in private Github repositories because of NDAs. You can still use it in your local development environment if you have access to the private repository.


Check out the private repository for somevendorname

$ cd vendor
$ git clone git@github.com:18F/identity-somevendorname-api-client-gem.git somevendorname

Add the vendor configuration

Add appropriate vendor environment variables to config/application.yml -- see a member of the login.gov team for credentials and other values.

Why 'Upaya'?

"skill in means" https://en.wikipedia.org/wiki/Upaya

Managing translation files

To help us handle extra newlines and make sure we wrap lines consistently, we have a script called ./scripts/normalize-yaml 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