Login Handbook
Welcome to the Login.gov handbook! This is our open source team documentation!
Please help us contribute and keep things up to date, and make sure to avoid contributing sensitive information.
Categories
-
Application development
-
High-level architecture explanations
-
Common Dev things across AppDev and DevOps
-
About this handbook
-
Product and process
-
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
-
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 theapp-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 -
Engineering Design Doc Template (deprecated)
Template that can be copied for engineering proposals -
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: Lambda (deprecated)
Overview of and launch checklist for our async Lambda workers -
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
Common Dev things across 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
-
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
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
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 -
Making Changes via Terraform
This is a guide to the variousterraform
directories inidentity-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
Private Articles
Product
Product and process
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
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
events.log
structure and event descriptions -
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
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
-
Reviews
Mid-Year and End-of-Year Self Review and Peer Feedback -
Services and Accounts
List of external services and logins to manage
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
-
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