Org SAML Protection

A GitHub organization owner can enable SAML protection for their org, which requires members to authenticate via SSO (e.g. Okta) before they are able to access any resources associated with that organization. When SSO/SAML protection is enabled, previously issued OAuth tokens for applications such as CircleCI become invalid for that organization, and future user GitHub authentication to CircleCI without an active SAML session will result in a loss of access to protected orgs.

When CircleCI attempts to fetch the config.yml of a project or read other org resources on behalf of a user, and that user has not authorized access to the SAML-protected org as part of the GitHub OAuth flow (see below), the operation will fail. This can impact UI/API interactions, as well as pipeline creation. In the case of VCS-initiated pipelines, GitHub will show a successful webhook delivery in the repository settings, but CircleCI will not be able to fetch the config and a pipeline will not be created.

Solution: Re-Authentication

The solution to this problem is for the user to revoke their CircleCI credentials in GitHub and then re-authenticate via the login flow (or, for email+password users, by re-connecting their GitHub account in User Settings -> Account Integrations). Follow these steps:

1. Go to your personal OAuth application settings for CircleCI: CircleCI OAuth App 
2. Click “Revoke access” and confirm.
3. Go to https://app.circleci.com and log out if necessary.
4. Log back in to CircleCI via GitHub (), or after logging in via another means (e.g. email+password), re-connect your VCS identity (https://app.circleci.com/settings/user)
   
   1. When prompted, be sure to click “Authorize” for any SAML-protected orgs you need access to
   2. Click “Continue” to be redirected to CircleCI
      

It’s important to note that CircleCI only stores a single OAuth token for each GitHub user, regardless of how many orgs they interact within CircleCI. This means that, if a user regularly interacts with multiple orgs, and does not want to re-authenticate when switching between them, it is recommended that they authorize SAML-protected orgs on every re-authentication to CircleCI via GitHub, including when switching devices. This will prevent access-related problems arising from that user’s actions on either platform, e.g. failure to create CircleCI pipelines based when pushing commits.

Sometimes when you switch to SSO, due to how CircleCI handles permissions, all projects will then be unfollowed, and deploy keys will be deleted. Please follow projects in order to add a deploy key and start building on CircleCI.

If you are an org admin and are interested in some preventative steps or how you can avoid common pitfalls when you set up GitHub SSO, check out this article here.