Configuring support and training access using single sign-on with CloudBees

This document explains how to configure single sign-on (SSO) with CloudBees so users with a CloudBees CI subscription can access CloudBees common services like support and training. This document doesn’t cover the setup of single sign-on (SSO) for specific products like CloudBees Feature Management.

As a CloudBees customer, you can set up the authentication for hosted services using SSO with a SAML-based identity provider (SAML IdP).

CloudBees is in the process of switching to use for authentication. Both and must be configured for full SAML integration.

This document explains how to add two CloudBees SAML service providers, or apps, to your IdP:

  •, CloudBees’ SAML system that provides access to support, training, and uploads.

  •, CloudBees' new platform that provides access to licenses, feedback, and


To use these procedures, you must have:

  • Administrator privileges on your systems and for your CloudBees organization.

  • Access to Contact your CloudBees Success Manager (CSM) for access.

  • A CloudBees CI (Core) subscription.

You must have an organization already set up in CloudBees Portal to complete this procedure. To set up your organization, contact your CSM.

Single sign-on setup overview

The diagram below provides an overview of how to set up SSO with SAML to access CloudBees services. Like the procedure, the diagram has two sections: creating the SAML connection (green block) and updating IdP to integrate with CloudBees (blue block).

Steps that can be done simultaneously are represented in parallel rows in the diagram. However, you need to create the SAML connection before updating your IdP integration with CloudBees. The first procedure results in a metadata file that provides information to update the IdP configuration.

Steps to setup SSO with SAML
Figure 1. SSO SAML setup flow

Creating your SAML connection

  1. As an administrator of your CloudBees organization, sign in to

  2. Select Org on the left.

  3. Select SAML SSO.

  4. Fill in the form using the information below:

    SSO SAML screen
    • Login URL: The endpoint of your SAML Identity Provider or Login redirect URL from the IdP metadata SingleSignOnService field:

    • Provision user: Select True if you want individuals signing in using your IdP to be added as new users to your CloudBees organization.

      • If this is unchecked, users who sign in with a matching email address are not saved in CloudBees’ systems.

      • If this is checked, users who sign in with a matching email address are saved in CloudBees' systems and automatically added to your organization.

    • X.509 Certificate: Input your X.509 certificate (public key) generated by your SAML identity provider. The same certificate must be used on the IdP side for both applications and

    • Email domains: Specify the comma-separated list of domains for which the SAML sign-in process should be triggered.

      Each domain must have a DNS TXT record in the format of cloudbees-domain-verification:0123456789abcdef0123456789abcdef01234567 for verification of domain ownership. See step 6 below. Your network administrator must update the DNS settings to include the above DNS TXT record.
  5. Select Create.

    If you receive an error, verify that your certificate is copied and created correctly.
  6. Verify shows the validation key in the format cloudbees-domain-verification:0123456789abcdef0123456789abcdef01234567. Add this key as a DNS TXT record.

  7. After the DNS TXT record has been updated and propagated, select Retry or Verify to validate the domain ownership. There may be as much as a 24-hour delay between record creation and validation with CloudBees.

If domain ownership has been validated, you are all set to use the SAML sign-in process and your SAML configuration should show Certificate Fingerprint instead of the actual X.509 certificate.

Completed SSO SAML screen

Updating your IdP to integrate with CloudBees

Multiple IdPs support SAML 2.0 and their setup is specific to each of them. Refer to Common IdP setup guides for instructions for some of these providers.

CloudBees supports any valid IdP. CloudBees is the Service Provider (SP) in the SAML setup. The SP redirects the sign-in to the identity provider, or IdP. You must configure IdP to allow CloudBees.

Common IdP setup guides

This list links to documentation for commonly used IdPs:

Required information from the CloudBees metadata file

From the portal, you can:

  • Download an XML file of your SAML metadata.

  • Review the settings required for your IdP, if you can not use the XML metadata.

The important settings in the SP metadata file are:

  • Issuer/Entity ID

  • Assertion Consumer Service

  • NameID

  • Logout URL

The NameID must match the entered domains. For example, if your domain is then all email addresses returned in the NameID must end with, such as

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

To match profiles, the email address that the user signs in with and the email address returned by NameID must match the user’s entry in CloudBees' system.

Downloading your CloudBees SP SAML metadata file

You can only view the CloudBees metadata file after you have saved the SAML connection in CloudBees Portal. This connection was created in Creating your SAML connection.

  1. Sign in to

  2. After creating your SAML SSO configuration, close the Configure SAML Single Sign On dialog and reopen it to see the Download CloudBees SAML Metadata button.

  3. Select Download CloudBees SAML Metadata.

Your metadata file export will resemble the example file below. The word ORG shows the location of your organization’s domain name.

<?xml version="1.0" encoding="UTF-8"?>
<!-- This is SAML metadata supplied by CloudBees for ORG (revision 2) --> (1)
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" validUntil="2018-08-19T07:09:59Z" cacheDuration="PT1440M" entityID="">
  <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
	<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location=""/>
	<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="" index="1"/> (2)
	<md:OrganizationName xml:lang="en-US">cloudbees</md:OrganizationName>
	<md:OrganizationDisplayName xml:lang="en-US">CloudBees, Inc.</md:OrganizationDisplayName>
	<md:OrganizationURL xml:lang="en-US"></md:OrganizationURL>
  <md:ContactPerson contactType="support">
	<md:GivenName>CloudBees Support</md:GivenName>
1 ORG location showing the organization’s domain name.
2 ORG location showing the organization’s domain name.

Downloading your CloudBees SP SAML metadata file

To finalize your configuration, you need to add `’s SP metadata to your IdP. This is your new authentication system.

Your connection name in uses the format: samlp-<domain>, where <domain> is replaced with the domain name you used in CloudBees Portal. This samlp-<domain> phrase is used to create your connection URL for If your domain is example, then this phrase becomes samlp-example.

To download the metadata file:

  1. Copy and paste the URL to a browser window:

  2. Change <domain> to your organization’s domain used in CloudBees Portal.

  3. Press enter once the URL is complete.

  4. Save the file when prompted.

Appendix: Parsing your IdP’s metadata file

You need two pieces of information from your IdP’s XML metadata file to complete the procedure Creating your SAML connection:

  • Login URL

  • X.509 certificate

Locating your Login URL

To identify the Login URL:

  1. Open the downloaded XML metadata file.

  2. Locate the endpoint of your SAML Identity Provider or Login redirect URL from the IdP metadata SingleSignOnService field.

     <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="<LOGIN URL>"/>
  3. Copy the URL where <LOGIN URL> is displayed in the line above.

  4. Enter your Login URL from the Location in the field for Login URL in Creating your SAML connection.

Locating your X.509 certificate

When you use the procedure Creating your SAML connection, you need the X.509 encryption certificate.

To locate the certificate:

  1. View the metadata file downloaded from your IdP.

  2. Locate the tag <KeyDescriptor use="encryption"> or the keyword KeyDescriptor.

  3. The encryption certificate is located between the tags <ds:X509Certificate> and <ds:X509Certificate>. Copy the certificate.

        	<KeyDescriptor use="encryption">

The certificate is used in the X.509 Certificate field in Creating your SAML connection.