roll-out-plan.md

SAML Plan Rollout

Week 0

• What is SAML?
  • https://github.com/jch/saml/blob/master/README.md
• What is SSO?
  • IAM with SAML SSO
  • Official Supported SAML services

Week 1

• GitHub purchased + upgraded
• Configure testing
  • Cloud: For GHEC you can create a new org within your Enterprise to use for testing or use a current org but do not switch on the “enforce” option. Once successfully configured users will see an “authenticate with saml” banner so using a separate org might be needed to avoid users seeing this.
  • Server: For GHES we recommend using a test/staging instance of GHES as there is no enable but not enforce option so once enabled all users will need to authenticate through SAML.
• Begin manager communication, ideally at Engineering Managers Meeting
• Create documentation plan for tracking information about users, admins, and bot accounts
  • Managing bots and service accounts with SAML SSO

Week 2

Audit Users

• Audit User activity in repo
  • GHEC Script: Find inactive users
• Audit Admins who don’t need to be admins
  • Manually look through admin permissions. Make note of anything that goes against expectations. Follow up and communicate to see why this is necessary.
  • Script: GHE org permissions report
• Audit Bots to be marked as outside collaborators
  • This is done primarily through communication
  • On GHEC, you can see outside collaborators through the outside_collaborators tab: https://github.com/enterprises/<enterprise>/outside_collaborators
• Choose a plan for bots/service accounts.
  • Help: Managing bots and service accounts with SAML single sign on
  • Options include:
    • Adding service accounts as outside collaborators
    • Create a separate organization that isn't SAML enforced (GHEC only)
      • Repositories can be forked into this organization and marked as Internal.
    • Allow built in authentication for users outside of your identity provider (GHES only)

Testing & Initial Configuration

• Configure initial testing environment with identity provider
  • Enabling and testing SAML single sign on for your organization
  • GHES:
    • SAML attritubtes
    • If you are migrating from LDAP to SAML and would like to continue using Team Sync with SAML, we have this open-source utility:GHEC: Script for SAML and Team Sync - active directory
  • GHEC Mapping SAML to GitHub IDs: Script to pull details to help cross reference
• Decide on 2FA plan
  • If you choose to configure 2FA on GitHub, here are instructions

Communication

• Begin user communication
• Message inactive Admins to ensure that they do not need access before downgrading
• Identify pool of test users and bots based on manager and engineer feedback

Week 3

• Enact plan on managing bots and services accounts
• Remove inactive admins
• Remove inactive bots
• Remove inactive users
• Enable SAML
  • GHEC: Enabling and testing SAML single sign on for your organization
  • GHES: Configuring SAML
  • GHEC: Verifying your organization's domain
  • GHEC: How to restrict notifications to your domain only
  • Azure AD, Okta, and OneLogin: About SCIM
• Add GitHub to IdP
• Manually provision GitHub to test users
• Communicate to test users
• Manual testing by users in test pool
• Ensure bots can deploy when marked as outside collaborators

Week 4

• Provision GitHub to all of Engineering via IdP
  • Preparing to enforce SAML single sign on
• Add GitHub to appropriate IdP group
• Announcement email
  • GHEC Users will need to:
    • Authorize personal access tokens for use with SAML
    • Authorize SSH keys for use with SAML

Week 5

• Audit for adoption
  • GHEC: script to run via GraphQL
  • Server: As you click the button, you will be prompted with list of users who do not yet have it enabled, and asked if you are sure you want to enforce
• Resolve unverified accounts
• Prepare response team for SAML enforcement

Week 6

• Wrap up communication
• Rollout / SSO Required in GitHub
  • Users not authed via Okta will automatically removed from of the Org and will need to auth via Okta and be manually added to the Dev Team. You can find instructions here.
  • Enforcing SAML
• Response team available for immediate auth needs

Beyond

In the future, when a user is provisioned GitHub in the SAML IdP, they will receive an GitHub Organization invite email from GitHub. The user should click on the link in the email and complete the SSO flow. This will be the standard for all new users once SAML authentication is enforced.