Configuring single sign-on for CloudBees products and services

6 minute readIdentity management
The account management features described in this topic apply to all CloudBees support and training environments. For more information about managing accounts in other CloudBees products, refer to the documentation for those products.

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

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

The CloudBees identity services, id.cloudbees.com, provides access to licenses, feedback, and app.cloudbees.com. It must be configured for full SAML integration.

This document explains how to add the CloudBees SAML service provider to your IdP.

If you are having trouble, please contact CloudBees Support at support.cloudbees.com.

Requirements

To use these procedures, you must have:

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

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

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

Configuring single sign-on using the wizard

The single sign-on configuration wizard is available for existing CloudBees customers who want to use single sign-on.

During this procedure, you will verify that you own the domain to which you want to connect and add the appropriate XML metadata to connect your identity provider to CloudBees products.

You must be a system administrator to perform this procedure.

To configure single sign-on using the wizard:

  1. Go to app.cloudbees.com.

  2. In the top right of the screen, select your organization.

  3. In the top right of the screen, select Organization settings.

  4. In the left pane, select Single sign-on.

  5. Select Configure SAML SSO.

  6. Enter the name of the domain you want to configure, and then select Next.

    You must own this domain to enable the connection between the domain and CloudBees products.

  7. Select Copy to copy the challenge key.

    Copying the challenge key.

  8. In your DNS or cloud provider, within your DNS settings, create a TXT record and paste the challenge key that you copied in step 7.

    See your DNS or cloud provider’s documentation for information about how to create a TXT record.

  9. Select Verify.

    It may take a few minutes for the DNS settings to propagate. You may need to select Verify more than once.

  10. In Connection name, enter a unique name for this connection between your identity provider and CloudBees products.

  11. Do one of the following to add the required metadata to enable the connection:

    1. Select the icon in Import Metadata XML file.

    2. Locate the identity provider’s XML file that contains the identity ID, sign-on URL, and signing certificate metadata, and paste that XML data into the Or paste the Metadata XML field.

    3. Type the entity ID, sign-on URL, and signing certificate data into the appropriate fields. Note that some identity providers refer to Entity ID as Audience.

      SSO SAML screen

  12. Select Next.

  13. Do one of the following to obtain the XML string that you need to add to your identity provider:

    1. Select the icon in Download XML.

    2. Select Copy next to the Or copy the below and add to your identity provider field.

  14. Add the XML string to your identity provider.

  15. Select Enable SSO to enable single sign-on to be used with CloudBees products.

  16. Select Enable auto provisioning to automatically add users to the organization without sending an email invitation request to join.

    If this is not selected, you must manually invite users.

  17. Select Enable strict mode to restrict access to only users that are listed within your organization. All users must use single sign-on. Any existing usernames/passwords or alternatives, such as Google OAuth, will not be valid.

    Configuring SAML single sign-on

  18. Select Configure.

    Single sign-on is now configured.

Configuring single sign-on manually

The following procedures help you to manually configure single sign-on. If you used the single sign-on wizard to set up SSO for CloudBees, you do not have to perform the following procedures. CloudBees recommends using the wizard.

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.

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

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.

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.

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 id.cloudbees.com SP SAML metadata file

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

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

To download the id.cloudbees.com metadata file:

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

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

Managing teams
Viewing subscriptions