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.

Team

Articles for the whole team

• Login.gov Principles
  Our mission and project principles

• Onboarding

• Offboarding

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

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

• Glossary
  Explanation of common terms, acronyms, and abbreviations

• Incident Response Checklist
  Quick reference checklist for incident response

• Leave Guidance

• Org Chart

• PII Guidance
  Guidance on safe handling of Personally Identifiable Information

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

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

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

• 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

• Staffing
  

Handbook

About this handbook

• Contributing to the Handbook
  Guidelines for contributing to the handbook

• Template Page
  An example article that you can copy

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

• Overtime

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

Development

Common Dev things across AppDev and DevOps

• GitHub
  Team code repos, permissions, notification strategies

• Postmortem Template

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

• macOS PIV to SSH key extraction

AppDev

• AppDev Oncall
  Responsibilities and runbook for AppDev oncall

• Bug Bounty Triage
  How to handle bug bounty reports

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

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

• Deployer Rotation
  Spreadsheet to track the AppDev Deployer

• 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

• 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

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

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

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

• 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

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

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

• 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

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

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

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

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

Architecture

• 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

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.

• Config PR review checklist
  Data map for identity-idp-config YAML files to data sources (IAA GTCs and Orders, Dashboard, etc)

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

• Partner Support Ticket Handling
  How to handle and track support requests 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.

• RACI framework for Partnerships team

Platform

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

• Acceptance Criteria for Infrastructure PRs/Issues
  Detailed guide on how to file Issues and Pull Requests for the Login.gov Infrastructure Team.

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

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

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

• Email Routing
  Inbound and outbound SMTP information

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

• GitLab
  GitLab Setup

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

• Infrastructure Metrics and Alerting

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

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

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

• Platform Disaster Runbooks
  Recovering from really really bad stuff

• Platform On-Call Guide
  Runbook/guide for processes/responsibilities for the on-call platform engineers.

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

• 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

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

• Team Radia Sprint Ceremonies
  How Sprints and Standups operate

Reporting

• Analytics Events
  events.log structure and event descriptions

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

Private

• Private Articles