GHE Migration and SAML Enforcement Overview

Purpose

This project is around getting Mozilla's GitHub organizations imported into GitHub Enterprise (GHE) and getting SAML enforced - which uses Auth0 to verify the user's phonebook (LDAP or FxA backed) account and link it to the user's GitHub account.

This allows for more certain onboarding and off-boarding, and better communication paths around any other maintenance activity regarding GitHub.  Previously large effect actions have been hampered because we have no way to reliably communicate with large numbers of folk in our GitHub orgs.

Common questions/concerns

• Is this required?
  • While it is absolutely a preferred path, primarily for unifying practice and support around GitHub, there may be reasons you feel your org isn't a candidate to migrate into GHE.  Please have an organization owner reach out to us (email to github-admins @ mozilla.com is a great start) and we can start a conversation.
• Why are we doing this?
  • GHE allows several things
    • Unlimited private repos.  (This is mainly a concern for older "legacy" orgs)
    • Actions can be run against private repos
    • SAML linkages (from phonebook profile to GitHub ID) - making onboard/off-board administration easier
    • GitHub enterprise level support is available
  • In addition to GHE, IT is also involving itself more in the secops posture and KTLO level work
• Cost/Licensing
  • Licensing is handled at the enterprise level.
  • While every member of an org uses a license, and every outside collaborator of a private repo uses a license, they only do so once.  So if a user is a member of org A and org B (and so on) they only use one license.
• Will there be a mountain of re-engineering/changes/etc?
  • While there will be SOME changes, we've tried to make the process as non-impactful as we can.

most of the changes are at the individual user level (linking to phonebook, authorizing tokens/keys to be used with SAML).

• • User names in GitHub are not changed - they're just linked to the auth0 identity.  (LDAP or FxA backed)
  • URLS do not change - we're not removing orgs or changing org names or moving repos
• Bot Accounts
  • Bots need to change somehow to work with SAML
    • They can be converted to an Outside Collaborator.
      • This is the easiest to implement and least impactful at the time of the move
      • However, this means that they can't be managed by teams, and need to be invited to any new repositories.
    • They can be converted to an App
      • GitHub Apps are the newer, and per GitHub more recommended way of doing things - but this would require the bot owners to re-engineer their bot into an app.
    • If your bot workload can't handle (or you'd like to discuss with us) being made into an Outside Collaborator, we'd love to have a conversation.  It may be that you aren't a candidate to move into GHE yet.
• What about community participation?
  • There's several paths of participation
    • For public repos, anyone can work issues, file PR's - without any explicit access - Nothing changes here due to GHE/SAML.
    • People can be granted more access to specific repos as "Outside Collaborators" (OCs) - Nothing changes for them either.
    • If people are members of the org there's two paths:
      • They'll need to have a phonebook account (free and self serve to setup) and an FxA account (similarly self serve) in order to SAML.  OR
      • They can be converted to outside collaborators (which has no impact on their access level) and then there's no change.

Pre-Migration work

This phase can happen LONG before the migration starts, and largely deals with things like setting up communications/billing/exception handling.

Dealing with billing

One of the few changes that GHE forces is that all payments must be via invoice for GHE - so any credit card transactions have to be found (GitHub will provide us a list of things that are being paid for by CC in an org) and converted to invoice.

Auditing for people with unneeded ownership permissions to the org

With IT helping with on-board/off-board/KTLO, there's less need, and with secops involved, less desire to have many owners in the org.  So we'll be reaching out to the owners to reverify their need for ownership. 

=== Getting as many non-phonebook linked people linked === 

This entire process rests on the phonebook linkage, so the higher the percentage that are linked, the less disruption there is.  Linkage directions will be sent multiple times to users, and can be found here for the curious.

Bots

Since there's no "BOT" flag in GitHub, we'll need the help of the org members to identify bot accounts. 

Once identified, they can be converted to "Outside Collaborators" (OC) in GitHub - which removes them from concern with regards to SAML enforcement, and still allows them access to their repos. OC's don't participate in SAML, and so can continue operating as before. The only drawback is that they aren't members of the GitHub org, and thus aren't part of teams, but can still have any allowed role in a repo. If you have questions about bots or OCs, please reach out to the GHE admins.

Users not linked to a phonebook account

When SAML is enforced, anyone that hasn't successfully SAML'd will be (temporarily) removed from the organization.  Upon successfully SAML'ing they'll be let right back in. 

However, to SAML you need two things from phonebook

• A linked GitHub account (You can confirm by checking the Identities section of your people.mozilla.org entry).
• Membership in a group for users that access the GitHub org you belong to.  (You can confirm by checking the Access Groups section of your people.mozilla.org entry - scroll down to the "mozilliansorg" section).

Communication paths

Org to IT

Used for "We need something from IT" Onboard, orphan permission changes, archiving, questions.

• Bugzilla - Please don't mark it as fully confidential without cc'ing in someone from the ghe-admins@ group. https://bugzilla.mozilla.org/enter_bug.cgi?product=mozilla.org&component=Github%3A+Administration
• Matrix - https://matrix.to/#/#github-admin:mozilla.org
• Email - mail to ghe-admins @ mozilla.com

IT to Org

We'll need to communicate to the org.   This will likely be a single or group of "deciders" for the GH org, and will likely be different for many orgs. 

If there is an existing communication process you use, please let us know, so we can use it for our

Migration process

It's a 4 week process all told where we send communications to all users we can identify via their phonebook linkage. 

Warn/Migrate

• The org is actually migrated into GHE at this point.  The migration itself is impact free - if the invoice operations have been handled.
  • an early org was unknowingly migrated ... 3 weeks before an OWNER noticed - unknown if the users have noticed.
• We send out comms to all identified users in the org (phonebook linked) telling them of the upcoming SAML changes, and steps they'll need to do when that happens in about a week
• We invite all identified users into the phonebook group giving them access.
  • Accepting this invite is one of the items in that comms email
• We also put the directions and notifications in an org-wide team notification, trying to reach whoever we can.

Enable

• A week after the previous step we enable the SAML connection in the org.
• We send out comms about this, and that people should click the green button for SAML, and follow the (now repeated) directions
• At this point, we're waiting and watching the org, helping any stragglers (people who didn't accept invites, have the wrong GH ID linked, etc)
• One week after enablement we'll look at the SAML rate, and if it's low, we'll send out a reminder.

Enforce

• Two weeks after enablement, it's time to enforce
• We send out a final email that we're enforcing.  And what to do if you haven't SAML'd yet.
• We enforce SAML on the org
• At this point, anyone that hasn't SAML'd is removed from the org. 
  • They receive an email from GitHub about this, including a button to hit to SAML and be reinstated.
  • If they've accepted invites, and have the link in phonebook, this will "just work".
  • If they haven't they're redirected here, and if they follow those direction's we'll be able to help them get connected.