SSL を使用して Tomcat で Bitbucket Server を保護する

This page is intended for administrators setting up Bitbucket Server for a small team. It describes how to enable HTTPS (HTTP over SSL) access for Tomcat, the webserver distributed with Bitbucket Server, using a self-signed certificate. You should consider doing this, and making secure access mandatory, if Bitbucket Server will be internet-facing and usernames, passwords and other proprietary data may be at risk.

If you are setting up a production instance of Bitbucket Server you should consider using a CA certificate, briefly described below.

Bitbucket Server の実行には、リバース プロキシの背後での Bitbucket Server の実行などの他のネットワーク トポロジ オプションがあります。いくつかの一般的なオプションの概要については、「Bitbucket Server のプロキシと保護」を参照してください。

When Bitbucket Server is set up following the instructions on this page, access to Bitbucket Server is direct, and all communication between the user's browser and Bitbucket Server will be secured using SSL.


Bitbucket_topo_direct_SSL

注意:

  • Bitbucket Server will listen for requests on port 8443. This port can be changed if required.
  • The address with which to access Bitbucket Server, by default, will be https://<computer name>:8443. Change the base URL for Bitbucket Server if required.
  • Any existing links with other applications will need to be reconfigured using this new URL for Bitbucket Server.
  • Bitbucket Server と同じホスト名およびコンテキスト パスで、別のアトラシアン アプリケーション、または Java Web アプリケーションを実行している場合は、Bitbucket Server にコンテキスト パスを設定することができます。
  • ユーザーのコンピューターと Bitbucket Server との間の Git 操作の保護は別途検討する必要があります。「Git への SSH アクセスを有効にする」を参照してください。

Please note that Atlassian Support will refer SSL-related support to the issuing authority for the certificate. The documentation on this page is for reference only.

1. Generate a self-signed certificate

Users may receive a warning that the site is untrusted and have to "accept" the certificate before they can access the site. This usually will only occur the first time they access the site.

The following approach to creating a certificate uses Java's keytool. Other tools for generating certificates are available.

To generate a self-signed certificate:

Log in with the user account that Bitbucket Server will run under, and run the following command:

Windows:

"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA -sigalg SHA256withRSA

Linux, macOS:

$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -sigalg SHA256withRSA

This will create (if it doesn't already exist) a new .keystore file located in the home directory of the user you used to run the keytool command.

If you used the Bitbucket Server installer to install Bitbucket Server as a service on your system, the installer will have created a user account called atlbitbucket. This account is locked (it cannot be used to log in to the system) and doesn't have a home directory. In this case you need to specify a location for the .keystore file using the keystore parameter like this:

Windows:

"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA -sigalg SHA256withRSA -keystore /path/to/keystore/bitbucket.jks

Linux, macOS:

$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -sigalg SHA256withRSA -keystore /path/to/keystore/bitbucket.jks

Note the following:

  • When running the keytool command you will be prompted with: What is your first and last name?
    You must enter the fully qualified hostname of the server running Bitbucket Server. This is the name you would type in your web browser after 'http://' (no port number) to access your Bitbucket Server installation. The qualified host name should match the base URL you have set in Bitbucket Server (without the port number).
  • The keytool utility will also prompt you for two passwords: the keystore password and the key password for Tomcat.
    You must use the same value for both passwords, and the value must be either:
    • "changeit", which is the default value Tomcat expects, or
    • any other value, but you must also specify it in <Bitbucket home directory>/shared/server.xml (see the next section for details)

2. Configure HTTPS in Tomcat

To configure HTTPS in Tomcat:

  1. Edit <Bitbucket home directory>/shared/server.xml and, at the bottom, before the </Service> tag, add this section (or uncomment this if it already exists):

    <Connector port="8443" 
      maxHttpHeaderSize="8192" 
      SSLEnabled="true"
    	maxThreads="150" 
      minSpareThreads="25" 
      maxSpareThreads="75"
    	enableLookups="false" 
      disableUploadTimeout="true" 
      useBodyEncodingForURI="true"
    	acceptCount="100" 
      scheme="https" 
      secure="true"
    	clientAuth="false" 
      sslProtocol="TLSv1.2" />

    This enables SSL access on port 8443 (the default for HTTPS is 443, but 8443 is used here instead of 443 to avoid conflicts). For security reasons, we recommend requiring TLS 1.2. If you have clients that don't support TLS 1.2, you can change the sslProtocol entry to: sslProtocol="TLS"

    If you created the keystore somewhere else on the filesystem, add the keystoreFile attribute to the connector tag as well:

    keystoreFile="/path/to/keystore/bitbucket.jks"

    On Windows the path must be specified in URL format, using forward slashes (rather than backslashes), e.g.:

    keystoreFile="file:///C:/Users/Administrator/bitbucket.jks"

    If your keystore password is anything other than "changeit", add the  keystorePass  attribute to the connector tag as well:

    keystorePass="<password value>"

    If your keystore password is anything other than "changeit", add the  keystorePass  attribute to the connector tag as well:

  2. Comment out the existing Connector directive for port 7990 in <Bitbucket home directory>/shared/server.xml, so as to disable HTTP access, if you want all access to Bitbucket Server to make use of HTTPS. That is, comment out this directive:

    <Connector port="7990"
        protocol="HTTP/1.1"
        connectionTimeout="20000"
        useBodyEncodingForURI="true"
        redirectPort="8443"
        compression="on"
        compressableMimeType="text/html,text/xml,text/plain,text/css,application/json,application/javascript,application/x-javascript" />
  3. Start, or re-start, Bitbucket Server. You will be able to access Bitbucket Server at https://localhost:8443/ in your browser.

Exporting the self-signed certificate

If Bitbucket Server will run as the user who ran the keytool --genkey command, you do not need to export the certificate.

You may need to export the self-signed certificate, so that you can import it into a different keystore, if Bitbucket Server will not be run as the user executing keytool --genkey. You can do so with the following command:

Windows:

"%JAVA_HOME%\bin\keytool" -export -alias tomcat -file file.cer

Linux, macOS:

$JAVA_HOME/bin/keytool -export -alias tomcat -file file.cer

If you generate the certificate as one user and run Bitbucket Server as another, you'll need to do the certificate export as the generating user and the import as the target user.

Requesting a CA certificate

Digital certificates that are issued by trusted 3rd party CAs (Certification Authorities) provide verification that your website does indeed represent your company.

When running Bitbucket Server in a production environment, you will need a certificate issued by a CA, such as VeriSignDigiCert or Thawte. The instructions below are adapted from the Tomcat documentation.

First, you will generate a local certificate and create a 'certificate signing request' (CSR) based on that certificate. You then submit the CSR to your chosen certificate authority. The CA will use that CSR to generate a certificate for you.

  1. Use Java's keytool utility to generate a local certificate, as described in the section above.
  2. Use the keytool utility to generate a CSR, replacing the text <MY_KEYSTORE_FILENAME> with the path to and file name of the .keystore file generated for your local certificate:

    Windows:

    "%JAVA_HOME%\bin\keytool" -certreq -keyalg RSA -alias tomcat -file certreq.csr -keystore <MY_KEYSTORE_FILENAME>


    Linux, macOS:
     

    $JAVA_HOME/bin/keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr -keystore <MY_KEYSTORE_FILENAME>
     
  3. Submit the generated file called certreq.csr to your chosen certificate authority. Refer to the documentation on the CA's website to find out how to do this.
  4. CA が証明書を送信します。
  5. Import the new certificate into your local keystore. Assuming your certificate is called "file.cer" whether obtained from a CA or self-generated, the following command will add the certificate to the keystore:

    Windows:

    "%JAVA_HOME%\bin\keytool" -import -alias tomcat -file file.cer


    Linux, macOS:
     
     

    $JAVA_HOME/bin/keytool -import -alias tomcat -file file.cer

トラブルシューティング

前述の説明に従って keytool で作成した自己署名証明書、または CA 証明書を使用する場合の、トラブルシューティングのヒントをいくつか紹介します。

When you enter " https://localhost:8443/ " in your browser, if you get a message such as "Cannot establish a connection to the server at  localhost:8443 ", look for error messages in your logs/catalina.out log file. Here are some possible errors with explanations:

SSL + Apache + IE の問題

Internet Explorer を使用して SSL 経由で添付ファイルをアップロードした場合にエラーが発生する問題が報告されています。これは IE のバグが原因で、Apache で次の設定を行うことで解決できます。

BrowserMatch ".MSIE." \
	nokeepalive ssl-unclean-shutdown \
	downgrade-1.0 force-response-1.0

Google 検索を行うとこれに関する多くの情報が得られます。

キーストアが見つからない

 java.io.FileNotFoundException: /home/user/.keystore (No such file or directory)

This indicates that Tomcat cannot find the keystore. The keytool utility creates the keystore as a file called .keystore in the current user's home directory. For Unix and Linux the home directory is likely to be /home/<username>. For Windows it is likely to be C:\User\<UserName>.

Make sure you are running Bitbucket Server as the same user who created the keystore. If this is not the case, or if you are running Bitbucket Server on Windows as a service, you will need to specify where the keystore file is in <Bitbucket home directory>/shared/server.xml. Add the following attribute to the connector tag you uncommented:

 keystoreFile="<location of keystore file>"

Incorrect password

 java.io.IOException: Keystore was tampered with, or password was incorrect

You used a different password than "changeit". You must either use "changeit" for both the keystore password and for the key password for Tomcat, or if you want to use a different password, you must specify it using the keystorePass attribute of the Connector tag, as described above.

Passwords don't match

 java.io.IOException: Cannot recover key

Tomcat のキーストアパスワードとキーパスワードに異なるパスワードが使われていることを意味します。この二つのパスワードは同一でなければなりません。

不正な証明書

javax.net.ssl.SSLException: No available certificate corresponds to the SSL cipher suites which are enabled.

If the Keystore has more than one certificate, Tomcat will use the first returned unless otherwise specified in the SSL Connector in  <Bitbucket home directory>/shared/server.xml .

Add the keyAlias attribute to the Connector tag you uncommented, with the relevant alias, for example:

<Connector port="8443" 
  maxHttpHeaderSize="8192"
	SSLEnabled="true"
	maxThreads="150" 
  minSpareThreads="25" 
  maxSpareThreads="75"
	enableLookups="false" 
  disableUploadTimeout="true" 
  useBodyEncodingForURI="true"
	acceptCount="100" 
  scheme="https" 
  secure="true"
	clientAuth="false" 
  sslProtocol="TLS"
	keystoreFile="/opt/local/.keystore"
	keystorePass="removed"
	keyAlias="tomcat"/> 

APR uses a different SSL engine, and you will see an exception like this in your logs:

SEVERE: Failed to initialize connector [Connector[HTTP/1.1-8443]]
LifecycleException:  Protocol handler initialization failed: java.lang.Exception: No Certificate file 
specified or invalid file format

これは APR コネクターが OpenSSL を使用しており、キーストアの使用方法が異なることが原因です。この問題の解決策は 2 通りあります :

Use the Http11Protocol to handle SSL connections

Edit the server.xml so that the SSL Connector tag you just uncommented specifies the Http11Protocol instead of the APR protocol:

 <Connector port="8443" 
  protocol="org.apache.coyote.http11.Http11Protocol"
	maxHttpHeaderSize="8192" 
  SSLEnabled="true" 
  keystoreFile="${user.home}/.keystore"
	maxThreads="150" 
  enableLookups="false" 
  disableUploadTimeout="true"
	acceptCount="100" 
  scheme="https" 
  secure="true"
	clientAuth="false" 
  sslProtocol="TLS" 
  useBodyEncodingForURI="true" />
Configure the Connector to use the APR protocol

This is only possible if you have PEM encoded certificates and private keys. If you have used OpenSSL to generate your key, then you will have these PEM encoded files - in all other cases contact your certificate provider for assistance.

 <Connector port="8443" 
  maxThreads="200"
	scheme="https" 
  secure="true" 
  SSLEnabled="true"
	SSLCertificateFile="${user.home}/certificate.pem"
	SSLCertificateKeyFile="${user.home}/key.pem"
	clientAuth="optional"  
  SSLProtocol="TLSv1"/>

クライアント認証の有効化

To enable client authentication in Tomcat, ensure that the value of the clientAuth attribute in your Connector element of your Tomcat's server.xml file is true.

<Connector
	...
	clientAuth="true"
	... /> 

For more information about Connector element parameters, please refer to the 'SSL Support' section of the Tomcat 6.0 documentation.

不正な証明書タイプ

If the certificate from the CA is in PKSC12 format, add the keystoreType attribute to the SSL Connector in  <Bitbucket home directory>/shared/server.xml .

keystoreFile="/opt/local/wildcard_atlassian_com.p12"
keystorePass="removed"
keystoreType="PKCS12"/>

証明書チェーンが不完全

キーストアでエンティティ / ドメイン証明書よりも手前にルート証明書と中間証明書がインポートされていない場合、次のエラーが表示されます。

[root@dev atlas]# /usr/java/jdk1.7.0_17/bin/keytool -import -alias tomcat -file my_entity_cert.crt
Enter keystore password:
keytool error: java.lang.Exception: Failed to establish chain from reply

ほとんどの場合、CA は複数の証明書を含む圧縮ファイルを送信します。インポート順序が重要になるため、最初にルート証明書、次に中間証明書 (1 つまたは複数)、最後にエンティティ / ドメイン証明書の順でインポートする必要があります。keytool を使用した Tomcat (Java ベース) Web サーバーでの証明書のインストール向けのガイダンスを提供する多数のオンライン リソースがあります。

最終更新日: 2018 年 2 月 13 日

この内容はお役に立ちましたか?

はい
いいえ
この記事についてのフィードバックを送信する
Powered by Confluence and Scroll Viewport.