| Expand | ||||||
|---|---|---|---|---|---|---|
| ||||||
|
Kantega SSO Enterprise for Jira, Confluence, Bitbucket, Bamboo and Fisyeye/Crucible follow an almost identical pattern on each of the products. If you have one of those, this guide is for you.
Introduction
This guide will show how to establish password-less Integrated Windows Authentication (Kerberos) single sign-on for a Confluence instance available at https://wiki.example.com. The Windows uses are logged into their computers using the Active Directory domain EXAMPLE.LOCAL.
| Info |
|---|
In this example, we assume a Microsoft Active Directory/LDAP User Directory has already been set up for the same domain. We also assume that you have Domain Admin rights so that you can create and configure user accounts in AD. If you do not have these permissions yourself, you will have to ask a colleague for help. We recommend setting up a test environment before you go to production. |
This YouTube video shows the necessary steps to set up Kerberos login and how the login experience will be when it is configured. It was created a couple of years ago Some screenshots may have been altered slightly since then:
| Widget Connector | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
Setup wizard
In the configuration page, click Run Kerberos Setup Wizard.
This wizard helps you in the following ways:
It helps you collect some essential information about your environment.
It shows you how to create and/or configure an Active Directory account.
It shows you the
ktpasscommand you will use to create a Kerberos keytab file on your Active Directory server, which Kantega SSO needs to import to authenticate users.
Start page
In many cases, the wizard can suggest appropriate configuration values for you automatically. If this is the case, you will be notified. You might want to jump straight to the task summary using If you already have connected a user directory of the type Active Directory this makes it easier for the wizard to guess the right values. If all values in this page look good, you can jump straight to the task summary (by clicking User these values) in below screenshot using the suggested values instead of going through each step.
...
For this guide, though, we will run through each step of the wizard.
Active Directory Connection
Connecting to your Active Directory lets the wizard inspect your AD, suggest values, and validate that your configuration is valid.
You can choose a pre-configured User Directory, or connect to an Active Directory server of your choice:
Canonical hostname
...
If you instead click Run wizard to change values, you will come to pages looking like the ones below.
Canonical host name
In our case wiki.example.com is the actual Canonical name (A RECORD) and we can use this. (If wiki.example.com was a DNS CNAME alias, say for server123.example.local, then the canonical name is should be server123.example.local
Otherwise, if it's a DNS A record, then the canonical name is issues.example.com.
Usually, the wizard can determine this for you by looking it up in DNS on the server.
...
Note that even if you access JIRA using the short name http://issues, the canonical name is always in the FQDN form. (It is never just issues, but issues.example.com)
Kerberos Realm name
...
It is your Active Directory Domain name in upper case, dot-separated format.
...
If the wizard can't look this up in AD, it will instruct you on how to determine this on your client.
Active Directory account
Kerberos services need to be mapped to an Active Directory account. We recommend you use a separate AD account to map each Kerberos service.
Unless your instance is already mapped, the wizard will suggest an account name such as svc-jirasso-issues.
...
Encryption types
The wizard will suggest the strongest encryption type supported by your environment.
Some factors which may limit your choice of encryption strength:
If your Domain Functional Level is Window 2003, then only RC-4 is supported. However, in newer Java versions, RC4 HMAC encryption is no longer supported.
AES-256 is only supported if the Java used for running your Atlassian product has the Unlimited Strength Policy Files installed
Enabling AES 256 support in Java
If your service is already mapped to an account, then the strongest configured encryption type for that account is recommended.
In this case, the wizard has recommended AES-256:
...
.)
The wizard will try to lookup the right Canonical name using DNS, but it is not always available to do so in some environments.
...
Realm
On this page you select the realm to use in your setup. If you have a complex AD structure with multiple realms you will be able to lookup users in an AD forest.
...
Active Directory Account
You need to select the name you want for the account linked to the Kerberos keytab file. This account will later need to be created in your AD.
...
Ecryptition type
We strongly suggest you select the highest encryption type AES 256 for better security. Only in a mixed environment of older AD servers you might need some of the weaker encryption, but please note that this will leave your system weak for attacks.
...
Summary / Tasks
On the summary page you are give certain tasks like creating the right user account in AD and selecting the appropriate encryption. You will also have to run a PowerShell script shown on the page with the command ktpass to create the keytab file to import into Kantega Single Sign-on Enterprise. As a final step you upload the keytab file. Read more on the following steps to make things work here: https://kantega-sso.atlassian.net/wiki/x/NQBQYQ
...
The Get-ADUser part of the above command will clear potential earlier attempts to link the SPN HTTP/wiki.example.com@EXAMPLE.LOCAL to other accounts in AD. The $null value in the end is correct syntax to clear the value of the UserPrincipalName field making ktpass command more likely to succeed.
A quick review of the ktpass syntax
Command / parameter | Description | ||||
|---|---|---|---|---|---|
| ktpass is pre-installed in Windows 2008 onward. Located in c:\Windows\System32 | ||||
| HTTP is always used for web servers, also when using https. wiki.example.com is the canonical DNS name of Confluence EXAMPLE.LOCAL is the Kerberos realm name of the Active Directory Domain | ||||
| Maps the /princ name above to the account svc-confluence-sso. ktpass will add this attribute on the account:
| ||||
| Specifies the encryption type used when generating keys in the keytab. Must match the account supported encryption type. | ||||
| The general ptype, recommended by Microsoft. | ||||
| Output location of the generated keytab file |
Running the ktpass command will output a keytab file and register wiki.example.com as an HTTP Kerberos service.
Specifically, ktpass will:
Add a
servicePrincipalNameattribute on the account with the valueHTTP/wiki.example.com.Set the
userPrincipalNameattribute toHTTP/wiki.example.com.Ask the admin to provide a password and confirm it.
Set that password on the account.
Generate a
keytabfile with anAES-256key for the principalHTTP/wiki.example.com@EXAMPLE.LOCAL.
Note that ktpass must be running in a "Run as administrator" PowerShell window by a user with Domain Admin permissions.