You are viewing the Kantega SSO legacy documentation. The new documentation site is: https://kantega-sso.atlassian.net/wiki/x/hwAb
Skip to end of metadata
Go to start of metadata


Keytab files

How do I create a keytab file?

Keytab files are created with ktpass. Preferably on server 2008 or later. The user running ktpass must be member of domain admin or enterprise admin.
See this section for detailed instructions. 

How do I merge keytabs? 

Ketyabs are merged inside Kantega Single Sign-on by uploading sequental keytab files and selecting to merge instead of overwriting the previous.

Earlier version used ktutil (linux) for merging. Using ktpass will add a SPN to an excising keytab, bumping the version number if it exists.
See this section for detailed instructions  on how to use ktutil

Key version mismatch in the Kerberos test page

Either the latest generated keytab is not uploaded to our plugin or the clients holds on to an outdated ticket. Make sure the latest generated Keytab is uploaded to our plugin and run klist purge on the client to purge Kerberos tickets. Run the "Active Directory server test" to detect possible misconfigurations

I am getting a GSSException on Kerberos test page

With a checksum error, the browser is sending a Kerberos ticket, and the keytab has a key for the SPN+encrypte, but it can't decrypt/verify the ticket. Usually this is because of an invalid keytab.

The most common causes:

  • Very often, this is just a ticket cache issue. If you have been testing and recently ran ktpass to issue a new keytab, it's likely the client is still holding on to and sending a cached ticket for the old service account/keytab. Try opening a CMD prompt on the client (not as admin) and run "klist purge". This will force the client to obtain a fresh ticket.

  • The password or salt for the keytab may be incorrect. This should not be possible if you used the ktpass command and procedure provided by the Kerberos wizard.

  • The service account password was changed after the keytab was issued. It is important that you only use the service account to the specific purpose of obtaining one keytab for only one site/url and nothing else. If you are reusing the service account for multiple sites (like for instance test/production or jira/confluence) you will break the service account whenever you try to obtain more than one keytab. Use more than one account if you need for multiple sites or for instance for LDAP user to lookup users in Active Directory.

Other than that, check the output of the add-on test page carefully. Is it highlighting any other problems? In particular: Any warnings about ticket KVNO and keytab KVNO mismatch?

Browser sends an NTLM token instead of a Kerberos token

Browsers on Windows will first try to acquire a Kerberos token. If that fails for some reason, the browser falls back to sending an NTLM token. This typically results in a username/password popup box.

The most common reason for Kerberos to fail is that the site is not in the Local Intranet Zone (IE and Chrome) or that the site is added to the trusted URL list in Firefox. See browser configuration for details.

Other common reasons for Kerberos to fail is that you have issued the keytab using the wrong Service Principal Name. See How Kerberos Works for details about how browsers determine the SPN.

I have to press the login button to be logged in.

Our plugin does not try to log in a user when Confluence would otherwise not have required that user to log in. 

This means that all users will see the page anonymously. If they then press login or access content that requires authentication, then a Kerberos login will be attempted. When an attempted login fails (either because the end user is not a Kerberos user or because the user is not known to Confluence), then the plugin will fall back to showing Confluence’s login page. The most common reason is Confluence with anonymous read permissions.

Links to filters does not automatically log in users.

Our plugin only tries to log in a user when JIRA would otherwise have required that user to log in. JIRA will show different results whether the user is logged in or not, and hence does not redirect to the login page for anonymous users. This results in Kerberos Authentication not being triggered.
Activating "Forced SSO URLs" (previously named: Preemptive authentication) forces Kerberos logon to filter URLs.

Does application links work with our add-on?

Our add-on does not affect how application links work. Because users don`t have to authenticate to each application, we recommend using OAuth Impersonation application links.

The user has to log on manually the first time

Make sure the Default Group Memberships is set. This setting can be found when editing the user directory. Make sure the group has global logon permissions. 
Because of an unexpected behavior in confluence when checking if the user has logon permission try configuring "configured required group".

How can we restrict who should be logged in with Kerberos

Our plugin supports IP white/blacklisting for when to perform Kerberos. For IP white/ blacklisting to work our plugin needs to see the correct client IP.
Which client IP our plugin sees is shown under "Client IP restrictions".

Also, you may enable restriction based on what User Agent the client uses.

User sessions time out after 4 or 5 hours, can we increase the session timeout?

Our plugin does not affect the session timeouts in the Atlassian products they run on. Please refer to Atlassian's documentation if you need to change this:

Alternative UPN Suffixes

When Active Directory is configured with alternative UPN suffixes (e.g. both example.com and example.local) Kerberos Authentication can be set to look up users with both. Configure additional user mappings to reflect the Alternative UPN suffixes in Active Directory Domains and Trusts.

Does single sign-on work with Bitbucket clients?

Yes, single sign-on can be configured also for Git clients. There is an option to enable Kerberos on the common /scm/* path and an alternative path. Enabling this will allow Git clients to clone from the alternate, Kerberos-enabled path /kerberos-scm/* 

An alternate clone URL "HTTP+SSO" will also be added to the Bitbucket clone dialog.

See Using Git with Kerberos for details

Why am I asked for a password to enter the admin section?

This is by design. If you would like users to be able to enter the admin section without entering their passwords, Atlassian has a way of disabling secure administrator sessions (WebSudo)

https://confluence.atlassian.com/adminjiraserver073/configuring-secure-administrator-sessions-861254024.html

Can we make SSO work for users with non UTF-8 characters in their username?

Non-UTF characters in usernames is not supported by Java's Kerberos implementation by default. To enable support for UTF-8, you need to set the property -Dsun.security.krb5.msinterop.kstring=true (typically in setenv.sh). This will allow usernames with characters such as ö, ü, ä to sign in log using Kerberos.

User Directories

How are Kerberos users mapped to accounts in User Directories?

Kerberos uses the sAMAccountName Active Directory attribute to identify users.

The add-on will extract this username from the client's Kerberos Principal Name and use that when looking up users in User Directories.

Example: If the Kerberos Principal Name is "johndoe@EXAMPLE.LOCAL", the add-on will search User Directories for the account "johndoe".

This means that if your accounts are named with the standard username attribute, you can use any of the User Directory types supported by Atlassian:

  • Active Directory,
  • Atlassian JIRA
  • Crowd
  • Generic LDAP
  • Internal
  • Internal with LDAP Delegation

If you have multiple User Directories, the user will be looked up in the same order as with manual logon.

Our Active Directory has a non-standard User Name Attribute, will that work?

Yes. Our add-on will automatically detect that your User Directory has a non-standard User Name Attribute. (Different from sAMAccountName, say "userPrincipalName")

If this is the case, the add-on will first look up the account in AD using the standard sAMAccountName, then map it to the configured User Name Attribute you configured, and finally perform a new search using that name.

Can we use a Crowd User Directory?

Yes. Our add-on will search your Crowd User Directory with the standard account name (sAMAccountName)

Can we use an Internal User Directory?

That's certainly possible, but to simplify user management we recommend you set up an Active Directory User Directory instead, perhaps using local groups.

Environment

Can SAML and Kerberos work in combination?

Yes! When both SAML and Kerberos is configured, Active Directory joined devices can benefit from password-less SSO with Kerberos, while mobile phones and other standalone devices are offered SAML SSO.

What server operating systems are supported?

Actually, JIRA/Confluence etc. may run on any operating system. 

Does the server running the application have to be domain joined?

The server may or may not be domain joined. 

Is SSO from multiple domains supported?

Yes. Create a keytab file. One for each domain. Merge the keytabs to one file and upload it.

How does Confluence collaboration (synchrony) work with Kerberos

Very large Kerberos tokens may affect Synchrony. If users are experiencing issues with collaboration, run the Web Server Test inside our add-on and it will tell you how to apply configuration to the proxy server. Sample configuration can be found here.

Can we use AES encryption with server 2003 / domain functional level 2003?

No, domain functional level must be 2008 or greater. Run the "Active Directory server test" in our plugin to determine the functional levels.

Advanced Encryption Standard (AES 128 and AES 256) support for the Kerberos protocol. In order for TGTs to be issued using AES, the domain functional level must be Windows Server 2008 or higher and the domain password needs to be changed. 

Is Linux KDC supported?

Our plugin does not communicate with the KDC at all. We receive the SPNEGO token as an HTTP header and verify that against the uploaded/configured keytab file. Our plugin don't really care where the keytab file was created, as long as it is in the valid keytab file format and has keys with the right encryption type, version number, Service Principal Name and key material. There is no network traffic going on during this verification process. 

Our built in Active Directory Test Page expects to test an Active Directory server. There is nothing preventing you from using a different KDC. As long as it is configured properly.

Manual login stops functioning after issuing a keytab

If the user used to bind to Active Directory is used when creating a keytab you may experience that all user logons fail. To fix the issue delete the user account in Active Directory and recreate use user with the same username and password as before. An alternative is to log in with a user in the internal user directory and alter the Active Directory user directory. A third option is to alter the settings directly in the database. 

Kerberos plugin detects Duplicate SPN

Duplicate SPN (e.g. HTTP/jira.example.com) cannot exist in Active Directory. The Kerberos test page detects duplicate SPN. To the resolve the issue either delete the user in Active Directory that has the duplicate SPN. An alternative is to remove the SPN from the user object. setspn -D HTTP/jira.example.com accountname

What could be the cause when we experience very slow logins?

User directories can be configured to update group memberships at login, and in some network environments these operations can be very slow. If you experience very slow logins, you should check the settings controlling the update operations. These are found in your user directory configurations. 

Under advanced settings you will find a setting called "update group memberships when logging in" (see attached screenshot). Slow login problems caused by the update group membership operations should disappear if you set this setting to "never".


Web proxy server configuration

How to configure Kerberos Authentication with Apache?

See this section for detailed instructions

Does Kerberos work with mod_proxy_ajp?

We have seen problems with Apache 2.2 combined with allowing large HTTP headers (using ProxyIOBufferSize). We recommend using HTTP instead of AJP, or using Apache 2.4.

How to configure Kerberos Authentication with Nginx?

Atlassian has documentation on how to configure Nginx. We have sample configuration available at this page

Log gives 400 ERROR or we get a blank page when authenticating

A blank page is in most cases a HTTP 400 error. More detail can be obtained by disabling http friendly error messages. Some Kerberos clients send Kerberos tokens which are so large they make the client request exceed the maximum header size limit of your server (typically around 8000 bytes for both Apache,Nginx and Tomcat). (IIS is about 16K)

Circumventing HTTP 400 can be done by appending ?nokerberos to Dashboard.jspa or login.jsp 

Bundled with the plugin there is a test to determine an appropriate value. (Web server test page) Changes has to be made to both Tomcat and a proxy if one is used. Tomcat needs to be restarted to apply the changes.  

Kerberos authentication fails for non US-ASCII usernames

ActiveDirectory allows the use of unicode for a user's sAMAccountName. The Kerberos spec technically only allows US-ASCII for user principals, however. While avoiding non-ASCII characters in usernames gives the best interoperability and is generally recommended, support for unicode usernames can be enabled by setting -Dsun.security.krb5.msinterop.kstring=true on application startup. The exact procedure varies depending on Atlassian application and platform, but generally involves editing the start script. 

Common characters that require this setting in order for Kerberos to work includes umlauts (ü, ö etc.) and the German eszett (ß).

The Usage counters reports a lot of client did not return a token

Improperly configured browsers will not reply with a Kerberos token. Monitoring software may also generate hits to this counter. The counter is reset with restart of the application. 

Other topics

Is there a way to avoid Kerberos from happening for a specific login even though I am using Kerberos?

If you add this parameter to your sits URL: ?nokerberosSession you will avoid getting Kerberos for your web session.

And if you would like Kerberos to trigger again after this, add the following to your URL: ?kerberosSession

This could be relevant if you want to log in to a non-Kerberos administrator account or if you want to avoid Kerberos on certain calls to your system.

We have turned on the "Disable traditional username/password login" feature and now needs to log into a local admin account using username and password. What do we do?

To be able to log in via username and password, you need to allow username and password again by disabling this feature. This is done by deleting the file <my-atlassian-product-home-folder>/kerberos/disable_username_password_login.txt. For certain Atlassian products like Bitbucket, the file is sometimes located in the folder <my-atlassian-product-home-folder>/shared/kerberos/disable_username_password_login.txt.