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

• AppDev

  Application development

• Architecture

  High-level architecture explanations

• Development

  Common Dev things across AppDev and DevOps

• Handbook

  About this handbook

• Netlify Sandbox

  Sandbox for NetlifyCMS demos

• Partnerships

• Platform

• Private Articles

• Product

  Product and process

• Reporting

• Security

• Team

  Articles for the whole team

All Articles

AppDev

Application development

Deploying

• 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

• Identity Proofing Testing
  Tips and tricks for testing identity proofing (IAL2 accounts) including example fake phone numbers and example PII

• 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

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

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

• Troubleshooting 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

• Cloudwatch Dashboards
  How to search for, create, and manage cloudwatch dashboards

• 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, replaced in favor of RFCs

• 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

• 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
  Team code repos, permissions, notification strategies

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

Documentation

• Postmortem Template

• 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

• macOS PIV to SSH key extraction

Other Articles

Handbook

About this handbook

• Contributing to the Handbook
  Guidelines for contributing to the handbook

• Template Page
  An example article that you can copy

Netlify Sandbox

Sandbox for NetlifyCMS demos

• Example Netlify demo
  Page for editing

Partnerships

• 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 Internal Pilot Playbook
  Coordinate Pilots of new features with our 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 Infrastructure PRs/Issues
  Detailed guide on how to file Issues and Pull Requests for the Login.gov Infrastructure Team.

• 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 Production Deploys
  How to deploy changes to the production Gitlab system

• Infrastructure Metrics and Alerting

• 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

Private Articles

Product

Product and process

• 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

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

Reporting

• Analytics Events
  events.log structure and event descriptions

• Google Analytics
  Brochure site analytics and the Digital Analytics Program

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

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

Security

• Incident Response Guide
  Security Incident Response Guide

• 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

• 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

People Ops

• Leave Guidance

• Offboarding

• Onboarding

• Overtime

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

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

• Staffing
  

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

• 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

• RFC Template
  “Requests for Comments” or Pitches, see folder of existing RFCs