Issue

As a CloudBees customer you want to setup the authentication for hosted services using SSO with a SAML based identity provider (SAML IdP).

Environment

• CloudBees GrandCentral
• CloudBees Console
• Training portal

The SAML integration requires at the minimum an Enterprise level subscription to a CloudBees service/product.

Resolution

How to setup the Identity Provider?

There are various Identity Providers that support SAML 2.0 and their setup is specific to each of them.

You can review the required configuration for your SAML IdP using the CloudBees Console.

From the Console you can

• download an XML SAML metadata file for your IdP
• review the settings required for your IdP (if you can not use the XML metadata)

The important settings are

• Entity Id
• Consumer Service Endpoint
• Logout Endpoint

User Provisioning

Please ensure that your IdP sends the user’s canonical email address as the NameID, you should also return the first_name and last_name attributes with the user’s given name and family name respectively.

CloudBees SAML Revision

Note that CloudBees SAML Revision refers to the specific settings CloudBees uses with your IdP. CloudBees made a change in late 2018 to improve the consistency of our environment, resulting in new v2 settings that are not backward compatible with v1.

The required configuration settings will differ depending on the revision of our configuration that is in use - please use the settings provided in the XML metadata or in the Console (they are consistent between the two formats)

Common IdP setup guides

You’ll find more documentation below about SAML 2.0 IdPs and their integration with CloudBees:

• SAML 2.0 for CloudBees with OKTA
• SAML 2.0 for CloudBees with SecureAuth
• SAML 2.0 for CloudBees with OneLogin
• SAML 2.0 for CloudBees with SSOEasy

How to setup an organization with CloudBees?

1/ As an administrator of your CloudBees organization log into https://console.cloudbees.com.

2/ Click on the Organization button on the left.

3/ Click on SAML SSO button (on the right)

4/ Fill in the details as below

• Login URL: The endpoint of your SAML Identity Provider.
• Provision user: Select true if you want visitors (non existent users) with an email address matching your Email domains to be added as new users to your CloudBees organization, this is in accordance with this SAML setup.
• X.509 Certificate: Input your x509 certificate (public key) generated by your SAML identity provider.
• Email domains: Specify the comma separated list of domains for which SAML login process should be triggered.
• Note: each domain will need to have a TXT record in the format of cloudbees-domain-verification:0123456789abcdef0123456789abcdef01234567 for verification of domain ownership (See step 6 below)

5/ Click Create button

6/ If all goes well you will see a Retry button showing the validation key in the format cloudbees-domain-verification:0123456789abcdef0123456789abcdef01234567 this key will need to added as DNS TXT record.

7/ After the DNS TXT record with above mentioned key has been added click on Retry button, this will validate the domain ownership. Note: there may be an up to 24 hour delay between your record being created and it validating with CloudBees.

8/ If domain ownership has been validated you are all set to use SAML Login process and your SAML configuration should show Certificate Fingerprint instead of the actual X509 certificate.