GitHub/GHE SAML User FAQ

From MozillaWiki
< GitHub
Revision as of 18:53, 15 June 2022 by Cknowles-moz (talk | contribs) (Creating a firefox account for phonebook)
Jump to navigation Jump to search

GHE SAML User FAQ

A page for users attempting to SAML into a Mozilla controlled GitHub Enterprise Organization.

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 Firefox account to create a people.m.o account - sign up here if you don't have one
  • And if you do use a Firefox 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

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.

  1. Log onto your profile people.mozilla.org
  2. Scroll down until you see the "Identities" section
  3. Click on the pencil icon to edit it.
  4. Click on "+ Identities"
  5. Select "GitHub" from the dropdown menu and click "VERIFY"
    1. Note, you can also link your Bugzilla ID here.
  6. You should be taken to GitHub to log in and verify your ID.
    1. You may see a button to “Authorize Mozilla” - Click that.
  7. 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

  1. Log onto your profile people.mozilla.org
  2. Scroll down until you see the "Contact" section
  3. Click on the pencil icon to edit it.
  4. Add an email (if there isn't one already)
  5. 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.

  1. 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)
  2. 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 do try, and who to contact.

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.

Troubleshooting

Circle CI

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

Getting Help

Retrieved from "https://wiki.allizom.org/index.php?title=GitHub/GHE_SAML_User_FAQ&oldid=1242963"