FAQ - Frequently Asked Questions

We are happy to hear from you if you don't find the answer to your question here.

General

What do I have to do to move my Kantega SSO installation from Server to Data Center?

In short, the Kantega SSO version is fully compatible with both Atlassian Server and Atlassian Data Center products, and configuration is saved in the same way on both types. Therefore, if you use Atlassian recommendations for importing the database and home folder from the previous installation to the new, your Kantega SSO setup should work directly. That is as long as your DNS name for the new installation is the same as the previous (for example https://my-jira.example.com).

If you need to change the DNS name for your installation, you would have to:

  • for a Kerberos setup, to create a new keytab file with the new DNS name

  • for OIDC/SAML setups create new/change configurations in your Identity providers since the configurations point to the old DNS name.

You could possibly also use the Kantega SSO backup and restore feature to move your configuration from the old installation to the new. This would also correctly move configuration for Kerberos/SAML/OIDC setups. But configuration for Cloud User Sync will be somewhat more work since these rely on a User directory setup that is not restored. And especially for a SCIM setup, you would have to run the SCIM setup wizard again.

Do contact us if you have any questions regarding moving your installation and we will be very glad to help you out with the details.

Cloud User Sync

Do I need a license for Atlassian Crowd to use the Cloud User Provisioning feature?

No, Atlassian Crowd Server is not used to make connectors work, so you do not need to have a license for this. The Cloud User Provisioning feature uses the Crowd protocol for user communication with the Atlassian products, that is all.

Why do the administrator (web sudo) logins fail?

The connectors do not send or synchronize password information. If you have web sudo enabled in your Atlassian product and you administrator users defined in the cloud your administrators will experience a traditional login screen when they access admin pages. These logins will also fail as the Atlassian product is not able to verify the password. There are two solutions to this issue: 1) Disable "web sudo" in your setup. 2) Create administrator users in the internal directory.

Kerberos

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 a 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 single keytab files and selecting to merge instead of overwriting the previous. See more on this here.

Key version mismatch in the Kerberos test page

Either the latest generated keytab from Active Directory is not uploaded to Kantega SSO or the clients hold on to an outdated ticket. Make sure the latest generated keytab file is uploaded to Kantega SSO 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 the Kerberos test page

With a checksum error, the browser is sending a Kerberos ticket, and the keytab has a key for the SPN encryption, but it can not 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 is 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 the command: 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 for 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 multiple sites or for instance for LDAP users to lookup users in Active Directory.

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

User gets a username / password popup and/or the 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 https://kantega-sso.atlassian.net/wiki/spaces/KSE/pages/1868170/Browser+configuration for details.

Other common reason for Kerberos to fail is that you have issued the keytab using the wrong Service Principal Name. See https://kantega-sso.atlassian.net/wiki/spaces/KSE/pages/1736931/How+Kerberos+works for details about how browsers determine the SPN.

Read more here about how to https://kantega-sso.atlassian.net/wiki/spaces/KSE/pages/1802652/Enable+or+disable+Kerberos+for+specific+clients to avoid Kerberos challenge giving the popup on clients where it is not appropriate.

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

Kantega SSO by default only logs in users where your Atlassian product also would do so. Please use the “Forced SSO URLs” feature to have login happen more frequently.

This means that also anonymous users will be able to see pages that should not require login. If the user then presses login or accesses content that requires authentication, login will be attempted. When an attempted login fails (either because the end-user is not a known Kerberos user or because the user is not in the User Directory of your Atlassian product), Kantega SSO will fall back to showing the regular login page. 

Kantega SSO 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" forces Kerberos logon to filter URLs.

Kantega SSO does not affect how application links work. Because users do not have to authenticate to each application, we recommend using OAuth Impersonation application links.

Why does the user have to log in 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 unexpected behavior in confluence when checking if the user has logon permission try configuring "configured required groups".

How can we restrict who should be logged in with Kerberos?

Kantega SSO supports IP blocking/unblocking for when to perform Kerberos. For IP blocking/unblocking to work Kantega SSO needs to see the correct client IP.
Which client IP Kantega SSO 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?

Kantega SSO 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:

In Confluence and Jira you may enable the Remember My Login feature to have sessions last up to two weeks.

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 Kerberos single sign-on work with Bitbucket clients?

Yes, single sign-on using Kerberos 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. Other mechanisms in Kantega SSO than Kerberos is not supported for login by Git clients. If you are not using Kerberos, please use username/password or preferably SSH keys.

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).

Guide for disabling in Jira:
https://confluence.atlassian.com/adminjiraserver073/configuring-secure-administrator-sessions-861254024.html

In Confluence, please navigate to the address <your_confluence_url>/admin/viewsecurityconfig.action and turn off the value “Secure administrator sessions”.

User Directories

How are Kerberos users mapped to accounts in User Directories?

Kerberos uses the sAMAccountName Active Directory attribute to identify users.

Kantega SSO 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", Kantega SSO 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. Kantega SSO will automatically detect that your User Directory has a non-standard User Name Attribute. (Different from sAMAccountName, say "userPrincipalName")

If this is the case, Kantega SSO 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. Kantega SSO will search your Crowd User Directory with the standard account name (sAMAccountName)

Can we use an Internal User Directory?

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

Environment

Can OIDC, SAML, and Kerberos work in combination?

Yes! When OIDC and/or 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 OIDC or SAML SSO.

What server operating systems are supported?

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

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

The server may or may not be domain joined. Kerberos setup is possible anyhow. 

Is SSO from multiple domains supported?

Yes. Create a keytab file. One for each domain. Then upload each keytab file in Kantega SSO to merge them.

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 of Kantega SSO and it will tell you how to apply the configuration to the proxy server. A 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 Kantega SSO 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?

Yes. Kantega SSO 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. Kantega SSO does not 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.

Does manual login stop 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 logins fail. To fix the issue, delete the user account in Active Directory and recreate a 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. 

What does it mean when Kantega SSO detects Duplicate SPNs?

The same SPN (e.g. HTTP/jira.example.com) cannot exist on two users at the same time in Active Directory. The Kerberos test page will detect duplicate SPNs and flag this. To resolve the issue either delete one of the users in Active Directory that has the duplicate SPN. An alternative is to remove the SPN from the user object with this command

setspn -D HTTP/jira.example.com accountname

What could the cause for very slow logins?

User directories can be configured to update group memberships at login, and in some network environments these operations may 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" or “only on the first login”.

 

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 a sample configuration available on this page.

Why does the log give a 400 ERROR or a blank page when authenticating?

A blank page is in most cases an HTTP 400 error. More details 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 to be able to log in can be done by appending ?nokerberos or ?nokerberosSession to the URLs of 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.  

Can we make SSO work for users with non-UTF-8 characters in their 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 include umlauts (ü, ö etc.) and the German eszett (ß).

The Usage counters in Kantega SSO reports a lot of clients 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

You will have to wait up to one minute after the file is deleted before username/password login works.

SAML and OIDC

What is the difference between SAML and OpenID Connect?

SAML and OpenID Connect (OIDC) are both identity federation technology. SAML is XML-based, while OIDC is built on top of OAuth 2.0 with JSON and REST. They are both mature and secure protocols for setting up SSO to Confluence and work on both desktop clients and mobile apps.

More info about SAML and OpenID Connect

Environment

Which Identity Providers do you support?

We have made step-by-step instructions for the most common IDPs. If you IDP is not listed, then choose "Any other SAML / OIDC provider" in the setup wizard. 
If you want to add a vote for your IDP to be added to the setup wizard, don't hesitate to reach out to us. 

Do we need to make any file system changes to offer SAML or OIDC to mobile devices or JIRA Service Desk?

No, there is no need to make file system changes. Installing Kantega Single Sign-on will give you SSO to both JIRA and JIRA Service Desk. There is a switch to disable SAML/OIDC login for JSD on the “Redirect modes” page.

What is “known domains”?

The Known domains feature is both for increasing security and it enables the plugin to redirect the user to the correct IDP.

Let us say you have a user mark.miller@example.com. If example.com is a known domain to one IDP, we can redirect the user to that IDP.
If example.com is a known domain for two or more IDP, the user must choose. Remember to select a good name for your IDP.

If known domains is set to "Trust identity provider to log in users from any domain", potentially, the IDP can authenticate users from another domain.

What is “hosted domain”?

Hosted domain (hd) is a parameter that is sent to the IDP as a hint for which domain the user should log in with. You can enable this functionality in the Known Domains tab. This is not a security feature as it does not prevent logging in with another domain, however, it provides an increased user experience with providers supporting this feature.

Can we add multiple Identity Providers?

Yes, add as many as you like and combine SAML and OIDC if you like!

By adjusting modes under “Redirect rules” under each provider, you may prioritize when each should trigger.

Is logging in with mobile devices supported?

Yes, JIRA Mobile and Confluence Mobile clients are offered SAML and OIDC login. 

Do you support SAML and OIDC for the JIRA Service Desk?

Yes, both JIRA Service Desk agents and customers are offered SAML and OIDC login. You may disable SAML and OIDC login for JSD users if you like.

How can I solve getting a 'BeanInstantiationException: Failed to instantiate [org.kantega.atlaskerb.saml.SamlConfManager]' during startup when using AppDynamics?

When using the AppDynamics agent, the Kantega SSO may fail to enable with a BeanInstantiationException, frequently with internal cause org.w3c.dom.ls.LSException: An unsupported encoding is encountered.

We have reports of customers successfully resolving this by adding the following parameters to the startup script:

1 -Datlassian.org.osgi.framework.bootdelegation=META-INF.services,com.yourkit,com.singularity.*,com.jprofiler,com.jprofiler.*,org.apache.xerces,org.apache.xerces.*,org.apache.xalan,org.apache.xalan.*,sun.*,com.sun.jndi,com.icl.saxon,com.icl.saxon.*,javax.servlet,javax.servlet.*,com.sun.xml.*,org.apache.xml.serializer,net.shibboleth.utilities.*,org.opensaml.core.*

Can I use "Edit in Office" (WebDav) in combination with SAML or OIDC for my Confluence 6.11.x and newer?

Yes, in newer versions starting from Confluence 6.11.x you may use the Atlassian Companion app to edit your Office files also when you log in using SAML or OIDC.

Can I use "Edit in Office" (WebDav) in combination with SAML or OIDC for my Confluence 6.10.x and older?

No, the WebDav technology does not support these technologies. If you are using SAML or OIDC for login into Confluence and want to edit a Word, Excel or PowerPoint document: Please download the document, edit it and then upload it again.

User Directories

How are SAML and OIDC users mapped to accounts in User Directories?

The chosen user name attribute is matched against existing user directories in the order they appear in the User Directory list. 

What user directories are supported?

Actually, all user directories are supported. Your users may reside in a combination of Internal User Directory, Active Directory, Crowd, atlassian-user.xml, etc.

Can SAML and OIDC login be bypassed?

Yes, adding ?nosaml to the login URL will present the standard username/password screen. This is relevant if you want to log into a local administrator account when automatic redirect to SAML identity provider is enabled.

I have a problem with my IdP setup and have been using the "do not show login page" redirect mode. How can I log in locally to fix this?

By adding ?noautosso at the login URL, you will avoid being directly sent to you IdP. You could also press the "Cancel" link that is presented very briefly in the upper left of the screen during the automatic redirect.

Kantega SSO does not affect how application links work. This is because users do not have to authenticate to each application. We recommend using OAuth Impersonation application links when setting this up.

I am asked for a password to enter the admin section and not able to proceed since my identity has been established through SAML or OIDC?

This is by design and default activated on Jira and Confluence. If you would like SAML or OIDC 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

API Tokens

User accounts gets locked out when API tokens gets invalidated or expires. How can I prevent this from happening?

API tokens created in version 4.3.0 and earlier was treated in the same way as user passwords. As a result, requests made with expired or invalid tokens was counted as a failed login attempt. API tokens created starting with version 4.3.1 does not count towards failed user logins. Old API tokens (created before version 4.3.1) can be prefixed with API_TOKEN_ to get the new functionality.

Licensing

How do I get a license?

Trial licenses and extension of existing trials are managed via https://my.atlassian.com. Licenses can be purchased through the Atlassian Marketplace or via your preferred Atlassian Expert.

Can we extend our trial beyond 30 days?

Trial licenses can be extended for 30 days up to six times via https://my.atlassian.com. See direct links per app below: 

Which license tier do I need when purchasing an add-on?

See Atlassian's licensing FAQ: https://www.atlassian.com/licensing/marketplace#licensingandpricing-1

"Purchase the license tier that matches the number of users you have licensed for your host application. For example, if you have a 25-user Confluence license, purchase the Confluence add-on at the 25-user tier. 
The add-on will only function if its license matches or exceeds the tier of the host application – even if only some of your licensed users need to use the add-on."

For JIRA, the license has to match the highest application tier. If you have a 500-user JIRA Software license, and a 250-user Core license, then the license needs to be at the 500 level. 

JIRA ServiceDesk customers can log in with our add on for free since they are not counted against the user tier.

Examples:

25 JIRA service desk agents and 10000 service desk customers = KSSO 25 user license

50 JIRA service desk agents, 10000 service desk customers, 500 JIRA Software Users = KSSO 500 user license

What happens when the license or trial expires?

Without a license our plugin will not log in users. Users are presented with the standard login page. The KSSO admin panel will still function, so and will report that the license is invalid.