Configuring single sign-on with SAML

6 minute readReferenceIdentity management

Security Assertion Markup Language (SAML) 2.0 is a standard for signing users in to applications based on their sessions from another context. This single sign-on (SSO) login standard has significant advantages over logging in using a username/password:

  • No need to type in credentials

  • No need to remember and renew passwords

  • No weak passwords

SAML enables web-based, cross-domain SSO, which helps reduce the administrative overhead of distributing multiple authentication tokens to the user. It uses security tokens containing assertions to pass information about users between:

  • A SAML consumer, such as the CloudBees Software Delivery Automation services.

  • A SAML authority, referred to as an identity provider, such as Okta, OneLogin, SiteMinder, or Active Directory Federation Services (ADFS).

SAML does not require configuration that is specific to CloudBees Software Delivery Automation. However, you must configure CloudBees Software Delivery Automation to enable SAML.

To configure SAML SSO:

Configuring a SAML service provider

To use SAML SSO, you must configure a SAML service provider. In this case, the service provider is the CloudBees CD/RO or CloudBees Analytics application; set it up for the CloudBees CD/RO or CloudBees Analytics server and web server components.

To configure a SAML service provider:

  1. From the CloudBees navigation, select CD/RO or Analytics.

  2. From the CloudBees CD/RO or CloudBees Analytics main menu, select Administration  Configurations  SSO configurations. The Single Sign-On page displays.

  3. From the Edit SSO Configuration list, select Enable SAML SSO.

  4. In the Service provider section, select Add service provider. The Add service provider page displays.

  5. Enter the details for the new service provider as follows:

    Item Description

    Web Server URL

    The web server URL for the service provider host. This is the URL that an identity provider, such as Okta, sends a response after processing the request from CloudBees Software Delivery Automation. In this case, the service provider is the CloudBees CD/RO or CloudBees Analytics application and the URL is for the CloudBees CD/RO or CloudBees Analytics web server. For example, https://<cloudbees-web-server>, without appending /flow or /commander to the URL.

    Entity ID

    Service provider entity ID (usually URI).

    Assertion Consumer Service Endpoint

    Location at the service provider where the SSO tokens are sent. This location accepts <samlp:Response> messages, or SAML artifacts, for the purpose of establishing a session based on an assertion. It refers to an HTTP resource, often virtual, on a website that processes SAML protocol messages and returns a cookie representing the information extracted from the message. For example, https://sp.example.org/CB.sso/SAML2/POST.

    Single Logout Service Endpoint

    URL of the single logout service endpoint for the service provider.

    AuthnRequestsSigned

    Select to include AuthnRequestsSigned="true/false" metadata in descriptor.

    WantAssertionsSigned

    Select to include WantAssertionsSigned="true/false" metadata in descriptor.

    Public Certificate and Private Key

    To configure SAML using SSO, you must specify the service provider’s public certificate and private key. If you do not have a public certificate and private key, you can generate them using the following commands:

    openssl genrsa -out private.key 2048
    
    openssl req -new -x509 -key private.key -out publickey.cer -days 365
    
    openssl pkcs12 -export -out public_privatekey.pfx -inkey private.key -in publickey.cer

    Service Provider Public X.509 certificate (same certificate for signing and encryption)

    The service provider’s public certificate. You must specify the publickey.cer file for the service provider’s public certificate.

    SP Private Key

    The service provider’s private key. You must specify the private.key file for the service provider’s private key.

    Passphrase

    The passphrase used for the service provider’s private key.

    Service Provider Metadata

    Sign Service Provider Metadata

    If selected, sign service provider metadata.

  6. Select Save Changes. The new service provider appears in the list of service providers in the Service Provider section.

Creating a SAML identity provider

You can create one or more SAML identity providers. These include identity providers such as Okta, OneLogin, SiteMinder, or Active Directory Federation Services (ADFS).

To create a SAML identity provider:

  1. From the CloudBees navigation, select CD/RO or Analytics.

  2. From the CloudBees CD/RO or CloudBees Analytics main menu, select Administration  Configurations  SSO configurations. The Single Sign-On page displays.

  3. From the Edit SSO Configuration list, select Enable SAML SSO, if not already enabled. The Identity providers section shows a list of the existing SAML identity provider configurations.

  4. Select Add identity provider in the Identity providers section. The Add identity provider page displays.

  5. Enter the details for the identity provider as follows:

    Item Description

    IDP Name

    Name of the SAML identity provider.

    Enable identity provider

    If selected, this connector is enabled and any previously enabled identity provider is disabled.

    Description

    Comment text describing this object. This is not interpreted at all by CloudBees Software Delivery Automation.

    IDP Metadata XML File

    File name containing metadata for this SAML identity provider. This is provided to you by the identity provider when you configure a CloudBees SAML SSO application on their site. Refer to Example: Configuring an Okta identity provider integration.

  6. Select Save Changes. The new identity provider appears in the list of identity providers in the Identity Provider section.

Example: Configuring an Okta identity provider integration

This section demonstrates how to create a SAML SSO application integration for your CloudBees Software Delivery Automation environment. Steps in this section take place on the Okta platform. These instructions are for example purposes only and may not reflect the current Okta UI. Refer to the Okta documentation for instructions on how to use Okta.

Prerequisites

  • An active Okta account.

  • Your Okta account populated with user names.

  • A SAML SSO service provider configured on your CloudBees Software Delivery Automation server.

Creating the integration

To create the integration:

  1. Sign in to your Okta account and navigate to the Applications dashboard.

  2. Select Create App Integration. The Create a new app integration dialog displays.

  3. Select SAML 2.0 as the Sign-on method, and then select Next. Create SAML Integration displays with the General Settings tab preselected.

  4. Enter general settings for your integration and select Next. The Configure SAML tab activates.

  5. On the Configure SAML tab, enter the following:

    • Single sign on URL: Use the value from the Single sign on URL field from the CloudBees CD/RO or CloudBees Analytics SAML SSO service provider configuration.

    • Audience URI: Use the value from the Audience URI field from the CloudBees CD/RO or CloudBees Analytics SAML SSO service provider configuration.

    • Attribute statements: Create four as follows:

      Name Value

      FirstName

      user.firstName

      LastName

      user.lastName

      Email

      user.email

      Login

      user.login

  6. Select Next.

Download provider metadata

To download the provider metadata:

  1. Navigate to the Applications dashboard on the Okta platform.

  2. Select the application you just created. The application’s settings page displays.

  3. Select Sign On to display the Sign on methods page.

  4. Select Identity Provider metadata. The metadata XML file displays.

  5. Copy and paste it into a file.

    Identity provider metadata
    Figure 1. Identity provider metadata
  6. Enter this file name into the IDP Metadata XML file field of the CloudBees CD/RO or CloudBees Analytics SAML SSO Edit Identity Provider page and select Save Changes.

    IDP Metadata XML file
    Figure 2. IDP Metadata XML file

Configuring automatic registration of SAML users for SSO

You can optionally choose to not configure Directory providers by enabling CloudBees Software Delivery Automation to automatically register users upon authentication by the SSO identity provider.

To configure automatic registration of SAML users for SSO:

  1. From the CloudBees navigation, select CD/RO or Analytics.

  2. From the main menu, select Administration  Server settings  Security settings.

    For the Automation Platform UI, navigate to https://<cloudbees-flow-server>/commander/ and select Administration  Server from the main menu. From the top right corner of the Server page, select Settings.
  3. Set Auto register SSO users to Enabled.

  4. Optionally, you can also set the Group claim SAML attribute delimiter to one appropriate to your environment. The default is comma-based.

Managing access control

The access control functionality in CloudBees Software Delivery Automation determines who can modify the single sign-on configuration settings.

To configure access control:

  1. From the CloudBees navigation, select CD/RO or Analytics.

  2. From the CloudBees CD/RO or CloudBees Analytics main menu, select Administration  Configurations  SSO configurations.

  3. Select Access Control. The Access Control settings display.

  4. Review and change Privileges and Inherited Privileges as needed.

Signing in to CloudBees Software Delivery Automation

To sign in, copy https://<webHostName>/flow/ into a browser window, then enter your CloudBees Software Delivery Automation web host name as the <webHostName>.

If you experience page redirect problems during SSO sign in, you can modify the session.cookie_samesite setting by completing the following steps:

  1. Open the /opt/electriccloud/electriccommander/apache/conf/php.ini file.

  2. Change the session.cookie_samesitesetting value to Lax.

  3. Restart your CloudBees Software Delivery Automation web server.

The sample sign-in page below is SSO-enabled with GSuite and Kerberos SSO. Your page may be enabled with other SSO identity providers, such as Okta.

SSO enabled
Figure 3. SSO enabled

From here, use one of the following methods to sign in:

  • Select Sign in with Google: The credentials are authenticated via the Google identify provider, and if successful, you are redirected to the home page.

  • Select Sign in with Kerberos: This system has additionally been enabled with Kerberos SSO. The credentials are authenticated, and if successful, you are redirected to the home page.

  • Enter a Username and Password for local authentication. Then select Sign in. If successful, you are redirected to the home page.

If you do not already have an active session, you are unable to sign in through the CloudBees Software Delivery Automation server when the CloudBees Software Delivery Automation server is being upgraded. The following message appears on the sign-in screen until the CloudBees Software Delivery Automation server upgrade is complete: “Server is starting. Please wait.”