Single sign-on (SSO) overview
| SAML single sign-on for CircleCI is available for Scale Plan customers. See Prerequisites and Limitations for further details. Submit feedback on our Ideas board. |
Single sign-on (SSO) for CircleCI allows organization administrators to control access for their CircleCI organization using an Identity Provider (IdP).
Introduction
Single sign-on (SSO) is a form of authentication, which enables users of an application to authenticate once using an Identity Provider (IdP). The IdP authenticates the user and, based on their permissions, allows them to access applications managed by the organization using a single session.
SSO for CircleCI allows organization administrators to control access for their CircleCI organization using an IdP. CircleCI SSO makes use of the Security Assertion Markup Language (SAML) 2.0 protocol to perform authentication.
How SSO works at CircleCI
When a CircleCI organization has SSO enabled, note the following:
-
Users need to authenticate using the IdP in order to access the organization’s resources in CircleCI.
-
If a user tries to access the CircleCI org’s resources without authenticating using the IdP, they will be redirected to the IdP to authenticate.
-
When a user’s session expires, they will no longer be able to access the organization’s resources in CircleCI and will be prompted to re-authenticate.
-
The length of a user’s session is configured in the organization’s IdP.
Benefits of using SSO
Using SSO for authentication can result in improved security and user experience.
For organization administrators and owners: SSO with an IdP allows the standardization of user management for an organization, across controlled applications (such as CircleCI). Standardizing user management can simplify the process of managing users by centralising common tasks, for example:
-
Adding and deleting users.
-
Managing user permissions.
-
Controlling allowed session length.
For a member of an organization using SSO for authentication: The process of authentication to access applications is simplified. Rather than authenticating separately for each application, SAML SSO enables the user to confirm their identity once with an IdP and that authentication is communicated to the applications (such as CircleCI) that the user has access to. The user may then access these applications for the duration of their session.
Limitations
SSO for CircleCI currently has the following limitations:
-
SSO for CircleCI is supported for organizations using integrations through GitHub App, GitLab, and Bitbucket Data Center. SSO is not supported for organizations that integrate their code through the GitHub OAuth app or Bitbucket Cloud. See the VCS integration overview for more information on integration.
-
SSO requires all users to log into CircleCI with an email and password before authenticating with SSO into an organization. The email used to log in to CircleCI does not need to match the email used to authenticate with the IdP.
-
CircleCI supports SSO using one domain per organization.
-
Personal API tokens will not work against your organization after SSO is enabled. As a result the following features are unavailable when using SSO:
-
The CircleCI VS Code plugin will not work against your organization after SSO is enabled.
-
The CircleCI CLI will not work against your organization after SSO is enabled.
-
API v2 endpoints will not be accessible for your organization after SSO is enabled.
-
Config policies will not be usable/enforcable for your organization after SSO is enabled.
-