Configuring Kerberos SSO

Single sign-on (SSO) allows a user to automatically gain access to multiple applications and services once their sign-in credentials have been authenticated. Authenticated users are able to bypass the CloudBees CD/RO sign-in screen when they want to take action in CloudBees CD/RO.

Kerberos SSO is a network authentication protocol that works on the basis of tickets that 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.

Looking for SAML SSO information instead? See Configuring SAML SSO.

In summary, these are major steps to configure Kerberos SSO at your site. Select each one for a detailed breakdown.

Before starting, review Kerberos SSO prerequisites.

Kerberos SSO prerequisites

Before you configure Kerveros SSO, 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 CD/RO. A valid Kerberos configuration file, 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. See Kerberos configuration file for details.

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

  • Each server in the CloudBees CD/RO ecosystem must have its ipaddress, hostname and FQDN resolvable.

Kerberos SSO components

Identify the following components at your enterprise before proceeding. These components are used in the various stages of Kerberos SSO configuration

Component Example value

Active Directory domain

example.com

Kerberos realm

example.com

CloudBees CD/RO web server service

efwebserver.example.com

CloudBees CD/RO web server service principal name

HTTP/efwebserver.example.com@example.com

CloudBees CD/RO web server service account

efweb-krbsvc

CloudBees CD/RO server service

efserver.example.com

CloudBees CD/RO server service principal name

HTTP/efserver.example.com@example.com

CloudBees CD/RO server service account

efserver-krbsvc

End-user account

bob

Kerberos Key Distribution Center (KDC) configuration

Before setting up your CloudBees CD/RO servers and web servers with SSO, Kerberos principals required for authentication must be configured with Active Directory. Administrator privileges are needed for the following procedures.

In summary, the steps include:

Creating a user account

To create a user account in the Active Directory:

  1. Log into the domain controller as administrator.

  2. Create an account with a username (for example, bob) and password.

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

Creating service accounts

Service accounts are used to run the services for the CloudBees CD/RO server and the CloudBees CD/RO web server. You can run both services under the same account. See Kerberos SSO components for examples.

To set up these service accounts:

  1. Login to the domain controller as administrator.

  2. Create a user with a username and a password.

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

Mapping the user accounts to service principal names

Kerberos service principals for the CloudBees CD/RO web server and CloudBees CD/RO 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

  1. Log into the domain controller as administrator.

  2. Open the Windows Active Directory Users and Computers tool.

  3. Find the user account that you created (for example, efweb-krbsvc ).

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

  5. Select the servicePrincipalName attribute.

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

  7. Repeat these steps for the CloudBees CD/RO server to associate the user account efserver-krbsvc to the service principal HTTP/efserver.example.com@example.com.

  8. Enable the web and CloudBees CD/RO servers to require AES256-SHA1: make sure the AD service account to be used has the account option, The account supports Kerberos AES 256 bit encryption, set as mentioned in https://blogs.msdn.microsoft.com/openspecification/2011/05/30/windows-configurations-for-kerberos-supported-encryption-type/.

    The configuration related to AES256-only encryption must be performed for each AD domain account that has mapping to web/CloudBees CD/RO service principal name (SPN).

    This sets msDS-SupportedEncryptionTypes to 16.

  9. Verify msDS-SupportedEncryptionTypes is 16. Enter the command:

    get-aduser efwebserver -property msDS-SupportedEncryptionTypes

    Output should look something like the following:

    DistinguishedName : CN=efwebserver,OU=Users,OU=CORP,DC=corp,DC=example,DC=com
    Enabled : True
    GivenName : efwebserver
    msDS-SupportedEncryptionTypes : 16
    Name : efwebserver
    ObjectClass : user
    ObjectGUID : 478cceb3-89f7-4da1-9b71-53e3ed0c1202
    SamAccountName : efwebserver
    SID : S-1-5-21-3236939686-3975733939-3482413644-16648
    Surname :
    UserPrincipalName : HTTP/ip-10-0-129-123.corp.example.com@CORP.EXAMPLE.COM

Using the setspn utility

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

  1. 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
  2. Associate the Service Principal Name for the CloudBees CD/RO server to its service account by entering:

    C:\ setspn -s `HTTP/efserver.example.com@example.com` efserver-krbsvc

Generating a keytab file

Keytab files need to be generated for services provided by CloudBees CD/RO server and the CloudBees CD/RO web server. It 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.

If your test environment has two virtual IP (VIP) FQDNs—​one for the web server load balancer and another for the CloudBees CD/RO server load balancer—​create two AD accounts to generate the two keytabs: one for the web server service principal name (SPN) and one for CloudBees CD/RO Server SPN. Each SPN must be mapped to its own domain account.

If web and CloudBees CD/RO servers are located on the same machine or located on different machines but they are accessed through one load balancer, because they have the same SPN (with load balancer FQDN), only one domain account is needed and hence the same keytab for both web and CloudBees CD/RO servers.

To generate keytab files for the CloudBees CD/RO server and CloudBees CD/RO web server:

  • CloudBees CD/RO server: Create a keytab file for the CloudBees CD/RO server that stores 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 the domain controller node, with administrative privileges:

    ktpass -princ HTTP/efserver.example.com@EXAMPLE.COM  -mapuser EXAMPLE\efserver-krbsvc
     -pass password  +setpass +setupn +dumpsalt -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -out efserver.keytab

    The password must match the one used to create the service account for the CloudBees CD/RO server.

  • Web server: Create a keytab file for the CloudBees CD/RO web server that stores 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:

    ktpass -princ HTTP/efwebserver.example.com@EXAMPLE.COM  -mapuser EXAMPLE\efserver-krbsvc
     -pass password  +setpass +setupn +dumpsalt -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -out efwebserver.keytab

    The password must match the one used to create the service account for the CloudBees CD/RO web server.

  • Output from ktpass should look similar to the following:

    Targeting domain controller: WIN-MUCJF62AKDL.corp.example.com
    Using legacy password setting method
    Successfully mapped HTTP/ip-10-0-129-123.corp.example.com to efwebserver.
    Building salt with principalname HTTP/ip-10-0-129-123.corp.example.com and domain CORP.EXAMPLE.COM (encryption type 18).
    ..
    Hashing password with salt "CORP.EXAMPLE.COMHTTPip-10-0-129-123.corp.example.com".
    Key created.
    Output keytab to efwebserver.keytab:
    Keytab version: 0x502
    keysize 105 HTTP/ip-10-0-129-123.corp.example.com@CORP.EXAMPLE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 4 etype 0x12 (AES256-
    SHA1) keylength 32 (0x30ac141c0204cfd497d2ee6ae23e59b788d5100c44062414d880e6179eb06b94)

Of note:

  • The account used to run the web and CloudBees CD/RO servers can be completely independent from domain account that is used to map the SPN. CloudBees CD/RO servers can use a local account on host machines or an AD domain account that is different from the one used to create the keytab. So, the RUN_AS_USER need not match the AD domain account that is used as a value for -mapuser parameter to ktpass, used to generate the keytab.

  • The SPN must match the UPN. The option +setpass is required to update the account. Without it the changes to the UPN are not recognized.

  • Use the correct -mapuser and -pass parameter values of the service account for the CloudBees CD/RO server.

Verifying the keytab file

Use this procedure to verify the keytab has the correct SPN, enctype, and kvno.

  • Linux

    /opt/electriccloud/electriccommander/apache/bin/klist -e -k -K -t \
        /opt/electriccloud/electriccommander/apache/conf/efserver.keytab

    Output from this command is similar to the following:

    Keytab name: FILE:/home/ec2-user/mykeytabs/efserver.keytab
    KVNO Timestamp Principal
    ---- ------------------- ------------------------------------------------------
    4 01/01/1970 00:00:00 HTTP/ip-10-0-134-109.corp.example.com@CORP.EXAMPLE.COM (aes256-cts-hmac-sha1-96)
    (0x6d4b8a4c98bb0b3b1cf7d79b5f2105c704f91995b7704e803d02315f18a17bde)
  • Windows

    "C:\Program Files\Electric Cloud\ElectricCommander\jre\bin\ktab" \
                     -l -e -t -k efserver.keytab

    Verify that kvno in the keytab matches the output from the msDS-KeyVersionNumber value in the powershell command:

    get-aduser efserver -property msDS-KeyVersionNumber

    Here is sample output:

    DistinguishedName : CN=efserver,OU=Users,OU=CORP,DC=corp,DC=example,DC=com
    Enabled : True
    GivenName : efserver
    msDS-KeyVersionNumber : 4
    Name : efserver
    ObjectClass : user
    ObjectGUID : d9b49f30-2643-45d0-8b92-f8797e4f38ad
    SamAccountName : efserver
    SID : S-1-5-21-3236939686-3975733939-3482413644-16649
    Surname :
    UserPrincipalName : HTTP/ip-10-0-134-109.corp.example.com@CORP.EXAMPLE.COM

Testing authentication and ticket granting

  1. Login to the server hosting the CloudBees CD/RO web server as the web server service account.

  2. Run the following commands commands:

    export KRB5_TRACE=/tmp/debug.txt \
    /opt/electriccloud/electriccommander/apache/bin/kinit -k -t \
       /opt/electriccloud/electriccommander/apache/conf/efwebserver.keytab \
       <web server Service Principal Name>

    For example:

    export KRB5_TRACE=/tmp/debug.txt
    /opt/electriccloud/electriccommander/apache/bin/kinit -k -t \
       /opt/electriccloud/electriccommander/apache/conf/efwebserver.keytab \
       HTTP/ip-10-0-134-109.corp.example.com@CORP.EXAMPLE.COM

    If the keytab exists and the host or service principal has been correctly added to it then kinit returns immediately, without requesting a password.

    The authentication is successful if a ticket-granting ticket is cached in a /tmp/krb5* file, for example: /tmp/krb5cc_1000. This way you can verify that the account is not locked.

  3. When the above kinit is successful, list the tickets in the Credential Cache using:

    /opt/electriccloud/electriccommander/apache/bin/klist

    You should see output similar to the following

Ticket cache: FILE:/tmp/krb5cc_1000
Default principal: HTTP/ip-10-0-134-109.corp.example.com@CORP.EXAMPLE.COM
Valid starting Expires Service principal
08/12/2020 01:36:31 08/12/2020 11:36:31 krbtgt/CORP.EXAMPLE.COM@CORP.EXAMPLE.COM
renew until 08/13/2020 01:36:13
Troubleshooting

If kinit returns either of these errors:

`kinit: Password incorrect`
`kinit: Preauthentication failed while getting initial credentials`

Then as mentioned in https://access.redhat.com/sites/default/files/attachments/rhel6_samba_server_in_ad_domain_deployment_guide.pdf and https://www.usqcd.org/fnal/troubleshooting.html:

  • The current web server service account password in AD may not match the one used when generating the keytab. This means you may not have used the +setpass and +setupn options to set the password in the ktpass -princ command used to generate the keytab.

  • There may be a problem with your system’s clock. Make sure that the date command returns a time correct to within 5 minutes of your kdc. You can verify this with the ntpdate utility command:

    sudo ntpdate -qu your_domain_name

    If the time difference is within 5 min it is fine (the above example shows the offset was only 0.03 seconds). Otherwise sync it with the kdc using:

    sudo ntpdate your_domain_name

  • Check if you have duplicate SPNs registered in your domain by running the following command on the Domain Controller or the windows machine that can administer AD:

    setspn -x

    If duplicate SPNs are found for the SPN used for CloudBees CD/RO service account, then delete them using the setspn -D command or contact your Domain Administrator to remove the duplicate ones.

Configuring Kerberos constrained delegation

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

Configuration details

  1. Set the delegation for the CloudBees CD/RO web server keytab account user, for example efweb-krbsvc, to Do not trust this user for delegation.

  2. Perform steps as mentioned in https://docs.microsoft.com/en-us/sql/analysis-services/instances/configure-analysis-services-for-kerberos-constrained-delegation?view=sql-server-2017.

    1. On the Delegation tab, select Trust this user for delegation to specified services only, followed by Use Kerberos only.

    2. Click Add to specify which CloudBees CD/RO server services this account is permitted to delegate credentials.

    3. On the Add Services page, click Users or Computers.

    4. On the Select Users or Computer page, enter the CloudBees CD/RO server service keytab user, efserver-krbsvc, in my setup.

    5. Click OK to accept the service account

    6. (Optional) Check to verify they the CloudBees CD/RO web server service keytab account user, efweb-krbsvc, is configured correctly for delegation to the CloudBees CD/RO Service SPN.

  3. Run the query below to discover the users or computers trusted for constrained delegation with the PowerShell ActiveDirectory module:

    Get-ADUser -Filter {(msDS-AllowedToDelegateTo -ne "{}")} \
               -Properties \
                  TrustedForDelegation,\
                  TrustedToAuthForDelegation,ServicePrincipalName,\
                  Description,msDS-AllowedToDelegateTo
    • For the specific CloudBees CD/RO web server service keytab user:

      PS C:\> Get-ADuser <WebServer_Service_keytab _user> \
              -properties * | Select-Object \
                cn,sAMAccountName,servicePrincipalName,\
                userPrincipalName,trustedForDelegation,\
                trustedToAuthForDelegation,\
                msDS-AllowedToDelegateTo,modifyTimeStamp

To enforce constrained delegation, The Active Directory maintains a list of the SPNs of the instances of services to which a service running under a specific account is allowed to delegate, that is, to obtain service tickets that can be used for constrained delegation. This list of SPNs is stored in the new Active Directory msDS-AllowedToDelegateTo attribute of the computer and user accounts on computers that are running Windows Server 2008. When a Windows Server 2008 KDC processes a service ticket request by using the constrained delegation extension, the KDC verifies that the SPN of the target service is included in the list of SPNs in the msDS-AllowedToDelegateTo attribute.

Server configuration

After Kerberos SSO is configured and service accounts and Service Principal Names are created in the Active Directory, you must enable SSO on each CloudBees CD/RO server.

The following procedure is applicable for CloudBees CD/RO web servers, v9.1 and later.

  1. Run the following ecconfigure command to enable Kerberos SSO on each CloudBees CD/RO web server node.

    • Linux:

      sudo ecconfigure --webCopyKeytabFile "/path/to/efwebserver.keytab" --webEnableKerberosConstrainedDelegation true
    • Windows:

      ecconfigure --webCopyKeytabFile "c:/path/to/efwebserver.keytab" --webEnableKerberosConstrainedDelegation true

      This performs the following:

    • Copies the specified keytab file to /opt/electriccloud/electriccommander/apache/conf/efwebserver.keytab on the web server.

    • Configures the CloudBees CD/RO web server for the constrained delegation mode.

    • Restarts the CloudBees CD/RO web server.

  2. Copy the CD server keytab to the CloudBees CD/RO erver nodes.

    • Linux:

      cp efserver.keytab /opt/electriccloud/electriccommander/conf/efserver.keytab
    • Windows:

      C:\ copy efserver.keytab “C:\ProgramData\Electric Cloud\ElectricCommander\conf\efserver.keytab”
      The CloudBees CD/RO server keytab file is hardcoded and has to be efserver.keytab. You cannot use any other filename.
  3. Create the Active Directory Provider in the CloudBees CD/RO server as mentioned in Creating a new Active Directory provider section.

    • Set User Options > User Search filter to:

      (&(|(userPrincipalName={0})(sAMAccountName={0})(sAMAccountName={1}))(objectClass=user)(!(objectClass=computer))(!(userAccountControl:1.2.840.113556.1.4.803:=2)))
      The User Name Attribute can be userPrincipalName or sAMAccountName and has no bearing on the User Search Filter.
  4. Enable Kerberos SSO for CloudBees CD/RO server.

  5. Restart the CloudBees CD/RO server.

  6. Continue with Client configuration.

Kerberos configuration file

Below is a minimal example of a Kerberos configuration file, /etc/krb5.conf, that must be resident on all CloudBees CD/RO servers, web servers, and agents.

[libdefaults]
        default_realm = EXAMPLE.COM
[realms]
        EXAMPLE.COM = {
                kdc = dc.example.com
                admin_server = dc.example.com
                default_domain = example.com
        }
[domain_realm]
        .example.com = EXAMPLE.COM
        example.com = EXAMPLE.COM

where:

  • EXAMPLE.COM: the name of the realm

  • example.com: the domain name

Verifying /etc/krb5.conf

  1. Sign in to the server hosting the CloudBees CD/RO web server as the web server service account user.

  2. Run the /opt/electriccloud/electriccommander/apache/bin/kinit command. Enter the password at the prompt.

Errors like the following indicate the /etc/krb5.conf file needs to be fixed:

  • Kinit: krb5 init_context failed: 22

  • Kinit: krb5_get_init_creds wrong realm

Client configuration

This section specifies how to configure web browsers hosting CloudBees CD/RO web servers in your enterprise. Browsers must be enabled to send Kerberos credential for authentication. CloudBees CD/RO supports the following browsers:

Chrome

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

On MacOS:

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

  1. Enter:

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

  2. Enter:

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

  3. Log out of your user account.

  4. Log back in, and run kinit bob@example.com.

    This generates a Kerberos ticket on your computer.

  5. Confirm by running the klist command.

    The list of Kerberos tickets appears.

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

Internet Explorer

To configure Internet Explorer for Kerberos:

  1. Navigate to Settings > Internet Options > Security and select the Custom Level button

  2. Under User Authentication > Logon, select Automatic logon only in Intranet zone.

  3. Click OK.

  4. On the Security tab, select Local Intranet, and then click Sites.

  5. On the Sites popup window, select all options (this is default).

  6. Click the Advanced button and add the CloudBees CD/RO web server FQDN to your local intranet zone:

  7. Click Add, and then Close.

Firefox

To configure Firefox for Kerberos:

  1. Navigate to the configuration editor.

  2. Click the I accept the risk! button.

    The list of preferences appears.

  3. Double-click the network.negotiate-auth.delegation-uris preference.

    And then enter the value for the CloudBees CD/RO 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.

  4. Double-click the network.negotiate-auth.trusted-uris preference.

    And then enter host or domain names (delimited by commas). Note that you can use a wildcard for domain names by prefixing them with a dot. For example, .example.com. For the CloudBees CD/RO web server FQDN, you can provide the efwebserver.example.com value for this preference.

  5. Click OK, and then close the browser window.

End-User sign in

For information about how end users will sign in to CloudBees CD/RO using Kerveros SSO, see Signing in to CloudBees CD/RO.