Enforcing 2FA on an Enterprise account with a separate IDP

If you are the custodian of a GitHub Enterprise Organization then it’s likely that security is front of mind. If you haven’t already enabled and enforced  Two Factor Authentication  (more commonly referred to as 2FA) and are looking for ways to enhance security, and provide increased protection for your users and your intellectual property then 2FA is worth consideration.

Two Factor Authentication uses two separate pieces of information that can be corroborated to confirm a user’s identity. In addition to the initial authentication through either SAML Single Sign On or username and password, 2FA requires the user to provide a code generated either by GitHub or the user’s authenticator app. The code is short lived and can only be used once.

When 2FA is enforced, the only way for a user to access their account is by knowing their password and having access to the code on their phone or device. This provides your organization with additional confidence that the user is who they are claiming to be and makes account compromise more difficult for bad actors to achieve.

Enabling and Enforcing 2FA on your Enterprise or Organization

Enabling 2FA on either your Enterprise Account or at the Organization level is easy. As an Administrator in your security settings, click  Require two-factor authentication for everyone in the <<your_org_name>> organization.  and hit  Save.

_ Note:  For organizations using SAML Single Sign On, 2FA enforcement is independent of your chosen identity provider._

Caution:  When “Require two-factor authentication” is enabled, members, outside collaborators, and billing managers (including bot accounts) who  do not use 2FA will be removed  from the organization and lose access to its repositories. In short,  any and all users that do not have two factor security configured for their GitHub account will be prevented from accessing your organization.

It’s best practice to communicate the planned implementation of 2FA to your user community to avoid loss of access. However, there’s help to reinstate access should someone ‘not get the memo.’

Users are free to choose from a number of authenticator apps, hardware tokens (like YubiKeys), or just SMS. There is no provisioning or maintenance required to enforce 2FA for your organization.

To learn more about requiring 2FA for your organization, please read our help article on Requiring two-factor authentication in your organization.

How 2FA is configured

Users manage their own 2FA security settings independent of any organizational membership and is strongly recommended for GitHub and any other service that supports 2FA.

The act of supplying the correct code from the 2FA app shows that the user is in possession of the registered device being used for 2FA and acts as a secondary verification step to validate that the user is in fact who they claim to be - it does not validate or authenticate against the Identity Provider directly - regardless of the provider or scheme (SAML SSO or Built-in Authentication).

Most mobile 2FA applications can be configured to work with a user’s GitHub account using a simple flow that starts by scanning a QR code with the mobile device. For more configuration information, please see our detailed guide on Configuring two-factor authentication.

Popular 2FA applications include:

  • DUO
  • Okta
  • Google Authenticator
  • Microsoft Authenticator
  • 1Password
  • Authy
  • LastPass Authenticator


Cautionary Notes

  • The Enterprise Account or Organization can be configured to require a user to have 2FA configured and in place, but cannot enforce the user selection of 2FA mechanism or provider through GitHub tooling.

  • Any users without 2FA configured when 2FA is enforced at the Organization or Enterprise Account level  will be removed  from the Organization(s) at that instant.

  • Users are responsible for selecting, installing, configuring and maintaining their 2FA settings and can change these settings at will.

  • A user cannot disable 2FA while a member of any GitHub organization that requires 2FA as part of the security settings. To disable 2FA a user must first remove themselves from all organizations that require 2FA.

In Summary

If you haven’t mandated Two Factor Authentication for you organization, we strongly recommend that you take advantage of this GitHub Enterprise feature. 2FA provides additional assurance of a user’s identity and makes account compromise much harder. There’s little to no maintenance but there are some side effects that need to be carefully considered and communicated to the users in your organization so that they don’t get locked out (including bot accounts and external collaborators!)

Have more questions around 2FA or how GitHub is helping the Open Source Community with security issues? Please share your thoughts, questions and comments here.

GitHub Enterprise Help Documents

Note that GitHub 2 Factor Authentication (2FA) is not compatible with RSA hardware tokens. YubiKey hardware authentication devices are compatible with GitHub’s 2FA technology.

Written with @alwell-kevin.