Clarify the effects of SAML SSO settings in Docs

[micimize]

What article on docs.github.com is affected?

• About identity and access management with SAML single sign-on
• Enabling and testing SAML single sign-on for your organization
• Enabling SAML single sign-on for organizations in your enterprise account
• Preparing to enforce SAML single sign-on in your organization

What part(s) of the article would you like to see updated?

In all of these docs, the consequences of "enabling" versus those of "enforcing" are not properly specified, and there are specific sections that actively cause confusion. The fact that Enterprise and Organization level SAML configurations have dramatically different behavior compounds the issue.

In Enabling and testing SAML single sign-on for your organization, the docs state:

If you enable but don't enforce SAML SSO, organization members who choose not to use SAML SSO can still be members of the organization.

The mechanisms for how exactly this works, and how the behavior can be observed by an administrator, should be documented. A paragraph such as:

Users who have not yet linked their SAML provider will see the a banner like the following prompting them to link their account:

After linking their SAML identity, users will not be able access any organization resources without an active SSO session. To see the banner again, for testing purposes or otherwise, go to your user SSO details page within the organization at https://github.com/orgs/{my-enterprise-org}/people/{my-github-username}/sso and press the "revoke" button:

You will now be able to observe resources and go through the authentication flow again.

With details on the differences in configuration between enterprise and org level SAML noted somewhere as well:

Note: Enterprise-level SAML SSO differently from Organization-level SSO. At the Enterprise level, there is only a single "SSO Enabled" state, where all enterprise members must pass through SSO to access resources, but no members are removed from the organization for neglecting to do so.

I'd also recommend tuning the phrasing in Enabling SAML single sign-on for organizations in your enterprise account where the docs refer to "enforcing the setting," to avoid the term "enforce" in a context where its technical sense might be expected.

I linked all articles that I think should should note or link to a more detailed description of the effects of these settings.

Additional information

I'll just say that having more rigorous docs on these features would have saved a lot of overhead and confusion, and that I believe this should be a priority as it will help other users avoid troubleshooting security settings for production systems.

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[janiceilene]

@micimize Thanks so much for opening an issue! I'll triage this for the team to take a look 👀

[janiceilene]

👋 I've been chatting with some folks, if you've had any conversations in the GitHub community or with our awesome support folks, could you link or copy that into this issue. That way, we'll have all of the information as we continue to review this issue. Thanks so much!

[micimize]

Sure – there was a significant amount of discussion in enterprise issue 903169, not all of which is relevant, as a large amount of the discussion was on whether it was possible to access enterprise-level SAML mappings with a GitHub App.

In fact, my support contact also seemed confused about the behavior differences between enterprise and org level SSO. For instance, at the enterprise level, there is no "enabled" vs "enforced" distinction. Relevant excerpts:

While your Enterprise does have SAML SSO enabled, it is not enforced. When it is only enabled, users have the option to ignore the SAML SSO prompts and can log into your enterprise or organizations without it. If you do enforce it, then all your members will be forced to authenticated against SAML SSO and anyone who hasn't will be removed for the organizations and enterprise.

That is all quite helpful! I'm a bit confused when you say that our Enterprise's Members aren't required to have SAML SSO. If I invite an alternate account, I cannot accept the invitation without going through the "Authenticate to Join" SAML flow. Some members do not have their SAML identity linked, but I believe that is because they have never logged in to github.

You could ignore that SAML SSO flow by just going directly to the GitHub organization you were invited to if SAML SSO is only enabled but not enforced. There will be a banner asking, but the resources will be available. This gives the option for the GitHub user to authenticated to the SAML SSO or not. Do note, if at any time SAML SSO is turned to enforced, these members will be removed from the organization.

Is there any way/configuration to add non-SAML mapped users to a SAML-enabled github org?

Since your enterprise is only SAML SSO enabled, that shouldn't be a problem at this time given the method I stated above.

My response:

I think the issue is that there is no difference between SSO being enabled and enforced at the Enterprise level. There's no configuration for it, so as the docs you linked says, "Enterprise owners can also enforce SAML SSO for all organizations." I think we'll have to have some internal conversations on the importance of internal SSO enforcement.

It was in large part because of this confusion that makes me say "how the behavior can be observed by an administrator." In fact, there is a mistake in my copy above, where I direct users to "go to https://github.com/orgs/{my-enterprise-org}/people/{my-github-username}/sso" which is only visible to admins, but that I mistakenly thought would be visible to users for their own username.

[mattpollard]

@micimize 👋🏻 Thanks again for this issue. We appreciate your observations and suggestions!

I'm putting together a small plan to improve this documentation. I'm also communicating with a team at GitHub to suggest changes to the UI copy that might help clarify the difference between the SAML SSO configurations at the organization and enterprise levels.

I'll communicate further here as soon as I know more. Thanks for your patience in the meantime 🙇🏻

[mattpollard]

@micimize, thanks for your patience while we worked on this 🙏🏻 1fdb14f introduces changes to reinforce that enterprise-level SAML SSO involves enforcement across organizations. In the UI itself, we've also clarified the behavior.

I'm reopening this issue to address two more suggestions from your original comment. I'll let you know when those changes are ready! 🙇🏻