Configuring Bamboo with Microsoft SQL Server using Integrated authentication and Kerberos on Linux
プラットフォームについて: Data Center - この記事は、Data Center プラットフォームのアトラシアン製品に適用されます。
このナレッジベース記事は製品の Data Center バージョン用に作成されています。Data Center 固有ではない機能の Data Center ナレッジベースは、製品のサーバー バージョンでも動作する可能性はありますが、テストは行われていません。サーバー*製品のサポートは 2024 年 2 月 15 日に終了しました。サーバー製品を利用している場合は、アトラシアンのサーバー製品のサポート終了のお知らせページにて移行オプションをご確認ください。
*Fisheye および Crucible は除く
要約
The instructions on this page are provided "as is". Additional steps beyond those outlined in this Knowledge Base article may be required to achieve successful results on a customer-specific basis. Please refer to the official documentation for instructions and supported technologies for configuring Bamboo and SQL Server authentication. For updates on the official support for MS SQL Server with Kerberos authentication in Bamboo, please check the following Feature Request.
- BAM-25801 - Getting issue details... STATUS
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.
環境
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
ソリューション
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.
4. Choose a Kerberos authentication configuration model
This is a very important step towards the design and implementation of the solution. Read both options below and decide which one fits your environment.
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.
Read the default_keytab_name
instructions in the file below and uncomment it in case a Keytab file usage is decided
# 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
If you are installing Bamboo, provide the JDBC URL when prompted by the installation wizard.
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>
C
onfigure the DB credentials in Bamboo
- This step is only necessary if you are not using a Keytab. The exception is during installation, where dummy credentials are still required but will not be utilized and can be removed later.
- If you are installing Bamboo, provide the credentials as requested by the installation wizard.
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>
トラブルシューティング
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.