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 initiated from the service provider site. CloudBees platform integrates with an IdP provider by linking a CloudBees user with an IdP user. The connection is made using the user’s unique ID (the SAML NameIdFormat), which is required. The default Active Directory setting usually does not include NameIdFormat, so you may have to add it manually.

Perform the following to set up SSO in the CloudBees platform:

Add a domain to the platform.
Verify domain ownership by adding a platform verification code to your domain name system (DNS).
Configure SAML to connect your IdP.
Enable SAML to manage SAML connections.

You must have the Admin role to configure, update, and manage the SAML connection. Use role-based access control to fine-tune who can perform each SSO setup task.

Add a domain

Add a domain to be used for SSO. The domain name must be available (not currently listed in Admin settings Authentication Domains).

To add an available domain name to the platform:

Select Admin settings Authentication to the left of your account name.
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 checked for availability. A green checkmark indicates the name is available.
Select Next to display the verification code.

The domain is listed in Admin settings Authentication Domains with an Unverified status. You are ready to verify domain ownership.

Return later to verify domain ownership, if desired.

Select next to your domain.
Select Verify domain.

Verify domain ownership

To prevent unauthorized use of your domain, confirm ownership by adding the displayed verification code to the DNS records for your domain.

To verify domain ownership:

Sign in to your domain registrar’s website and locate the section for managing DNS records.
Create a new record, formatted as a TXT file, in your DNS.

Figure 1. An example verification code for the DNS is highlighted.
(Optional) If the verification code, as in the example above, is not displayed in the platform, do the following:
1. Go to Admin settings Authentication Domains and select next to your unverified domain.
2. Select Verify domain to display the verification code.
Copy the verification code from the platform and paste it into the DNS TXT file.
Save the updated TXT file.

Select Verify.

It may take some time for the changes to propagate across the DNS provider. Check the propagation progress at dnschecker.org.
The TXT record with the verification code must exist within your DNS for the verification to be successful.

If the domain verification is successful, the Domain status is listed as Verified in Admin settings Authentication Domains, and you are ready to set up a SAML connection.

Return later to configure SAML, if desired.

Select next to your domain.
Select Link connection.

Configure SAML

CloudBees platform SSO uses SAML to provide a streamlined user experience. Use a verified domain name to set up a SAML connection.

Each verified domain can only accommodate a single SAML connection with a given IdP. To create multiple SAML connections, you must either use multiple domains or multiple IdPs.

To configure a SAML SSO connection:

Go to Admin settings Authentication Domains and select a verified domain.
Select next to your unverified domain, and then select Link connection.
Select an existing connection from the options, or select Create new to create a new one.

If you select an existing SSO connection, you overwrite all existing XML information.
Enter a Connection name.
Locate the metadata XML from your IdP.
Use one of the following methods to enter the metadata XML:
1. Select Import metadata XML file, then upload your XML file.
2. Paste the XML from your IdP into Metadata XML.
3. Enter the Entity ID, the Sign-on URL, and the Signing certificate.
Select NEXT. The platform generates the XML information.
Perform either of the following:
1. Select Download XML to download the generated XML file to add to your IdP.
2. Copy the generated XML information and paste it into your IdP.
  
  Refer to instructions specific to your IdP for more information.
Select Close.

The SAML connection for your domain is configured accordingly. You are ready to enable your SAML connection.

Manage the SAML connection

Manage your SAML connections in Admin settings Authentication Connections. Enable your SAML connection by setting the Enabled toggle to On (). You may additionally set Strict mode or Auto-provisioned to be On if desired.

Enabled must be set to On (

) for SAML to be enabled. To use Strict mode or Auto-provisioned, you must also set Enabled to be On.

Table 1. SAML connection management
Connection	Definition
Strict mode	Set Strict mode to On to disable the invite function, so 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	Set Auto-provisioned to On to enable the invite function. New users who log in with an email containing the approved domain are automatically added to your tenant. If disabled, new users must first be manually invited to your tenant.
Enabled	Set Enabled to On to enable 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 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 next to the connection you want to remove.
Select Remove.
Select Next.
Select Save.

The selected SAML connection is removed from the platform.