> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SAML SSO The Bouncer

> Explains GitHub SAML single sign-on, how it delegates authentication to an IdP, risks of enforcing SSO, impacts on tokens/SSH, and rollout and recovery best practices.

SAML single sign-on (SSO) is a foundational feature for enterprise identity on GitHub. Without SAML, your GitHub organization remains an identity silo: engineers must remember separate corporate and GitHub credentials, and revoking access when someone leaves requires manual steps in two systems.

![A slide titled "A Separate Identity Silo" showing a corporate laptop (one login) that has no connection to a GitHub account (a completely different login). The caption reads "One engineer, two identities to remember."](https://mintcdn.com/kodekloud-c4ac6d9a/Ae2SeWV4btujbkSt/images/GitHub-Administration-Certification/Identity-and-Access-Management/SAML-SSO-The-Bouncer/separate-identity-silo-two-logins.jpg?fit=max\&auto=format\&n=Ae2SeWV4btujbkSt\&q=85\&s=5959a622ae7abae9d5925f3910412300)

## How SAML SSO works (an analogy)

Think of SAML like a security checkpoint at a federal building. In this analogy, GitHub is the building. GitHub issues the visitor pass (the SAML session token), but it doesn’t verify identities itself—the identity provider (IdP) does that. Your IdP is the "federal ID office" (for example, [Okta](https://www.okta.com/) or [Azure AD](https://azure.microsoft.com/en-us/services/active-directory/)). When someone tries to enter, the GitHub guard asks the IdP whether the person is cleared.

![A diagram titled "A Checkpoint at a Federal Building" showing a GitHub-styled building with a SAML checkpoint and two people at the entrance. To the right is a "Federal ID Office" that issues IDs via identity providers like Okta and Azure AD.](https://mintcdn.com/kodekloud-c4ac6d9a/Ae2SeWV4btujbkSt/images/GitHub-Administration-Certification/Identity-and-Access-Management/SAML-SSO-The-Bouncer/federal-saml-checkpoint-id-office.jpg?fit=max\&auto=format\&n=Ae2SeWV4btujbkSt\&q=85\&s=bbeb8a0b7333b216a8c678b4d524d137)

The guard does not use its own database; it queries the IdP. The IdP replies “yes, this person is cleared,” and the guard issues a visitor pass (the SAML session) so the person can enter GitHub.

![An illustration showing a guard at a GitHub building checking with an ID Office (your IdP) about a person's clearance. Blue and green arrows show the guard asking "is this person cleared?" and the ID Office replying "yes, cleared."](https://mintcdn.com/kodekloud-c4ac6d9a/Ae2SeWV4btujbkSt/images/GitHub-Administration-Certification/Identity-and-Access-Management/SAML-SSO-The-Bouncer/github-guard-idp-clearance-check.jpg?fit=max\&auto=format\&n=Ae2SeWV4btujbkSt\&q=85\&s=0380264c26ff51267b50e20e2662ef2b)

### Session lifetime

A SAML session is time-limited (commonly 24 hours). After expiry, users must re-authenticate with the IdP to receive a fresh session token.

![The image is a simple diagram titled "Good for 24 Hours" showing a current "Visitor Pass" on the left, a circular "24 hours" timer in the center, and a "New Visitor Pass" on the right. It illustrates that the visitor pass is valid for 24 hours and then expires.](https://mintcdn.com/kodekloud-c4ac6d9a/Ae2SeWV4btujbkSt/images/GitHub-Administration-Certification/Identity-and-Access-Management/SAML-SSO-The-Bouncer/visitor-pass-24-hour-expiry.jpg?fit=max\&auto=format\&n=Ae2SeWV4btujbkSt\&q=85\&s=b6e71ff3a702230a078d20eb67a9b319)

## Availability dependency

Because GitHub defers authentication to your IdP, GitHub’s access becomes partly dependent on the IdP’s availability. If your IdP’s systems (authentication service, MFA provider, phone gates) are down, users cannot obtain a session token—effectively blocking access to the organization.

![An illustrated slide titled "If the ID Office Goes Down" shows several people standing in line blocked by a broken phone connection to an "ID Office" building. A caption/button at the bottom reads "Nobody gets in."](https://mintcdn.com/kodekloud-c4ac6d9a/Ae2SeWV4btujbkSt/images/GitHub-Administration-Certification/Identity-and-Access-Management/SAML-SSO-The-Bouncer/id-office-down-nobody-gets-in.jpg?fit=max\&auto=format\&n=Ae2SeWV4btujbkSt\&q=85\&s=990204506527c9096e5322f44c20c336)

Communicate this dependency clearly to stakeholders: implementing SAML SSO improves security and centralizes identity, but it also couples GitHub access to IdP reliability.

## Enabling vs Enforcing SSO

A common operational pitfall is confusing "enabled" with "enforced." The difference is critical:

| Setting | Behavior | When to use |
| -: | - | - |
| Enabled | SSO is available; users may sign in via SSO or their existing methods. | Use during testing and rollout. |
| Enforced | Every access attempt requires an active SAML session. Existing non-SAML credentials are blocked until authorized. | Use only after thorough testing and communications. |

If you switch to Enforced while your admin account lacks an active IdP session (or while you haven't authorized critical automation credentials), you can lock organization owners and admins out immediately.

![A presentation slide titled "Locking Yourself Out" showing an admin user icon with a "no linked okta session" warning and an organization security dialog requiring SAML single sign-on. A stylized blue door labeled "your own organization" appears on the right.](https://mintcdn.com/kodekloud-c4ac6d9a/Ae2SeWV4btujbkSt/images/GitHub-Administration-Certification/Identity-and-Access-Management/SAML-SSO-The-Bouncer/admin-lockout-no-okta-saml.jpg?fit=max\&auto=format\&n=Ae2SeWV4btujbkSt\&q=85\&s=c2b2678c8bf556c19619db1223996d07)

Always verify an active IdP session for at least one org owner/admin account before switching SSO from enabled to enforced. Enforcing SSO without a valid admin session will lock owners and admins out of GitHub.

GitHub includes a "Test SAML configuration" button you should use to validate your Sign-on URL, Issuer, and certificate. Do not rely on guesswork—test before you enforce.

![A settings screenshot for SAML single sign-on showing empty fields for Sign-on URL and Issuer, a "Test SAML configuration" button with a "Test successful" indicator, a checked "Require SAML single sign-on" option, and a Save button. The slide header reads "Test Before You Enforce."](https://mintcdn.com/kodekloud-c4ac6d9a/Ae2SeWV4btujbkSt/images/GitHub-Administration-Certification/Identity-and-Access-Management/SAML-SSO-The-Bouncer/saml-signon-empty-test-success-enforce.jpg?fit=max\&auto=format\&n=Ae2SeWV4btujbkSt\&q=85\&s=3e751f91b3b309f6d6608de162012d63)

## What breaks immediately when you enforce SSO

When you flip enforcement on, any credentials that are not SAML-authorized for the organization will stop working—even though they still exist. This includes:

* Personal Access Tokens (PATs) used by automation and scripts
* OAuth apps that haven’t been granted organization access
* SSH keys that haven't been explicitly authorized for the organization

![A slide titled "Existing Credentials Stop Working" shows a flowchart where enforcing SAML causes a "Production incident." It highlights that personal access tokens and SSH keys "stopped working" and are "not SAML authorized."](https://mintcdn.com/kodekloud-c4ac6d9a/Ae2SeWV4btujbkSt/images/GitHub-Administration-Certification/Identity-and-Access-Management/SAML-SSO-The-Bouncer/saml-enforcement-production-incident-tokens-ssh.jpg?fit=max\&auto=format\&n=Ae2SeWV4btujbkSt\&q=85\&s=12b6823011ab9c9e50c25a7e2ac536ea)

Typical failure symptoms include 401 responses from the API and SSH permission errors:

```bash theme={null}
$ git fetch origin
remote: Invalid username or token.
fatal: HTTP 401 Unauthorized

$ git push origin main
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.
```

## Recovery: how to restore access

To get things working again after enforcement, users and automation must explicitly authorize their credentials for the organization:

* Personal access tokens and OAuth apps: Users must authorize these tokens/apps for the organization from their GitHub account settings (SAML authorizations).
* SSH keys: Users must open Settings → SSH and GPG keys, locate the key, and click Authorize next to the organization.

Before enforcing SSO, prepare a step-by-step guide for developers and CI owners that explains how to authorize PATs, OAuth apps, and SSH keys. Include exact menu paths and screenshots if possible to reduce help-desk load.

Suggested rollout checklist:

1. Identify owners and ensure at least one owner has an active IdP session linked to their GitHub account.
2. Communicate the change widely (developers, CI/CD teams, release engineers, automation owners).
3. Ask teams to pre-authorize automation tokens and verify CI systems’ credentials.
4. Use the GitHub "Test SAML configuration" button to validate settings.
5. Enforce SSO during a low-impact window and monitor CI and repo access logs.
6. Provide a fast-response channel (Slack, email alias) for immediate troubleshooting.

## Quick reference: common issues and fixes

| Symptom | Likely cause | Fix |
| - | - | - |
| HTTP 401 on API calls | PAT or OAuth app not SAML-authorized | Authorize token/app from the user's account settings |
| SSH permission denied | SSH key not authorized for org | Authorize the SSH key for the organization in Settings → SSH and GPG keys |
| Org owners cannot enter admin settings | No admin with active IdP session | Use an owner with an active session or follow GitHub’s emergency recovery procedures |

## Links and references

* [Configuring SAML single sign-on for your organization (GitHub Docs)](https://docs.github.com/en/organizations/keeping-your-organization-secure/managing-security-for-your-organization/configuring-saml-single-sign-on-for-your-organization)
* [Okta](https://www.okta.com/)
* [Azure Active Directory](https://azure.microsoft.com/en-us/services/active-directory/)

Communicate the trade-offs: SAML SSO strengthens centralized identity and access controls, but it also introduces an availability dependency and requires careful planning—especially before enforcing SSO across an organization.

> [card] [Watch Video](https://learn.kodekloud.com/user/courses/github-administration-certification/module/dcb84798-d0b6-4722-a8f6-fa86e279f82a/lesson/678a485e-eea2-4964-bd9f-970601115451)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.