NOT for new access - this page is around migrating and troubleshooting existing access

For that questions around setting up new access, read here. Being SAML'd is part of getting access, but this page is around any problems procedures encountered with the SAML process itself.

GHE SAML User FAQ

A page for users attempting to SAML into a GitHub organization with Mozilla IP.

What is SAML? Isn't this the same as SSO?

You often hear about SSO (Single Sign On), allowing you to use one account in many places. The protocol that SSO uses to do this is SAML - Security Assurance Markup Language. In the case of GitHub, we aren't using it to just do one set of credentials, you'll still have your Mozilla/People.m.o login, AND your GitHub login, but this will make it so that you will have to have a valid account setup with Mozilla to access Mozilla organizations in GitHub. This is why we stopped calling this "SSO" in this project, as that setup a false sense of "Are you going to make me change my github configs/accounts?!?!" Once setup, things should proceed much as before.

But my GitHub account is Mine! What happens if I leave Mozilla?

SAMLing does NOT change your GitHub account, nor does it give Mozilla personnel any authority over your account. You will still log into GitHub with your usual GitHub account/password/2FA setup.

The only thing SAMLing does is authorize your GitHub account to access Mozilla SAML controlled areas in GitHub. This is handled via Auth0 and your people.m.o profile.

If you leave Mozilla, you'll lose that special access, but your GitHub account is yours.

I already did this for org X, so I'm done, right?

Sadly no - SAML is setup per org. So if you belong to org "Mozilla" and "Mozilla-IT" you'll need to belong to the right phonebook groups and do SAML for EACH of them.

SAML Pre-reqs

Several things need to happen before you can SAML:

You need a people.m.o account

If you're an employee, or LDAP'd you already have a people.m.o account, and can skip this section.
But if you're not, you can use a Mozilla account to create a people.m.o account - sign up here if you don't have one
And if you do use a Mozilla account, you'll need to enable 2FA for it - here
Using that Firefox account, you can sign up on people.m.o for an account
NOTE: DO NOT use GitHub to authorize to people.m.o - if not LDAP'd, use Firefox accounts

People.m.o linkage to GitHub account

In your profile on people.mozilla.org you need to have your identity from GitHub connected and verified.

Log onto your profile people.mozilla.org
Scroll down until you see the "Identities" section
Click on the pencil icon to edit it.
Click on "+ Identities"
Select "GitHub" from the dropdown menu and click "VERIFY"
1. Note, you can also link your Bugzilla ID here.
You should be taken to GitHub to log in and verify your ID.
1. You may see a button to “Authorize Mozilla” - Click that.
Get back to your people.m.o profile, and edit the identities (Steps 1-5)

This linkage does NOT change anything in your GitHub account, merely allowing Mozilla staff and Auth0 to see the connection between your GitHub ID and your people account.

Make an email address at least Staff visible

Log onto your profile people.mozilla.org
Scroll down until you see the "Contact" section
Click on the pencil icon to edit it.
Add an email (if there isn't one already)
Click on the small icon to the right of the text box, and select "Staff"

Belonging to the correct group in people.m.o

If you want to SAML to a GitHub organization named <ORGNAME> you'll need to belong to a group in people.mozilla.org named "ghe_<ORGNAME>_users" - so if "mozilla-it" is the org, "ghe_mozilla-it_users" is the group.

Verify your lack of membership
1. In your profile, scroll down to "Access Groups" and under that "mozilliansorg"
2. Look for the appropriate group (e.g. "ghe_mozilla_users") in the list
3. If it's there, Yay! If not, continue with filing a bug, etc.
File a bug GitHub Administration asking for your mozilla account to be added to the appropriate people.m.o group. (for example, ghe_mozilla-it_users)
If your invitation is approved, you'll receive an email for confirmation, and you'll be a member of the group.
1. Once you have the invitation approved, log out of people (click on the profile pic in the upper left and click "Logout") then click "Sign in" also in the upper left.

SAMLing to the org

You will initially see a green "Authenticate your account" button when you log into the GitHub UI. Clicking this will start the SAML process. If you dismiss this button, sometimes it won't come back. In that case, go to the URL : "https://github.com/orgs/<ORGNAME>/sso" --- so if Mozilla, https://github.com/orgs/mozilla/sso You may get taken to an error page if there's a problem - the page has directions on what to try, and who to contact.

If this works, you've SAML'd - though there might be more steps you'll need to take if you're using keys, or tokens, or other integrations, read on.

SAML Timeouts (or, "Why do I have to click a button EVERY day?!")

SAML sessions to GitHub timeout after 24 hours per GitHub's defaults. And unfortunately Auth0 and GitHub speak sufficiently different dialects of SAML that the timeouts that we use with other providers aren't working, and multiple support tickets with GitHub and Auth0 have yet to resolve the issue.

If this is horrific imposition for you, we may be able to help with strategies to lessen or avoid the concern - please reach out to our bug/email channels and we're happy to discuss.

Alright, I've SAML'd what now?

There are several things you need to potentially touch to keep things working as before

Authorize PAT (Personal Access Tokens)

Any PATs that you have need to be told that they can be used with the SAML'd org. Directions here.

NOTE: This needs to be done whenever you initially SAML to a new org.

Authorize SSH Keys

Similar to PATs, any SSH keys associated with your account need to be updated to allow access to SAML orgs. Directions here.

NOTE: This needs to be done whenever you initially SAML to a new org.

Refresh GH CLI

We've received reports that you may need to issue a "gh auth refresh" with the gh CLI client.

Refresh GH Android/iOS app

You need to tell the app that things have changed by signing out and back in again.

Settings -> Manage Account -> Sign out (on iOS swipe left)
Then sign back into the app using your GitHub credentials
You will be prompted to authorize your app for any SAML organizations you belong to.
- When you hit the "Authorize" button, you'll do the Auth0/2FA dance
Once you've authorized all the organizations you want to, you'll be asked to "Authorize GitHub" - do this, and you should be back to working.

Reset OAuth Tokens

If any OAuth'd apps stop working, you may need to reset their tokens. To date we've seen this with GitHub plugins for VS Code, though others do it as well.

Unlike SSH/PAT, OAuth doesn't currently have a way to update the token with new authentications.

First, try logging out/back in for the OAuth'd thing.
Second, try revoking the token using the directions here
After revoking, redo the setup of the affected system again to regenerate the token.

Troubleshooting

SAML issues

Often you'll get taken to GitHub/SAML issues on a failure - follow those directions on reporting the problem.

"Additional Security" Error

If you get an error like the following, you need to establish 2FA on the account you are signing into people.m.o with. (For Firefox accounts, look here)

Mozilla requires you to setup additional security measures for your account, such as enabling multi-factor authentication (MFA) or using a safer authentication method (such as a Firefox Account login). You will not be able to login until this is done.

Slack Integration

Sometimes you may receive a notice that slack integrations have failed "Subscription to ORGNAME has been disabled, because <USER>, who originally set it up has not authorized the organization using SAML."

Check that <USER> has authorized their SSH keys per the directions above
Have <USER> resend `/github signin` in slack to reauthenticate.

Circle CI

"Overwrite your linked identity?"

Some people have gotten the above error on logging into Circle CI after SAML. They'll see references to their "old" SAML ID of their email address, and a "new" SAML of something like "ad|Mozilla-LDAP|<LDAP username>" - and asked if they want to go back and try re-saml, or "Overwrite and continue" ... So far "Overwrite and continue" is reported as working.

Problems with Circle CI post SAML

Some people have reported problems with using Circle CI after SAMLing - here's reports of what helped them

Clear cookies

In a private window log out of Circle CI
Clear all Circle CI cookies
Log back into circle CI

Restart Jobs

Having cleared cookies, go to Circle CI, and for any PR's or other items that haven't running properly, restart the automation on them

Re-setup the project

Try clicking "Stop building" in the Circle CI project settings, then going to the org page and clicking "Set up project" on the repo.

Directions from CircleCI

While the above have worked for most, the following is direction from CircleCI on changes post SSO/SAML. (Note that updating PAT/SSH keys is also mentioned here, if you've done that from above, you won't need to here.)

CircleCI access after enabling Github SSO

CircleCI webhooks failing after SAMLing

After doing all of the above you should have error free access to CircleCI, but some reports have come in about intermittent webhooks failing with status code 400

Have a SAMLd user re-issue the deploy key used in the affected repo.

Visual Studio Code GitHub extension issues

After SAMLing, various of the GitHub extensions to vscode may not work until you re-authorize them.

This specific fix works for the GitHub.vscode-pull-request-github extension.

As a rule, after doing the SAML enrollment, you need to re-auth all things using GitHub

Remove any entry from your system's keychain related to vscode and GitHub - on MacOS, `vscodevscode.github-authentication` appears to be the one - then re-set up your auth with the extension per the extensions instructions (and now it should prompt for SAML auth as well)

Getting Help

Chat - #github-admin on Matrix
Bugzilla - mozilla.org::Github:Administration
Email - ghe-admins @ mozilla . com

GitHub/GHE SAML User FAQ

Contents