SAML single sign-on (SSO)

Security Assertion Markup Language (SAML) is a standard for exchanging authentication and authorization data between an identity provider (IdP) and a service provider. SAML is a common single sign-on (SSO) configuration that allows users to sign in to multiple software applications using the same credentials. CloudBees platform uses the SAML 2.0 protocol to implement SSO.

The CloudBees platform SAML authentication is service provider (SP)-initiated. CloudBees platform integrates with an IdP provider by linking a CloudBees user with an IdP user. The connection is made using the SAML’s NameIdFormat, which is required. The default Active Directory setting usually does not include NameIdFormat, so you may have to add it manually.

You must have the Admin role to configure, update, and manage the SAML connection.

Configure SSO

CloudBees platform SSO provides a streamlined user experience allowing users to sign in to CloudBees platform with their existing credentials from another system.

Set up the domain

To configure the domain:

Select ADMIN SETTINGS Authentication at the top of the screen, by your username.
Select DOMAINS at the top left of the screen.
Select CREATE SAML.
Enter a Domain name; for a user with the email user@example.com, the domain name is example.com.

The domain name is searched for within the platform. If it is valid, a green checkmark appears. Otherwise, an error message appears.

If the domain name exists in the platform, it can only be configured if it is unverified. Verified domain names cannot be used in a new SAML configuration.
Select NEXT. The verification code is displayed.

Verify ownership

Verify the ownership of your domain to prevent unauthorized use and confirm ownership.

To add a TXT record containing your verification code to your DNS records for your domain:

Copy your verification code for use in a later step.
Sign in to your domain registrar’s website and locate the section for managing domain name system (DNS) records.
Create a new record, formatted as a TXT file, in your DNS.
Paste the verification code into the TXT file and save it.
It may take some time for the changes to propagate across the DNS provider.

The TXT record with the verification code must exist within your DNS for the verification to be successful.
Select VERIFY to check for your verification code.

If the verification code is not found in the DNS, an error message appears.

Set up the connection

To configure the connection:

(Optional) Modify the default connection name.
Locate the metadata XML from your IdP used to authenticate your users.
Use one of the following three options to enter the metadata XML:
1. Select IMPORT METADATA XML FILE.
2. Enter the Metadata XML manually.
3. Enter the Entity ID, enter the Sign-on URL, and enter the Signing certificate.
Select NEXT.
The configuration for the connection displays.

Refer to instructions specific to your IdP for more information.

The SAML connection for your domain is configured accordingly.

Manage the SAML connection

Toggle on or off any of the following to manage your SAML connection:

Table 1. SAML connection management
Connection	Definition
Strict mode	If enabled, the invite function is not available, and all users to your domain must sign in to the tenant organization via SAML. All users in your tenant must be from that domain.
Auto-provisioned	If enabled, the invite function is available. New users in your domain are automatically added to your tenant. If disabled, new users must first be manually invited to your tenant. All users can use SAML to sign in to your tenant, whether automatically added or manually invited.
Enabled	This function enables SAML, allowing users to sign in to your tenant using SAML. If disabled, users must sign in how they originally signed in to the platform.

Update a SAML configuration

You can change your SAML settings if you are an organization administrator.

To update the SAML configuration:

Select ADMIN SETTINGS Authentication at the top of the screen by your username.
Select CONNECTIONS.
Select the next to the connection you want to update.
Select Edit, and make the desired updates.
Select NEXT.
Select SAVE.

The SAML configuration is updated accordingly.

Remove a SAML connection

You can remove a SAML connection for your tenant organization. A removed SAML connection is completely and irreversibly removed from the CloudBees platform.

To remove a SAML connection:

Select ADMIN SETTINGS Authentication at the top of the screen by your username.
Select CONNECTIONS.
Select the next to the connection you want to remove.
Select Remove.
Select NEXT.
Select SAVE.

The selected SAML connection is removed from the platform.