Configuring Single Sign-On

Single sign-on (SSO) allows a user to sign on with one set of credentials and gain access to multiple applications and services. SSO increases security and provides a better user experience for customers, employees, and partners by reducing the number of required accounts and passwords and providing simpler access to all the applications and services they need.

You can integrate CloudBees Flow with enterprise SSO using either Kerberos or Security Assertion Markup Language 2.0 (SAML 2.0), so that users are not presented with the CloudBees Flow sign-in screen when they want to take action in CloudBees Flow. SSO improves the end user experience, so that users do not need to remember multiple credentials or sign in multiple times. SSO also improves overall enterprise security, because most SSO solutions support features such as multifactor authentication and stricter password policies.

SSO setup is recommended for occasional CloudBees Flow users (that is, users who do not regularly spend long periods of time in CloudBees Flow). These end users typically use CloudBees Flow to start or check progress of releases, pipelines, or deployments, approve gates or complete manual tasks, look at dashboards, and so on.

Configuring Single Sign-On Using Kerberos

Kerberos is a network authentication protocol that works on the basis of tickets to allow nodes communicating over a nonsecure network to prove their identity to one another in a secure manner. Kerberos provides mutual authentication—both the user and the server verify each other’s identity. Kerberos protocol messages are protected against eavesdropping and replay attacks.

Kerberos builds on symmetric key cryptography and requires a trusted third party, and optionally may use public-key cryptography during certain phases of authentication. Kerberos uses UDP port 88 by default.

Kerberos Single Sign-On Prerequisites

Before you configure single sign-on with Kerberos, make sure that:

Kerberos software is installed and configured on the server and client nodes.
Your system administrator has set up one or more Kerberos Key Distribution Centers (KDCs), and that each KDC is accessible from every node in your environment.
Kerberos client software is installed on all hosts that are involved in Kerberos authentication.

This software is required to communicate with the KDC server but is not included in CloudBees Flow. A valid Kerberos configuration (such as a krb5.conf file) that includes information for how to connect to the KDC, realm, and domain must be provided for the client.

Note that Windows clients have Kerberos authentication built into the authentication process, so there is no need for additional software.

Example Data for Kerberos Configuration

Component	Value
Active Directory domain	example.com
Kerberos realm	example.com
CloudBees Flow web server service	efwebserver.example.com
CloudBees Flow web server Service Principal Name	HTTP/efwebserver.example.com@example.com
CloudBees Flow web server service account	efweb-krbsvc
CloudBees Flow server service	efserver.example.com
CloudBees Flow server Service Principal Name	HTTP/efserver.example.com@example.com
CloudBees Flow server service account	efserver-krbsvc
End-user account	bob

Component

Value

Active Directory domain

example.com

Kerberos realm

example.com

CloudBees Flow web server service

efwebserver.example.com

CloudBees Flow web server Service Principal Name

HTTP/efwebserver.example.com@example.com

CloudBees Flow web server service account

efweb-krbsvc

CloudBees Flow server service

efserver.example.com

CloudBees Flow server Service Principal Name

HTTP/efserver.example.com@example.com

CloudBees Flow server service account

efserver-krbsvc

End-user account

bob

Configuring Kerberos with Active Directory

Before setting up your CloudBees Flow servers and CloudBees Flow web servers with single sign-on, Kerberos principals that are required for authentication must be configured with Active Directory. Administrator privileges are needed for the following procedures.

Creating an End-User Account in the Active Directory Domain

To create this account:

Log into the domain controller as administrator.
Create an account with a username (for example, bob ) and a password.

An organization typically already has its end user set up in Active Directory.

Creating Service Accounts in the Active Directory Domain

Service accounts are used to run the services for the CloudBees Flow server and the CloudBees Flow web server. See Example Data for Kerberos Configuration above. You can run both services under the same account.

To set up these service accounts:

Login to the domain controller as administrator.
Create a user with a username and a password.

Select the User cannot change password and Password never expires check boxes.

Configuring Service Accounts for Kerberos Delegation

Kerberos delegation allows an application (in this case, CloudBees Flow services) to reuse the end-user credentials to access resources hosted on a different server. Delegation is not enabled by default in Active Directory. This means that service accounts for the CloudBees Flow web server and server services need to be set up and trusted for delegation.

To set up Kerberos delegation:

Login to the domain controller as administrator.
Open the Windows Active Directory Users and Computers tool.
Find the service account that you created (for example, efweb-krbsvc ).
Open user properties and navigate to the Delegation tab.
Select the Trust this user for delegation to any service (Kerberos only) option.
Repeat these steps for the other service account that you created (for example, efserver-krbsvc ).

Mapping the User Accounts to Service Principal Names

Kerberos service principals for the CloudBees Flow web server and CloudBees Flow server services need to be created and associated with the service user accounts in Active Directory. This operation can be performed either through the Windows Active Directory Users and Computers administrator tool or through the setspn utility.

Using Windows Active Directory Users and Computers

Log into the domain controller as administrator.
Open the Windows Active Directory Users and Computers tool.
Find the user account that you created (for example, efweb-krbsvc ).
Open user properties and navigate to the Attribute Editor.

If the Attribute Editor does not appear in the UI, open View > Advanced Features and then enable it.
Select the servicePrincipalName attribute.
Enter the value HTTP/efwebserver.example.com@example.com, where efwebserver.example.com is the fully qualified domain name (FQDN) for the web server node.

When a load balancer is used for the web server, this value should be the FQDN of the load balancer.
Repeat these steps for the CloudBees Flow server to associate the user account efserver-krbsvc to the service principal HTTP/efserver.example.com@example.com.

Using the setspn Utility

The setspn utility lets you manipulate Service Principal Names (SPNs) in Active Directory.

Associate the Service Principal Name for the web server to its service account by entering:
```
C:\ setspn -s `HTTP/efwebserver.example.com@example.com` efweb-krbsvc▼
```
Associate the Service Principal Name for the CloudBees Flow server to its service account by entering:
```
C:\ setspn -s `HTTP/efserver.example.com@example.com` efserver-krbsvc▼
```

Generating a Keytab File for CloudBees Flow Services

Keytab files need to be generated for the CloudBees Flow server and CloudBees Flow web server services. A keytab file stores the encryption keys for the Kerberos Services Principals (for example, HTTP/ efwebserver.example.com@example.com for a web server). The service account’s password is used to encrypt the entries in this file.

You can also generate a keytab file by using the Automation Platform UI. For details, see Single Sign-On.

To generate keytab files for the CloudBees Flow server and CloudBees Flow web server services:

Create a keytab file for the CloudBees Flow server that will store the credentials or encryption keys for its Service Principal Name ( HTTP/efserver.example.com@example.com ) that is associated with the service account ( efserver-krbsvc ).

To create a keytab file, enter the following ktpass command on domain controller node with administrative privileges:
```
C:\ ktpass -princ HTTP/efserver.example.com@example.com -mapuser EXAMPLE\efserver-krbsvc -pass password -setpass -setupn +dumpsalt -crypto all -ptype KRB5_NT_PRINCIPAL -out efserver.keytab▼
```
The password must match the one used to create the service account for the CloudBees Flow server.
Create a keytab file for the CloudBees Flow web server that will store the credentials or encryption keys for its Service Principal Name ( HTTP/efwebserver.example.com@example.com ) that is associated with the service account ( efweb-krbsvc ).

To create a keytab file, enter the following ktpass command on the domain controller node with administrator privileges:
```
C:\ ktpass -princ HTTP/efwebserver.example.com@example.com -mapuser EXAMPLE\efweb-krbsvc -pass password -setpass -setupn +dumpsalt -crypto all -ptype KRB5_NT_PRINCIPAL -out efwebserver.keytab▼
```
The password must match the one used to create the service account for the CloudBees Flow web server.

Configuring Web Browsers for Single Sign-On

This section shows individual end users how to configure their web browsers for Kerberos. So that users can access server resources that require Kerberos authentication, their browser must be enabled to send Kerberos credentials. CloudBees Flow supports the following browsers:

Google Chrome
Microsoft Internet Explorer
Mozilla Firefox

Configuring Chrome for Kerberos

On Windows:

Chrome on Windows should use Internet Explorer settings. For instructions, see Internet Explorer .

Ensure that the registry on your machine is properly set up. The recommended way to configure a policy on Windows is by using a Group Policy Object (GPO). However, on machines that are joined to an Active Directory domain, policy settings might also be stored in the registry under HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER in the following paths:

Software\Policies\Google\Chrome\AuthServerWhitelist = efwebserver.example.com
Software\Policies\Google\Chrome\AuthNegotiateDelegateWhitelist = efwebserver.example.com

For details, see https://dev.chromium.org/administrators/policy-list-3#AuthServerWhitelist and https://dev.chromium.org/administrators/policy-list-3#AuthNegotiateDelegateWhitelist .

On MacOS:

To configure Chrome for Kerberos on macOS, complete the following steps. The example below is for a user named bob :

Enter:

/usr/bin/defaults write /Users/bob/Library/Preferences/com.google.Chrome.plist AuthNegotiateDelegateWhitelist "efwebserver.example.com"
Enter:

/usr/bin/defaults write /Users/bob/Library/Preferences/com.google.Chrome.plist AuthServerWhitelist "efwebserver.example.com"
Log out of your user account.
Log back in, and run kinit bob@example.com.

This generates a Kerberos ticket on your computer.
Confirm by running the klist command.

The list of Kerberos tickets appears.
Shut down and restart Chrome.

For more information about Chrome setup for Kerberos, see https://www.jamf.com/jamf-nation/discussions/10688/chrome-and-kerberos-single-sign-on .

Following are common problems with Kerberos setup on Chrome on macOS:

SSO sign-in no longer works.

Follow the steps below:
1. Sign out of your user account and sign back in.
2. On macOS, enter kinit bob@example.com and generate a ticket for the krbtgt account again.
3. Ensure that the Kerberos ticket is not expired on your local machine.
  
  On macOS, run the klist command and see the Kerberos ticket expiry information.
SSO does not work on Chrome.

Follow the steps below:
1. Ensure that registry entries are correct as stated above.
2. Ensure that there are no spaces before or after the name of the registry entry AuthNegotiateDelegateWhitelist.

Configuring Internet Explorer for Kerberos

To configure internet Explorer for Kerberos:

Navigate to Settings Internet Options Security and select Custom Level.
Under User Authentication Logon, select Automatic logon only in Intranet zone.
Click OK.
On the Security tab, select Local Intranet, and then Sites.
On the Sites popup window, select all options (this is default).
Select Advanced button and add the CloudBees Flow web server FQDN to your local intranet zone.
Select Add, and then Close.

Configuring Firefox for Kerberos

To configure Firefox for Kerberos:

Navigate to the configuration editor.
Select I accept the risk!. The list of preferences appears.
Double-click the network.negotiate-auth.delegation-uris preference: enter the value for the CloudBees Flow web server FQDN. For example, enter efwebserver.example.com. This preference lists the sites for which the browser may delegate user authorization to the server.

Double-click the network.negotiate-auth.trusted-uris preference: enter host or domain names (delimited by commas).

You can use a wildcard for domain names by prefixing them with a dot. For example, .example.com. For the CloudBees Flow web server FQDN, you can provide the efwebserver.example.com value for this preference.

Select OK, and then close the browser window.

Configuring CloudBees Flow for Single Sign-On in Kerberos

After single sign-on using Kerberos is installed and configured, and service accounts and Service Principal Names are created in Active Directory, you must enable it in CloudBees Flow. For details, see Single Sign-On.

End-User Login Flow for Single Sign-On in Kerberos

For information about how end users will sign in to CloudBees Flow using single sign-on with Kerberos, see Signing in to CloudBees Flow.

Configuring Single Sign-On Using SAML 2.0

SAML 2.0 is an XML-based protocol that uses security tokens containing assertions to pass information about a principal (usually an end user) between a SAML authority, named an Identity Provider (such as Okta or OneLogin) and a SAML consumer (in this case, the CloudBees Flow software), named a Service Provider. SAML 2.0 enables web-based, cross-domain single sign-on (SSO), which helps reduce the administrative overhead of distributing multiple authentication tokens to the user.

SAML does not require configuration that is specific to CloudBees Flow. However, you must configure CloudBees Flow itself to enable SAML, and you should also be aware of how end users will interact with the CloudBees Flow sign-in page when SAML is enabled as mentioned below.

Configuring CloudBees Flow for Single Sign-On in SAML

After single sign-on using SAML is installed and configured, you must enable it in CloudBees Flow. For details, see Single Sign-On.

End-User Sign-In Flow for Single Sign-On in SAML

For information about how end users will sign in to CloudBees Flow using single sign-on in SAML, see Signing in to CloudBees Flow.