Enterprise SAML Lockouts: How to Regain Access Quickly 🔐

[github-staff]

Problems with your Identity Provider (IdP) may cause yourself and users to be completely locked out of your enterprises and the organizations within it. If you are locked out of your Enterprise, it is possible to access it again through these methods, from fastest to slowest:

• Use your SSO recovery code.
• If you do not have recovery codes, retrieve them with an API query.
• Contact support to unlock your Enterprise

Using your Recovery Codes

Recovery codes are the fastest method of recovering your enterprise from a SAML lockout. These codes are shown to the enterprise owner who configured SAML, or in the case of an Enterprise Managed Users (EMU) enterprise, the setup user. We strongly encourage that these codes are saved before switching on SAML. If you don't think you have the recovery codes, they may actually be in fact saved somewhere, like a file name that contains the name recovery, in backups or entries in password managers.
To use a recovery code for non EMU enterprises:

• Navigate to https://github.com/settings/enterprises
• Click Settings next to your enterprise.
• On the screen to single sign onto your enterprise, click "Unable to single sign-on? Use a recovery code".
• Enter a recovery code and click Verify.

To use a recover code for an EMU enterprise:

• Navigate to GitHub.com while signed out of all accounts.
  Sign in with your setup user username and password. The setup user has a username format of EMU-SHORTCODE_admin.
• Below the SSO prompt, follow through to "Unable to single sign-on? Use a recovery code".

Retrieving your enterprise recovery codes through an API query.

If you do not have a local copy of recovery codes, an enterprise owner may be able to retrieve recovery codes by creating a Personal Access Token (PAT) with the scope read:enterprise using the following GraphQL query:

NB: For GitHub Enterprise Cloud with data residency: change the POST URL to https://api.ENTERPRISE_SLUG.ghe.com/graphql.

{
  enterprise(slug: "ENTERPRISE_SLUG") {
    ownerInfo {
      samlIdentityProvider {
        recoveryCodes
      }
    }
  }
}

The above query can also be executed via curl if you do not wish to use an API client (replace <TOKEN> with your PAT):

curl -XPOST https://api.github.com/graphql -H 'authorization: bearer <TOKEN>' -d '{"query":"{enterprise(slug:\"ENTERPRISE_SLUG\"){ownerInfo{samlIdentityProvider{recoveryCodes}}}}"}' --compressed

Contacting support to unlock your enterprise.

In cases where recovering access to your enterprise is not possible, you will need to open a support ticket to request SAML configuration to be removed from your enterprise. We need the following to disable SAML for your enterprise account:

• Permission from two enterprise owners, or in the case where there is only one enterprise owner, from the sole owner of the enterprise. Other roles in the enterprise such as a billing manager or an owner of an organization only cannot give permission.
• The permission must explicitly permission to switch off SAML and state the enterprise. For example, "I grant permission to switch off SAML for the 'ORGANIZATION_SLUG' enterprise".
• The permission must come from a verified email address on their GitHub account.

To reduce the amount of time required to turn over an unlock request, make sure enterprise owners are prepared as above. In cases where another enterprise owner cannot access the support portal, please CC their verified email address on the email chain.