Summary

This article will guide you through the necessary steps and options to configure Bamboo with Microsoft SQL Server using Integrated Authentication and Kerberos on Linux.

Environment

• Bamboo Data Center

• Linux / MacOS

• SQL Server 2017/2019/2022

• Microsoft Active Directory

Prerequisites for configuring Kerberos Authentication

Understand Kerberos

• Before configuring Kerberos authentication, ensure a solid understanding of its mechanisms. Seek guidance from a System Administrator experienced in Kerberos. Adequate privileges on the Key Distribution Center (KDC) and, if applicable, Active Directory or LDAP domain are crucial.

Know the password policies

• Before setting up Kerberos authentication, familiarize yourself with the password policies enforced within your Active Directory or LDAP domain.

Clock synchronization

• The Kerberos protocol is sensitive to time differences, so to avoid potential issues from clock drifts, synchronize all solution components with a reliable time source, preferably via NTP (Network Time Protocol).

Exclusions from this guide

This article does not cover the following areas:

• Installation, configuration, usage and best practices related to SQL Server, and Kerberos on Linux

• Kerberos user basics and command line syntax

• Setup, configuration, and best practices for Active Directory, Key Distribution Center (KDC), LDAP servers, or DNS

• Troubleshooting authentication issues beyond Bamboo's scope

Solution

1. Install SQL Server

Refer to the supported versions listed on the Bamboo Supported Platforms - Microsoft SQL Server page.

2. Create and configure the Bamboo Database

Follow steps 1 and 2 outlined in the documentation: Connect Bamboo to a Microsoft SQL Server database.

3. Register a Service Principal Name (SPN) on your SQL Server service account

Link a Service Principal Name (SPN) to the MSSQL Server service account if it is not available. For example, if the MSSQL JDBC URL is:

jdbc:sqlserver://SQL.example.net:1433;databaseName=bamboo;domain=EXAMPLE;encrypt=true;trustServerCertificate=true;integratedSecurity=true;authenticationScheme=JavaKerberos

The following SPN should be associated with the SQL Server service account on Active Directory:

MSSQLSvc/SQL.example.net:1433

Explore the Microsoft documentation for additional SPN options.

• Microsoft.com - Using Kerberos integrated authentication to connect to SQL Server

4. Choose a Kerberos authentication configuration model

Pre-configured Kerberos keytab

Bamboo can utilize a generated Kerberos keytab file for authentication, enabling the application to start without manual prompts or credential files. While this method avoids hardcoded credentials in a clear-text format, an external process unrelated to Bamboo is necessary to create and maintain the Kerberos keytab. It is also advisable not to use any automatic password rotation mechanisms on the SPNs used within the keytab file as that would set the credentials invalid once a password is changed, requiring a new keytab to be generated and managed and eventually causing an application outage due to invalid credentials. To enable a Keytab to be used, set a custom value to the default_keytab_name property in the customized krb5.conf file configured on the step next below.

Database credentials provided by Bamboo

Bamboo can be configured to control the database's username and password credentials. This approach ensures a seamless Kerberos setup, with Bamboo handling the initial TGT request and any necessary TGT renewals without requiring any external Keytab management. However, modifying Database credentials without a service interruption is not feasible under this model.

5. Configure Kerberos authentication

Create a custom Kerberos configuration file

While the operating system's default /etc/krb5.conf file can be used; it's advisable to create a dedicated file to prevent system administrator modifications that may disrupt Bamboo's authentication.

# Sample configuration - consult your System Administrator for the correct syntax

[libdefaults]
#
# Set default_keytab_file only if using a keytab file, 
# otherwise leave it commented. Alternatively, declare the
# KRB5_KTNAME environment variable before starting Bamboo
#
# default_keytab_name = FILE:/var/atlassian/application-data/bamboo/shared/configuration/bamboo.keytab
 
 default_realm = EXAMPLE.NET
 dns_lookup_realm = true 
 dns_lookup_kdc = true 
 forwardable = true
 udp_preference_limit = 1
 noaddresses = true
 ticket_lifetime = 12h

#
# Optional entries below if 
# dns_lookup_realm and dns_loopup_kdc are true and functional
# Consult your Windows/AD/KDC administrator for optimal configuration
#
[realms]
 EXAMPLE.NET = {
   kdc = AD.EXAMPLE.NET
   admin_server = AD.EXAMPLE.NET
   default_domain = EXAMPLE.NET 
 }

[domain_realm]
 .EXAMPLE.NET = EXAMPLE.NET

If setting a default_keytab_name entry in Bamboo's krb5.conf

Generate a keytab, or seek assistance from the DBA or System Administrator to generate it. Store the file in a Bamboo-managed location such as <bamboo-shared-home>/configuration, ensuring correct file permissions and ownership matching the Bamboo service account.

The keytab should include the MSSQLsvc SPN used in the JDBC URL. Before proceeding, confirm this step with the DBA or System Administrator.

Create the <bamboo-shared-home>/configuration/SQLJDBCDriver.conf file:

SQLJDBCDriver {
  com.sun.security.auth.module.Krb5LoginModule required
    useTicketCache=false
    useKeyTab=true
    storeKey=true;
    principal=<the SPN from the Keytab>
};

If not setting a default_keytab_name entry in Bamboo's krb5.conf

Make sure that Java will not use any keytab set in the operating system’s default location:

Create the <bamboo-shared-home>/configuration/SQLJDBCDriver.conf file:

SQLJDBCDriver {
  com.sun.security.auth.module.Krb5LoginModule required
    useTicketCache=true
    renewTGT=true
    useKeyTab=false;
};

Configure Java system properties to point to the Krb5LoginModule configuration file

Add the following property to <bamboo-install>/bin/setenv.sh’s JVM_SUPPORT_RECOMMENDED_ARGS:

-Djava.security.auth.login.config=<bamboo-shared-home>/configuration/SQLJDBCDriver.conf

Update <bamboo-install>/bin/setent.sh by adding the following entry to JVM_SUPPORT_RECOMMENDED_ARGS:

-Djava.security.krb5.conf=<bamboo-shared-home>/configuration/krb5.conf

Configure the JDBC URL for Kerberos and Integrated Authentication

For existing Bamboo installations, update the <bamboo-home>/bamboo.cfg.xml file and modify the JDBC URL to include Kerberos and Integrated Authentication by changing hibernate.connection.url property:

<property name="hibernate.connection.url">jdbc:sqlserver://<MSSQL_HOST:1433;databaseName=<DB_NAME>;domain=<DOMAIN>;encrypt=true;trustServerCertificate=true;integratedSecurity=true;authenticationScheme=JavaKerberos</property>

Configure the DB credentials in Bamboo

For existing Bamboo installations, validate or update the database credentials in <bamboo-home>/bamboo.cfg.xml:

<property name="hibernate.connection.username">sqlsvc</property>
<property name="hibernate.connection.password">mySuP4rP4ss!</property>

Troubleshooting

To troubleshoot Kerberos authentication, check <bamboo-home>/logs/atlassian-bamboo.log. Add the -Dsun.security.krb5.debug=true property to <bamboo-install>/bin/setenv.sh in JVM_SUPPORT_RECOMMENDED_ARGS if issues persist. Kerberos debug messages will be logged in <bamboo-install>/logs/catalina.out or standard output (/dev/stdout) for Bamboo running in a Docker container.

Remember to remove the Kerberos debug properties from JVM_SUPPORT_RECOMMENDED_ARGS after troubleshooting to prevent log file clutter.

Common Issues

Bamboo typically reports the following error for failed Kerberos interactions:

Caused by: com.microsoft.sqlserver.jdbc.SQLServerException: Cannot login with Kerberos principal sqlsvc, check your credentials. Kerberos Login failed: Integrated authentication failed. ClientConnectionId:d34db33f-e4f7-4a91-afd9-43a095f61953 due to javax.security.auth.login.LoginException (Pre-authentication information was invalid (24))

This generic Kerberos error indicates authentication refusal. To pinpoint the root cause, refer to the error message provided by Bamboo and the timestamp in the Kerberos debug logs, while -Dsun.security.krb5.debug=true.

Password Changes

If using a keytab and a DB credential is rotated, regenerate the keytab or request a new one from the DBA or System Administrator. For non-keytab setups, update Bamboo's configuration file at <bamboo-home>/bamboo.cfg.xml with the new credentials and restart the application.

Expired TGTs (Ticket Granting Tickets)

If an expired Kerberos TGT causes issues, review the Kerberos setup on the Linux host and establish a TGT renewal system as outlined earlier in this article. When Bamboo manages credentials directly, it handles the initial Kerberos initialization and TGT renewals, making direct username and password usage in the application config preferable.

Processes that may interfere with the TGT

Issues have been observed concerning builds triggered by Bamboo running in a Local Agent or on a Remote Agent connecting back to the Bamboo Server over SSH, utilized to generate keytab files and TGTs for external workstations. These builds were carried out using default configurations, leading to the execution of kinit as the Bamboo user account. Consequently, Bamboo's default TGT was overwritten with inaccurate details, resulting in outages due to invalid authentication. While this scenario is rare, it underscores the criticality of configuring Kerberos sensibly. Therefore, it is strongly advised to provide Bamboo with the necessary Database credentials to ensure proper isolation from external disruptions.