Documentation structure for LLMs (llms.txt)
CircleCI Logo

Set up SSO

1 day ago
Cloud
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.

Setup SAML SSO

To set up SAML SSO, you must have the Organization Admin role. For information on roles and permissions, see the Roles and Permissions Overview.

Access Setup Parameters in CircleCI

To begin setting up a SAML SSO connection in your CircleCI organization, follow these steps:

  1. In the CircleCI web app, select your organization.

  2. Select Org in the sidebar.

  3. Select Single sign-on (SSO) from the sidebar.

  4. On the SSO Settings page, select Setup SSO.

  5. Copy the provided Setup Parameters and Allowed iFrame Origin. You will need these to configure your Identity Provider (IdP).

Configure your Identity Provider (IdP)

Next you will configure your IdP. The steps to do this will vary depending on your IdP. For example, if you are using Okta, refer to Okta’s documentation.

  1. Open your IdP and paste the required configuration details (Setup Parameters and Allowed iFrame Origin) retrieved from CircleCI in the previous section to configure your IdP.

    If your IdP requires a logo for the application (for example, Okta), you can download the CircleCI logo from our brand site.

  2. Add https://app.circleci.com to your IdP’s trusted origins for iframe embedding. This is required to validate a user’s active SSO session when they are interacting with an SSO organization in CircleCI.

  3. The IdP will generate the following information, which you will need to copy in order to complete the next section:

    • SSO URL

    • x509 signing certificate

  4. Set up user accounts in your IdP. Your users will be able to access CircleCI through your IdP once they have a CircleCI account that they sign into with an email and password. Users that joined your organization before SSO was set up will retain their assigned roles. New users are given a default role of Organization Viewer.

Complete SSO Setup in CircleCI

To complete setting up a SAML SSO connection in your CircleCI organization:

  1. In the CircleCI web app, select your organization.

  2. Select Org in the sidebar.

  3. Select Single sign-on (SSO) from the sidebar.

  4. Enter the information provided by your IdP in the previous section. For the domain/realm, enter the email domain that your users will use for CircleCI SSO. When ready, select Save credentials.

  5. Copy the provided TXT record and add it to your DNS. Your SSO Connection will be marked as Pending until this step is complete. Adding the TXT record to your DNS allows CircleCI to validate that you are the owner of the domain on which you are setting up SSO.

    CircleCI will periodically poll DNS to check for the required TXT record. Once your DNS is successfully updated, your SSO connection will be marked as Connected, not enforced

  6. Once your SSO Connection is marked as Connected, toggle Enforce SSO for all users on to begin enforcement. Your SSO connection will now be marked as Connected, enforced

    • Existing organization members will be prompted to authenticate with your IdP the next time they attempt to access your CircleCI organization

    • New organization members must be invited to your organization. See the Manage Roles and Permissions page for more information.

    • Users must log into their email/password CircleCI account to authenticate with SSO. See the Sign in to an SSO-Enabled Organization page for more information.

Your organization is now using SSO to grant and deny user access. You can manage user roles by following the steps outlined on theManage Roles and Permissions page.

Stop enforcing SSO

SSO can be disabled for an organization. This will revert an organization to using email and password authentication.

  1. In the CircleCI web app, select your organization.

  2. Select Org in the sidebar.

  3. Select Single sign-on (SSO) from the sidebar.

  4. Toggle Enforce SSO for all users off to disable SSO enforcement.

Delete SSO connection

It is possible to delete an SSO Connection for an organization. This will delete the SSO connection and your organization will no longer require users to be authenticated via SSO. SSO configuration details will permanently be deleted and users will revert to using email and password authentication.