View source for GitHub/GHE SAML User FAQ

= '''NOT''' for new access - this page is around migrating and troubleshooting existing access =
For that questions around setting up new access, read [[GitHub#Can_I_be_a_Member_of_the_Mozilla_Organization.3F|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 [https://people.mozilla.org/e/ 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 [https://people.mozilla.org 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 [https://accounts.firefox.com/ here] if you don't have one
* And if you do use a Mozilla account, you'll need to enable 2FA for it - [https://support.mozilla.org/en-US/kb/secure-firefox-account-two-step-authentication here]
* Using that Firefox account, you can sign up on [https://people.mozilla.org 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 [https://people.mozilla.org/e/ 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"
## Note, you can also link your Bugzilla ID here.
# You should be taken to GitHub to log in and verify your ID.
## 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 [https://people.mozilla.org/e/ 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
## In your [https://people.mozilla.org/e/ profile], scroll down to "Access Groups" and under that "mozilliansorg"
## Look for the appropriate group (e.g. "ghe_mozilla_users") in the list
## If it's there, Yay!  If not, continue with filing a bug, etc.
# File a bug [https://bugzilla.mozilla.org/enter_bug.cgi?product=mozilla.org&component=Github%3A+Administration 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.
## 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 : "<nowiki>https://github.com/orgs/<ORGNAME>/sso</nowiki>" --- 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 [https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on 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 [https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-an-ssh-key-for-use-with-saml-single-sign-on 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 [https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-oauth-apps 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 [https://support.mozilla.org/en-US/kb/secure-firefox-account-two-step-authentication 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.)
* [https://support.circleci.com/hc/en-us/articles/360043002793-Troubleshooting-CircleCI-access-after-enabling-Github-SSO 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 [https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github 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 - [https://matrix.to/#/#github-admin:mozilla.org #github-admin] on Matrix
* Bugzilla - [https://bugzilla.mozilla.org/enter_bug.cgi?product=mozilla.org&component=Github%3A+Administration mozilla.org::Github:Administration]
* Email - ghe-admins @ mozilla . com