Login.gov Handbook

Welcome to the Login.gov handbook! This is our open source team documentation. Please help us keep things up to date, and make sure to avoid contributing sensitive information.

Categories

• AppDev

  Application development

• Architecture

  High-level architecture explanations

• Development

  Development topics common to AppDev and DevOps

• Handbook

  About this handbook

• Partnerships

  Business development, account management, outreach, and communications

• Platform

  Platform infrastructure and DevOps practices

• Product

  Product delivery and process

• Reporting

  Data analytics and key metrics reporting

• Security

  Security, anti-fraud, and incident response

• Team

  Articles for the whole team

All Articles

AppDev

Application development

Architecture

• Identity Verification FlowPolicy
  FlowPolicy is a lightweight structure used to manage dependencies between Identity Verification steps

• Identity Verification Rate Limiting
  Rate limits in identity verification

Deploying

• Acuant SDK Test Plan
  Pre-deploy manual test plan for the Acuant SDK

• Deploy Schedule for Automated Deploys
  The daily deploy schedule for IdP, PKI and Dashboard in lower environments

• Deploying new IdP and PKI code
  Release Manager’s Guide for Production

• Deploying the Sample Apps
  How to deploy oidc-sinatra and saml-sinatra to cloud.gov

Development

• A/B Testing Process
  Basic documentation on how Login.gov does A/B testing

• Feature flags
  Purpose and lifecycle of a feature flag, used when developing large new features.

• How to Manage the 50/50 State
  During deploys, both new and old instances are serving requests. This is called the 50/50 state and requires careful management when changing code that is used across instances.

• Identity Proofing Testing
  Tips and tricks for testing identity verification (“proofing”)

• SAML: Development
  High-level overview of the flow of SAML in the IdP code

• Secrets and Configuration
  How to update IdP and Rails app configuration (feature flags) and secrets application.yml, and how to use the app-s3-secret script

• Testing vendor APIs with live credentials
  Best practices for testing with sensitive keys

Oncall

• AppDev Oncall
  Responsibilities and runbook for AppDev oncall

• Bug Bounty Triage
  How to handle bug bounty reports

• Deployer Rotation
  Spreadsheet to track the AppDev Deployer

• Team Daytime Oncall
  Responsibilities for individual team daytime oncall

Setup

• Windows Virtual Machine Setup
  Setting up a Windows VM on your Mac so you can test Internet Explorer

Tasks

• Contact Form Updating Instructions
  Procedure for updating fields in the Help Center’s Contact Form

• Key rotation guide
  Guide for rotating secrets for the IdP and PKI codebases

• SAML: Annual Certificate Rotation
  How to perform annual certificate rotation

• Translation process
  Process and guidelines for localization and string translation (i18n)

• Updating MaxMind GeoIP database
  Instructions for updating our IP address geolocation database

• Updating Pwned Passwords Dataset
  Instructions for updating Pwned Passwords dataset in s3

X509 and PIV/CAC Certificates

• OpenSSL Command Line Recipes
  Commands for common certificate tasks, useful for PIV/CAC or AAMVA credentials

• Troubleshooting PIV/CAC logins and Managing Certificates
  If somebody has trouble using their PIV/CAC with Login.gov, and also how to download new certificates from Certificate Authorities

• Troubleshooting expiring PIV/CAC certs
  Guide on finding new certs if a cert is expiring

Other Articles

• Device profiling and fraud detection
  Information about configuring and testing device profiling and fraud detection

• Environment Descriptions
  Listing of environments and the differences between them, like prod, pt, dm, int or dev

• IAL2 Common Errors List
  List of the most common IAL2 errors

• Triage User Issues
  Rails console scripts and Cloudwatch queries, for debugging the IdP

• Troubleshooting the Sandbox
  Troubleshooting issues with the Login.gov sandbox/int environment

Architecture

High-level architecture explanations

Other Articles

• Background Jobs: Proofing Ruby Workers
  Overview and architecture of our proofing background jobs

• Background Jobs: RISC Ruby Workers
  Overview and architecture of our RISC notification jobs

• IDP Artifacts
  Overview of IdP artifact-building architecture

• IdP CDN
  Overview of use of CloudFront CDN to serve Login.gov

• Reporting Dashboard
  Overview of reporting dashboard architecture for data.login.gov

Development

Development topics common to AppDev and DevOps

Code

• Cloud.gov Pages
  Overview of static site hosting and authentication

• GitHub & GitLab
  Team code repos, permissions, notification strategies

• Pull Request Process
  How we do code reviews in pull requests

Documentation

• Incident Review Template
  A template document for incident reviews, outlining causes, a timeline of events, and action items

• Rollplans
  When to create a rollplan, where to find existing ones

References

• Scripts
  Overview of scripts used for interacting with deployed boxes

• Troubleshooting Quick Reference
  List of things to check to triage active issues in production

Other Articles

Handbook

About this handbook

Other Articles

• Contributing to the Handbook
  Guidelines for contributing to the handbook

• Template Page
  An example article that you can copy

Partnerships

Business development, account management, outreach, and communications

Other Articles

• Adding Test SSNs to the Sandbox for Partners
  The steps necessary to add a set of test SSNs for use in the sandbox that don’t meet the default format requirements.

• Deploying a Partner Service Provider Config to Production
  Process and procedures when deploying a partner service provider config to production

• Partner Reporting Document
  How to create monthly reports

• Partner Success Engineer Workflows
  Data map for identity-idp-config YAML files to data sources (IAA GTCs and Orders, Dashboard, etc)

• Partner Support Ticket Handling
  How to handle and track support requests from partners

• Partnerships Feedback Form
  This form is used to collect feedback from partners and the data is then put into an internal collection document

• Partnerships Internal Pilot Playbook
  Coordinate Pilots of new features with our Partners

• Partnerships Kudos and Feedback
  A history of kudos received from partners

• Provisioning Test IDV Users for Partners
  The steps necessary to set up a collection of test users with IDV profiles for a partner in the sandbox.

Platform

Platform infrastructure and DevOps practices

How To

• Baking New AWS AMI Images
  Runbook for creating new Base and Rails AMI images

• Building a Personal Sandbox Environment
  This is a guide to follow when you are standing up your own personal development environment, aka “sandbox”

• Deploying Infrastructure Code
  Runbook for the process of deploying code from 18f/identity-devops into our infrastructure.

• Infrastructure auto-terraform Runbook
  How to use/manage/understand auto-terraform

• Load Testing Process
  Process overview and instruction for performing load tests in AWS

• Platform Disaster Runbooks
  Recovering from really really bad stuff

• Platform On-Call Guide
  Runbook/guide for rotations/responsibilities for the Login.gov Platform engineering teams.

• Platform Scaling
  Runbooks for scaling out or up various resources in anticipation of or response to added load

• Setting Up aws-vault
  This runbook is for getting set up with, and using, aws-vault, a tool for providing easier access for cross-account role assumption.

References

• Custom Aliases/Functions for identity-devops Commands
  Reference/runbook for the custom commands created via the login-alias script.

• External Services and Limits
  Notes on rate and cost limited external services used by IdP and out platform

Team

• Acceptance Criteria for Platform PRs and Issues
  How to create and manage pull requests and issues for the Login.gov Platform Teams.

• Team Radia Sprint Ceremonies
  How Sprints and Standups operate

Other Articles

• AWS Accounts and IAM Groups/Roles
  Private list of AWS accounts, roles, and groups for human users

• AWS IAM User/Group/Role/Account Configurations
  Detailed information about our IAM configurations, and how to add/alter IAM components within our infrastructure.

• Email Routing
  Inbound and outbound SMTP information

• GitLab
  GitLab Setup

• GitLab Environment Deploys
  How to use GitLab to deploy your sandbox IdP environments

• GitLab Image Signing
  GitLab Image Signing

• GitLab Production Deploys
  How to deploy changes to the production GitLab system

• Infrastructure Metrics and Alerting
  Troubleshooting quick reference for infrastructure metrics and alerting, to analyze trends and track outages

• Making Changes via Terraform
  This is a guide to the various terraform directories in identity-devops and how to use them

• Platform Tips and Tricks
  Helpful tips for AWS, Terraform, and other platform related tech

• Platform: Secrets!
  List of configuration secrets and how to manage them

Product

Product delivery and process

GitLab

• GitLab Roadmapping
  Guide to roadmapping in GitLab

Other Articles

• Definition of Done
  Checklist for work to be done, and accepted via an Acceptance Thread

• Definition of Ready
  Best practices for tracking issues in JIRA

• Product Artifacts
  Documentation Templates including SBARs, 1-Pagers, RFCs

• Product Demo Recordings
  Creating a simple product demo with a mobile device

• Sprint ceremonies
  Overview of a scrum team’s regularly scheduled meetings

Reporting

Data analytics and key metrics reporting

CloudWatch

• CloudWatch Dashboards
  How to search for, create, and manage CloudWatch dashboards

• CloudWatch Insights 101
  Basic guide to querying against our logs with CloudWatch Insights

Data Warehouse

• Data Warehouse Log Tables Schema
  Schema definition for logs tables in the data warehouse

Queries

• Reporting Queries
  Queries to run in the Rails console for common reporting questions

• SQL Style Guide
  Conventions for formatting SQL queries

Other Articles

• Analytics Events
  Searchable list of IdP analytics events

• Google Analytics
  Brochure site analytics and the Digital Analytics Program

• Monthly Key Metrics Reporting
  Overview of report, includes metrics and methodology

• Reporting Process
  Reporting process for ad-hoc data requests, query requests and analyses

Security

Security, anti-fraud, and incident response

Other Articles

• Incident Response Guide
  Security Incident Response Guide

• New Feature Onboarding
  Checklist for new features, specifically focused on documentation needed for security review

• Vendor outage response process
  What to do in the event of a 3rd party vendor outage.

Team

Articles for the whole team

Guides

• Contingency Plan Training Wargames - Dungeon Master’s Guide
  How to create an exciting Wargames DM scenario

• Contingency Plan Training Wargames - Player’s Guide
  How to prepare for a Wargames scenario as a player

• Incident Response Checklist
  Quick reference checklist for incident response

• PII Guidance
  Guidance on safe handling of Personally Identifiable Information

• StatusPage Update Process
  Publishing outage and maintenance information to StatusPage

How To

• AWS Incident Manager
  Basic information on our on-call scheduling and alerting tool

People Ops

• Leave Guidance
  Reasons, types, and conventions around taking leave as a Login.gov Login.gov employee

• Offboarding
  List of steps which must be completed when a person leaves the Login.gov program

• Onboarding
  List of steps to be completed when a person joins the Login.gov program

• Overtime
  Guidance around working overteam as a contractor or federal employee

• Reviews
  Mid-Year and End-of-Year Self Review and Peer Feedback

• Services and Accounts
  List of external services and logins to manage

• Staffing
  Login.gov staffing processes

Program Information

• Funding and Cost Recoverability
  How Login.gov is funded and what it means

• Login.gov Principles
  Our mission and project principles

Team Organization

• Org Chart
  Login.gov’s roster of team members and teams

• Slack
  Groups and Channels

• Sprint Team Roles
  List of our sprint team roles and responsibilities

• Sprint Teams
  List of our sprint teams and the explanations behind their names

Other Articles

• GPO Designated Receiver
  How we verify that USPS/GPO address verification is working as expected

• Glossary
  Explanation of common terms, acronyms, and abbreviations