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 (Core) subscription can access CloudBees common services like support and training.

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

You need to add two service providers to your IdP: one for CloudBees Portal and one for Auth0.

To use these procedures, you must have:

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

  • Access to console.cloudbees.com. 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.

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 https://console.cloudbees.com.

  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.

      • 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.

    • X.509 Certificate: Input your X.509 certificate (public key) generated by your SAML identity provider.

    • 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.

  8. 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 example.com then all email addresses returned in the NameID must end with example.com, such as user@example.com.

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 console.cloudbees.com.

  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 should 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="https://grandcentral.cloudbees.com">
  <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="https://grandcentral.cloudbees.com/logout"/>
	<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
	<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://grandcentral.cloudbees.com/authenticate/saml/consume?account_name=ORG" index="1"/> (2)
  </md:SPSSODescriptor>
  <md:Organization>
	<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">https://www.cloudbees.com</md:OrganizationURL>
  </md:Organization>
  <md:ContactPerson contactType="support">
	<md:GivenName>CloudBees Support</md:GivenName>
	<md:EmailAddress>support@cloudbees.com</md:EmailAddress>
  </md:ContactPerson>
</md:EntityDescriptor>
1 ORG location showing the organization’s domain name.
2 ORG location showing the organization’s domain name.

Downloading your Auth0 SP SAML metadata file

CloudBees is in the process of switching to use Auth0 for authentication. This step is required in addition to the preceding procedure to handle both new and legacy systems.

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

Your connection name in Auth0 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 Auth0. If your domain is example, then this phrase becomes samlp-example.

To download the Auth0 metadata file:

  1. Copy and paste the URL to a browser window: \\https://id.cloudbees.com/samlp/metadata?connection=YOUR_CONNECTION_NAME

  2. Change YOUR_CONNECTION_NAME to samlp-<domain>, replacing <domain> with 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">
            	<ds:KeyInfo>
                    	<ds:X509Data>
                        	<ds:X509Certificate>
    MIIDETCCAfmgAwIBAgIUZRpDhkNKl5eWtJqk0Bu1BgTTargwDQYJKoZIhvcNAQEL
    BQAwFjEUMBIGA1UEAwwLc2FtbHRlc3QuaWQwHhcNMTgwODI0MjExNDEwWhcNMzgw
    ODI0MjExNDEwWjAWMRQwEgYDVQQDDAtzYW1sdGVzdC5pZDCCASIwDQYJKoZIhvcN
    AQEBBQADggEPADCCAQoCggEBAJrh9/PcDsiv3UeL8Iv9rf4WfLPxuOm9W6aCntEA
    8l6c1LQ1Zyrz+Xa/40ZgP29ENf3oKKbPCzDcc6zooHMji2fBmgXp6Li3fQUzu7yd
    +nIC2teejijVtrNLjn1WUTwmqjLtuzrKC/ePoZyIRjpoUxyEMJopAd4dJmAcCq/K
    k2eYX9GYRlqvIjLFoGNgy2R4dWwAKwljyh6pdnPUgyO/WjRDrqUBRFrLQJorR2kD
    c4seZUbmpZZfp4MjmWMDgyGM1ZnR0XvNLtYeWAyt0KkSvFoOMjZUeVK/4xR74F8e
    8ToPqLmZEg9ZUx+4z2KjVK00LpdRkH9Uxhh03RQ0FabHW6UCAwEAAaNXMFUwHQYD
    VR0OBBYEFJDbe6uSmYQScxpVJhmt7PsCG4IeMDQGA1UdEQQtMCuCC3NhbWx0ZXN0
    LmlkhhxodHRwczovL3NhbWx0ZXN0LmlkL3NhbWwvaWRwMA0GCSqGSIb3DQEBCwUA
    A4IBAQBNcF3zkw/g51q26uxgyuy4gQwnSr01Mhvix3Dj/Gak4tc4XwvxUdLQq+jC
    cxr2Pie96klWhY/v/JiHDU2FJo9/VWxmc/YOk83whvNd7mWaNMUsX3xGv6AlZtCO
    L3JhCpHjiN+kBcMgS5jrtGgV1Lz3/1zpGxykdvS0B4sPnFOcaCwHe2B9SOCWbDAN
    JXpTjz1DmJO4ImyWPJpN1xsYKtm67Pefxmn0ax0uE2uuzq25h0xbTkqIQgJzyoE/
    DPkBFK1vDkMfAW11dQ0BXatEnW7Gtkc0lh2/PIbHWj4AzxYMyBf5Gy6HSVOftwjC
    voQR2qr2xJBixsg+MIORKtmKHLfU
                        	</ds:X509Certificate>
                    	</ds:X509Data>
            	</ds:KeyInfo>
    
        	</KeyDescriptor>

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