SAML is the control that makes GitHub access a corporate identity decision rather than a GitHub one.
It is also the control that, when misconfigured, prevents every engineer in the company from working — which is why the operational details below matter more than the configuration steps.
The short answer
Section titled “The short answer”SAML SSO controls access to organisation resources. GitHub’s description: it “gives organization owners and enterprise owners a way to control and secure access to organization resources like repositories, issues, and pull requests.”
Three enforcement states: disabled, enabled but not enforced, and “enabled and enforced.”
Re-authentication is periodic, with a login period GitHub documents as “generally 24 hours.”
Supported identity providers, as documented for organisation SAML: Microsoft AD FS, Microsoft Entra ID, Okta, OneLogin, PingOne and Shibboleth, plus “IdPs that implement the SAML 2.0 standard.”
Configure it at the enterprise level rather than per organisation, unless you have a specific reason not to.
Enterprise-level or organisation-level
Section titled “Enterprise-level or organisation-level”SAML can be configured for an enterprise or for an individual organisation, and the choice has lasting consequences.
Enterprise-level SAML applies across the enterprise’s organisations. One configuration, one certificate, one enforcement decision.
Organisation-level SAML is per organisation. Each has its own identity provider connection and its own enforcement state.
Prefer enterprise-level. The reasons compound: one certificate to monitor rather than twenty, one configuration that cannot drift, no possibility of a newly created organisation being left ungated, and one place to look when diagnosing.
Organisation-level SAML has a narrow legitimate use: an organisation that genuinely needs a different identity provider — a joint venture, or a subsidiary with its own directory. That is rare, and it should be a deliberate exception rather than an accident of history.
Many enterprises have both, because the original organisation was configured before the enterprise account existed and nobody removed it. That state is worth resolving: overlapping configurations produce behaviour that is hard to reason about, and two certificates to monitor instead of one.
Migrating from organisation-level to enterprise-level re-links identities. Every member re-authenticates, and every authorised credential is affected. Plan it as a change with notice, not as a cleanup task.
Enforcement states in practice
Section titled “Enforcement states in practice”Disabled is the starting point.
Enabled but not enforced is the transitional state, and understanding it correctly is the key to a smooth rollout. Members can authenticate through the IdP and link their identity; they are not required to. Access continues for those who have not.
This is exactly what you want during rollout, because it lets you drive the link rate to near-100% before anybody is locked out.
Enabled and enforced requires the linked identity. Members who have not linked lose access at the moment of enforcement.
The transition from enabled to enforced is the risky moment, and it is entirely de-risked by measuring the link rate first. If 40 of 900 members have not linked, enforcing today produces 40 blocked engineers and 40 support tickets; chasing them first produces none.
What happens to credentials
Section titled “What happens to credentials”The largest source of support load, and it is entirely predictable.
Classic personal access tokens must be authorised after creation before they can access a SAML-protected organisation.
SSH keys must be authorised in the same way.
Fine-grained personal access tokens are authorised during creation, before access is granted — which is one of several reasons to prefer them.
A linked external identity is a prerequisite for authorising either: GitHub documents that “before you can authorize a personal access token or SSH key, you must have a linked external identity”, created by authenticating with the IdP at least once.
Revoking an SSH key’s authorisation is one-way. GitHub states that if authorisation is revoked by an organisation, “you will not be able to reauthorize the same key and will need to create a new SSH key and authorize it.”
What this means at enforcement time: every developer’s existing SSH key and every existing token stops working against the organisation until authorised. If you have not told them this will happen and how to fix it, you will spend a day explaining it several hundred times.
Say it in advance, with the exact steps. A short page: here is what will stop working, here is the link to authorise it, here is who to ask. Published before enforcement, not after.
Rolling out
Section titled “Rolling out”-
Configure at the enterprise level, in the enabled-but-not-enforced state.
-
Test with a small group. Sign in, link identity, clone over SSH, clone over HTTPS with a token, run a CI job. Every path, not just the browser.
-
Store the recovery codes in the corporate secret manager, accessible to more than one person, and verify they work.
-
Publish the developer instructions — what will stop working and how to fix it — before announcing the date.
-
Announce the enforcement date with at least two weeks’ notice.
-
Track the link rate. Members with linked identities versus total members, weekly.
-
Chase the gap individually in the final week. Investigate every account that cannot or will not link.
-
Enforce at a low-traffic time, with somebody holding recovery codes on hand.
-
Watch the support channel for the following day. The volume tells you how good step 4 was.
Do not enforce on a Friday, and do not enforce during a release window. The cost of getting this wrong is every engineer, at once.
What SAML does not cover
Section titled “What SAML does not cover”The gaps are as important as the coverage, and each is a place where access exists outside the control.
Outside collaborators. GitHub documents that “SSO authentication is not required for outside collaborators.” If your contractors are collaborators rather than members, they are outside SAML entirely — no IdP authentication, no session expiry, no deprovisioning path.
Public repository access. Viewing a public repository’s overview and file contents, and cloning it, do not require IdP authentication. For an enterprise with public repositories this is expected and correct, and worth knowing when reasoning about what SAML protects.
GitHub Apps. An app authenticates with its own private key and installation token. It has no SAML session and is unaffected by enforcement. This is correct — an app is not a person — and it means the app’s permissions are the control, not SAML.
The GitHub account itself. SAML gates organisation resources. The person still has a GitHub account, still signs in to GitHub normally, and still has whatever else that account can reach. GitHub is explicit: “SAML SSO does not replace the normal sign-in process for GitHub.”
Existing clones. Somebody with a clone on their machine keeps it. Revoking access stops future fetches; it does not reach the copy they already have.
Which is the honest scope: SAML controls new access to organisation resources, through authenticated paths, for members. Everything else needs a different control.
Sessions and what revocation reaches
Section titled “Sessions and what revocation reaches”Worth being precise, because this is what matters during an incident.
A SAML session has a lifetime, generally 24 hours, after which re-authentication is required.
Revoking a session ends it immediately. The person must re-authenticate, and if their IdP account has been disabled, they cannot.
Revoking the linked identity is stronger. It severs the connection between the GitHub account and the IdP identity, and it invalidates the authorisation of credentials that depended on it.
Revoking authorised credentials individually removes specific tokens and SSH keys.
Doing all three is the complete action for an incident, and doing only one is the common mistake — a revoked session with an authorised token still in place leaves Git access working.
Order matters slightly: revoke credentials first, then the identity, then sessions. Revoking in the other order leaves a window in which a live session can create a new credential.
Suspending the account is the strongest response available for a managed user; for a personal account under SAML, removal from the organisation is the equivalent.
Practise this once. An incident is not the time to discover which screen does what, and the whole sequence takes under two minutes when you know where the controls are.
Certificate rotation
Section titled “Certificate rotation”The most common SAML outage, and it is a diary entry away from being impossible.
SAML depends on your IdP’s signing certificate, and certificates expire.
On expiry, authentication fails completely. With SAML enforced, that means no access to organisation resources for anybody whose session has lapsed — and sessions lapse continuously, so the outage spreads over roughly a day rather than arriving at once. That gradual onset makes it harder to diagnose, not easier.
Monitor the expiry with an alert, sixty days ahead, to a team address rather than a person’s calendar.
Rotate before expiry, not at it. Most identity providers support publishing a new certificate ahead of the cutover, and GitHub’s configuration accepts the update.
Test after rotating. Sign in from a clean session. A rotation that appears to succeed and has not is a delayed outage.
Recovery codes
Section titled “Recovery codes”The thing that gets you back in when SAML itself is broken.
They are issued when SAML is configured, and they allow an owner to sign in without going through the identity provider.
They are the only route back from a broken configuration, an expired certificate, or an identity provider outage.
Which means the handling requirements are severe:
- Stored in the corporate secret manager, not in GitHub, not in chat, not in a document readable by the enterprise
- Accessible to more than one person, because the single holder will be on a flight
- Tested annually, because a code that does not work is not a recovery path
- Re-checked whenever SAML configuration changes
Attribute mapping and what GitHub reads
Section titled “Attribute mapping and what GitHub reads”The configuration detail that causes the subtle failures, as opposed to the obvious ones.
GitHub receives a SAML assertion from your identity provider containing attributes describing the user. The mapping between your directory’s fields and what GitHub expects is configured on the identity provider side.
The name identifier is the critical one. It is what links the GitHub account to the IdP identity, and it must be stable. Using an attribute that changes — an email address that changes on marriage or a role change, a username that changes on a department transfer — means the link breaks and the person is treated as a new identity.
Prefer an immutable identifier. Most directories have one — an object ID, a GUID, an employee number — and it is what the name identifier should map to, even though it is less human-readable.
This decision is expensive to reverse. Changing the name identifier attribute re-links every identity, with all the consequences described above. Get it right initially.
Other attributes matter less for authentication but may matter for provisioning; see SCIM.
Test the failure case. Change a test user’s email in the directory and confirm they can still sign in. If they cannot, your name identifier is wrong and you have just discovered it cheaply.
Diagnosing SAML problems
Section titled “Diagnosing SAML problems”“I can see the repository but cannot clone it.” Almost always an unauthorised SSH key or token. Check their authorised credentials.
“It worked yesterday.” Session expiry, which is expected roughly daily. Re-authenticating fixes it.
“CI broke after enforcement.” A token or key used by automation that was never authorised. This is why step 2 above includes running a CI job.
“Nobody can sign in.” Certificate expiry or an identity provider problem. Recovery codes.
“One person cannot sign in.” Their IdP account, their linked identity, or a mismatch between the two. The member’s SAML access view shows the linked identity.
“They left, and their token still works.” Removing somebody from the IdP does not necessarily revoke everything. Revoke the linked identity, the sessions and the authorised credentials explicitly, and use SCIM so this is automatic.
The single most useful screen is the member’s SAML access view, showing linked identity, active sessions and authorised credentials in one place. Learn where it is before you need it.
Automation and SAML
Section titled “Automation and SAML”The category that breaks at enforcement and is discovered last, because nobody thinks of CI as a user.
Anything using a classic personal access token against a SAML organisation needs that token authorised. Which includes: CI systems, deployment tooling, monitoring integrations, scripts on a server somewhere, and the thing somebody wrote three years ago that nobody remembers.
Anything using a deploy key or an SSH key likewise.
Inventory before enforcing. Every token and key with recent activity, and what uses it. The audit log and the token list both help; the tribal knowledge of the platform team helps more.
The right long-term answer is not authorising these tokens — it is replacing them. A personal access token owned by an individual, used by a production pipeline, is a single point of failure tied to somebody’s employment. When they leave and SCIM deprovisions them, the pipeline stops.
Move automation to GitHub Apps. An app is not a person, has explicitly scoped permissions, is unaffected by SAML enforcement, and does not disappear when somebody leaves. This is the single most valuable change most enterprises can make to their credential posture. See machine identities.
For GitHub Actions, use the workflow token or OIDC rather than stored long-lived credentials wherever the target supports it.
SAML enforcement is a good forcing function for this work. The inventory has to be done anyway; doing the replacement at the same time converts a compliance exercise into a real improvement.
Multiple identity providers and migrations
Section titled “Multiple identity providers and migrations”Enterprises change identity providers, and the change is a genuine project.
GitHub connects to one SAML provider per configuration. Changing it means updating the configuration, which invalidates existing linked identities.
Every member re-links. Which means the whole rollout sequence again — measure, chase, enforce — with the additional complication that access is currently enforced, so a mistake locks everybody out rather than merely failing to gate them.
Recovery codes are essential here, more than at initial rollout, because there is no un-enforced state to fall back to.
A staged approach where the identity provider supports it: run the new provider alongside the old, migrate users, then cut GitHub over. Whether this is possible depends entirely on your providers.
Test with a small group first, using a sandbox organisation if you have one.
And expect the credential authorisation problem again, since linked identities are the prerequisite for credential authorisation. Every token and key affected by the first rollout is affected again.
Under EMU the constraints are tighter still. GitHub documents that using “Okta and Entra ID for SSO and SCIM (in either order) is explicitly not supported”, so a migration between those two providers under managed users is not a matter of reconfiguration. Verify what is supported before planning.
Common mistakes
Section titled “Common mistakes”Enforcing before measuring the link rate. Every unlinked member is a blocked engineer.
Not warning developers about credential authorisation. The largest avoidable support load.
Recovery codes held by one person. A single point of failure for enterprise access.
Recovery codes stored in GitHub. A complete bypass of the control.
No certificate expiry monitoring. The most common SAML outage.
Testing only the browser path. SSH, tokens and CI all behave differently.
Configuring per organisation. Multiple certificates, multiple drift surfaces.
Enforcing on a Friday or during a release. The blast radius is everybody.
Treating enabled-but-not-enforced as a destination. It provides no enforcement.
Operating it after the rollout
Section titled “Operating it after the rollout”SAML is not finished when it is enforced. Four recurring tasks keep it working.
Monitor the certificate. Sixty-day alert, to a team, verified annually.
Review the recovery codes. Do they work, can the right people reach them, and are those people still here.
Watch for unlinked members. With enforcement on, this should stay at zero. A non-zero value means somebody was added outside the normal flow, which is worth investigating rather than fixing silently.
Review authorised credentials. The token and key list grows, and old entries are standing access. A quarterly look at the oldest ones is enough.
Add SAML events to your alerting. Configuration changes to SAML are among the highest-consequence events in the audit log and among the lowest volume — a change to the identity provider URL or certificate should page somebody, because it is either a planned rotation or an attack.
Include SAML in incident runbooks. The revocation sequence, the recovery code location, and who has authority to use them. Written down before it is needed.
And re-test after every identity provider change. Your IdP team will upgrade, reconfigure and migrate things without necessarily knowing that GitHub depends on them. A quarterly end-to-end test — sign in, clone over SSH, run a CI job — catches what nobody told you about.
Mental model
Section titled “Mental model”SAML makes GitHub access contingent on your identity provider, which is exactly what you want and exactly why it is a single point of failure. The configuration is straightforward; the operational discipline — link-rate measurement, credential warnings, certificate monitoring and recovery code handling — is what determines whether it is a control or an incident.
What you learned
Section titled “What you learned”- SAML SSO controls access to organisation resources, in three states: disabled, enabled, enforced
- The login period is generally 24 hours, so re-authentication is roughly daily
- Enabled-but-not-enforced is the correct rollout state, used to drive the link rate before enforcing
- Classic tokens and SSH keys need separate authorisation; fine-grained tokens authorise at creation
- A linked external identity is a prerequisite for authorising any credential
- A revoked SSH key authorisation cannot be reinstated for the same key
- Certificate expiry causes a gradual, full-enterprise authentication outage
- Recovery codes are the only route back and must be held securely by more than one person
- The member SAML access view showing identity, sessions and credentials is the key diagnostic screen
Exercise
Section titled “Exercise”Use an enterprise you administer, or reason from documentation.
-
Determine your current enforcement state. Predict: enabled, or enforced?
-
Find the link rate: members with a linked identity versus total members.
-
Locate your recovery codes. Predict: could you find them in under five minutes, and does more than one person have access?
-
Find your IdP certificate’s expiry date. Is there an alert configured?
-
For one member, open their SAML access view. Count their authorised credentials.
-
Count authorised classic personal access tokens across the enterprise. Find the oldest.
-
Write the developer notice you would publish before enforcing: what stops working, how to fix it, who to ask.
-
List every non-browser path that must be tested before enforcement.