FAQ - Frequently Asked Questions
We are happy to hear from you if you don't find the answer to your question here.
General
Can Kantega SSO be combined with other SSO solutions?
In general, combining multiple SSO solutions in one Atlassian product, like Jira or Confluence, is not a good idea. What could happen is that the different solutions struggle to take action when a user is not logged in and collide when doing this. In the worst case it could introduce security vulnerabilities in your system. Kantega SSO is best used alone as the SSO solution and should cover most needs. On the other hand, it should work to use mechanisms in Kantega SSO that are not directly related to SSO like Cloud user provisioning or User cleanup in combination with for example say Atlassian SSO.
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 Base URL for the new installation is the same as the previous (for example https://my-jira.example.com).
If you need to change the Base URL name for your installation, you would have to:
for a Kerberos setup, create a new keytab file with the new Base URL
for OIDC/SAML setups create new/change configurations in your Identity providers since the configurations point to the old Base URL.
You could alternatively use the Kantega SSO Backup & restore (Snapshots of config) 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.
How can I access my Atlassian instance after my Kantega SSO data center license has expired?
Since Kantega SSO stops working without a valid license on data center, you might be unable to login to your instance if you have disabled traditional login. More information about the “Prevent traditional login” feature along with recommended setup can be found on this page: Enforce SSO and MFA
To disable “Prevent traditional login” and log in with a local admin account, delete the following file:
<atlassian_home_folder>/kerberos/disable_username_password_login.txt
If you do not have access to a local administrator account and/or are unable to delete “disable_username_password_login.txt”, we recommend following Atlassian’s guides for recovering the administrator account:
Confluence: https://confluence.atlassian.com/doc/restore-passwords-to-recover-admin-user-rights-158390.html
Bitbucket: https://confluence.atlassian.com/bitbucketserver/lockout-recovery-process-776640158.html
Is Kantega SSO Enterprise affected by the log4j vulnerability CVE-2021-44228?
We have looked into our dependencies, and found out that our runnable is not affected since the Atlassian runtime system a versions which is out of scope for the vulnerability. Look at Atlassian's FAQ for the incident here about on premises logging in general: https://confluence.atlassian.com/kb/faq-for-cve-2021-44228-1103069406.html. You may read more about the incident for Atlassian systems in general in Atlassian’s FAQ: https://confluence.atlassian.com/kb/faq-for-cve-2021-44228-1103069406.html
Updating Kantega SSO Enterprise
My system stopped working after update. How do I revert Kantega SSO Enterprise back to a stable version?
Sometimes an unexpected error occurs when you update Kantega SSO Enterprise in major versions (e. g. from version 4.x to 5.x.), and the update of configuration will not work. Whenever you get an error we recommed you contact our support team for troubleshooting. To get your system up an running again i the meantime follow the process in this giude: Reverting Kantega SSO Enterprise to a stable version.
Why won’t the update run, or fail?
If you get an unexpected update error, it might be that the Jira/Confluence etc. process doesn’t have proper file permissions in the home folder. Kantega SSO Enterprise always backs up a config before updating it, and needs to be able to create a backup of config file and save this in the file system.
Why do I get a “Missing or invalid CSRF protection token detected
The browser submitted a POST request which did not include a valid CSRF protection token” error after upgrade to version K-SSO version 5
From Kantega SSO Enterprise 5.0, the policy for CSRF has been changed. Now you need to have an Origin
header set in the POST request to save data to a page in KSSO. For exampe, if you are using nginx proxy, you might have to set the following value in your configuration: Access-Control-Allow-Origin: <your-domain-here>.
In the mean time, if you need your system up and running fast, follow the process in this guide: Reverting Kantega SSO Enterprise to a stable version.
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.
Why did SCIM sync PATCH requests stop working on Jira 10?
Atlassian has made several changes related to Platform 7. One of the changes is that they now restrict HTTP methods they haven’t implemented, consequently breaking the PATCH request that Kantega SSO accepts as part of the SCIM specification. We have contacted Atlassian in order to solve this problem, and they have created a high priority ticket: https://jira.atlassian.com/browse/JSWSERVER-26162. Meanwhile, the existing workaround is to use the API Server. Using this endpoint you can use your frontend server/reverse proxy to terminate the HTTPS and map to HTTP on the bind port.
So the request directly to the API server will be:
curl --location --request PATCH 'http://YOUR_JIRA_HOST:5501/scim/YOUR_SCIM_TENANT_ID/v2/Users/2612370c-dd6b-464d-b4cc-b33b648fed93' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN_HERE' \
--data-raw '{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "replace",
"path": "userName",
"value": "ryan3"
}
]
}'
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?
If you encounter this exception:
SPNego Exception: GSSException: Failure unspecified at GSS-API level (Mechanism level: Permission denied)
It might be related to a setting -Dsun.security.jgss.native=true, please check if user running the Atlassian host product (Jira, Confluence, Bitbucket, Bamboo) have access to the relevant GSS library or remove the setting if it’s not necessary.
Relevant libraries might include:
Linux:
libgssapi_krb5.so
,libgssapi.so
macOS:
libgssapi_krb5.dylib
Windows:
secur32.dll
For more information you can check this documentation:
https://docs.oracle.com/en/java/javase/11/security/accessing-native-gss-api.html
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 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 How Kerberos works for details about how browsers determine the SPN.
Read more here about how to https://kantega-sso.atlassian.net/wiki/pages/createpage.action?spaceKey=KSE&title=Enable%20or%20disable%20Kerberos%20for%20specific%20clients&linkCreation=true&fromPageId=1802357 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.
Links to filters does not automatically log in users.
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.
Does application links work with Kantega SSO?
Kantega SSO does not affect how application links work by default. However, if you activate API tokens or disable Basic Auth and affect the REST API authentication, then application links could be affected. 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:
JIRA: https://confluence.atlassian.com/jirakb/how-to-change-the-default-session-timeout-604209887.html
Confluence: https://confluence.atlassian.com/confkb/how-to-adjust-the-session-timeout-for-confluence-126910597.html
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 in Jira and Confluence and is called Secure Administrator sessions (or websudo). In certain setups users may not be able to authenticate using passwords since this might not be available in the user directory or disabled.
If you logged in via an Identity Provider using SAML or OIDC you may re-authenticate with SSO (without giving the password in Jira/Confluence) to get into the admin section:
If you would like users to be able to enter the admin section without entering their passwords, Atlassian also has a way of disabling this.
Guide for disabling in Jira:
https://confluence.atlassian.com/adminjiraserver073/configuring-secure-administrator-sessions-861254024.html
Guide for disabling in Confluence:
https://confluence.atlassian.com/conf73/configuring-secure-administrator-sessions-991928809.html
Why do I see an error message in the Jira log when a user uses “Re-authenticate with SSO?
Jira gives an error Thread corrupted! ActionContext still references a HttpSession
when the websudo is established. This does not have any functional impact. The message comes due to some internal weakness and is not possible to avoid. To remove the error message from the logs, you may add this line:<logger name="com.atlassian.jira.web.filters.steps.requestcleanup.WebworkActionCleanupStep" level="OFF"/>
just above the elements </Loggers></Configuration>
in the bottom of the file:${JIRA_INSTALL}/atlassian-jira/WEB-INF/classes/log4j2.xml
Kerberos will not work when using host-resolver-rule
flag in Chrome to configure DNS for your server
During testing you may want to use the host-resolver-rules
flag to get your Jira answering on jira.example.com
instead of configuring this correctly in DNS. See how host-resolver-rule
is used:
chrome.exe --host-resolver-rules="MAP jira.example.com 192.16.1.50"
Our testing shows that during such a setup getting a Kerberos ticket form AD will not work. So when testing Kerberos you will either have to configure this link between jira.example.com and IP in your DNS servers or in your local hosts file.
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.
We are unable to log in with traditional login on Jira. When we press “Log in again”, we are instead automatically logged in with Kerberos and redirected to Jira’s dashboard.
This situation occurs when Kerberos is configured and force login is enabled. To allow users to log in with traditional login, visit Kantega SSO → Common → Force Login. At the bottom of the page there is a section called “After login behavior”. Toggling this slider off should allow users to log in with username and password after pressing “Log in again”.
How can I bulk transform usernames in Jira?
Here are some docs and discussion relevant to the topic of transforming username
https://developer.atlassian.com/server/jira/platform/database-user-and-group-tables/
https://confluence.atlassian.com/jirakb/bulk-update-user-information-in-jira-server-644875261.html
My Kerberos authentication has stopped working
Potential error messages:
Parsing of the client's SPNEGO token failed with: java.lang.IllegalArgumentException: Expected tag byte should be 60, was 4e
We changed our Kerberos implemention in version 6.26.0. If you are encountering errors with Kerberos authentication after upgrading to this version please contact us through our help desk or with mail to servicedesk@kantega-sso.com. We recommend enabling the legacy Kerberos implementation as described on this page to see if it helps the issue or changes the error message: https://kantega-sso.atlassian.net/wiki/spaces/KSE/pages/1442742278/Dark+Features#Use-legacy-Kerberos
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
OIDC
Why do I get an error message with HTTP 401 UNAUTHORIZED: Please check that your client_secret is correct?
The following error message indicates that the IDP no longer accepts the configured client secret: [OIDC-K6JCV4L81E] Failed performing OIDC POST request: Expected HTTP 200 OK. Actual response was HTTP 401 UNAUTHORIZED Please check that your client_secret is correct
.
Possible explanations:
The client secret for you OIDC integration is expired.
You accidentally copy/pasted in the wrong value. E.g. Microsoft Entra ID /Azure AD offers a secret ID field which is often confused with the client secret itself
SAML
Why do I get the error code SUBJECT_CONFIRMATION_DATA_UNEXPECTED_IN_RESPONSE_TO?
When a user is redirected from an Atlassian Data Center instance to the identity provider for authentication, the redirect includes a unique authentication request ID. When the IDP later returns the user to the Atlassian Data Center, the SAML Response from the IDP must contain an inResponseTo attribute with the same ID. If the addon receives a SAML Response with an unknown responseTo ID, you will see that error message.
It can happen for a number of reasons:
The user spent too long at the IDP, (> 30 minutes) so the ID is no longer recognized by the time the user returns with a SAML Response. The most common cause of this is open browser windows from the previous work day etc.
VPN: if the users are connecting to your Data Center through a saturated VPN, you may
Replay: An ID can only be used once. If a user reloads certain login pages, the same SAML Response can end up being POST’ed again. The ID will have been removed and is no longer usable, generating that error.
Data Center specific: Clustering problems. The ID is stored in a distributed cache (atlassian-cache). This ensures that if the user returns to a different node than the one that initiated login, login can still continue successfully. Usually though, sticky sessions ensure users return to the server they started on.
If you have load balancing problems and cannot achieve sticky sessions, then you may encounter this error. You may also see users experiencing login loops.
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 or Prometheus?
When using the AppDynamics agent or Prometheus, 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:
-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.
How is Kantega SSO affected by the new Atlassian login page?
The new Atlassian login page breaks the HTML elements that Kantega SSO injects into your login screen due to it’s new structure, and authenticates in a different way which also breaks prevent traditional login. For this reason, we recommend not setting the following parameter:
-Datlassian.authentication.legacy.mode
We mark Kantega SSO as compatible with product versions based on the default login page which means that using the above-mentioned parameter can lead to unexpected behavior. For this reason, Kantega SSO 7.32 is only available for versions with the new login page, but we will look into making it compatible with older versions as well when the new login page is released on all products.
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.
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 ?noredirect 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.
Can SAML and OIDC login be bypassed?
Yes, adding ?nosso 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 or OIDC identity provider is enabled.
In the same way, when Instant redirect to SAML or OIDC identity provider is enabled, adding ?noredirect to the login URL will present the standard username/password screen.
You find the login URLs for bypassing Instant and Auto redirect in the Redirect rules page for the Identity provider.
Does application links work with Kantega SSO?
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.
In version 5.1.0 of Kantega SSO re-login via a SAML or OIDC based Identity Provider has been added to perform websudo (see below image).
See also some consideration regarding when you can use a password to log into websudo here: https://kantega-sso.atlassian.net/wiki/spaces/KSE/pages/1769694/User+provisioning#A-note-regarding-admin-users-and-websudo-(secure-admin-sessions-in-Jira-and-Confluence)
Advanced troubleshooting
Dumping HTTP traffic in Tomcat
This might be useful in case your http stack experiences encoding problems or malformed requests.
For Jira with log4j2 edit log4j2.xml:
For earlier versions of Jira with log4j 1, edit log4j.properties and add:
For Confluence with log4j1:
Then add the same part as in last message into web.xml (webapp/WEB-INF/web.xml):
SAML or OIDC redirect back to /plugins/servlet/no.kantega.saml/sp/{idp-id}/login responds with 403 error
If the request returning from the IDP back to /plugins/servlet/no.kantega.saml/sp/{idp-id}/login is visible in the Tomcat catalina.out log, but does not reach the application itself (Jira, Confluence, Bitbucket, Bamboo), since only Tomcat logs the request but not the host app or Kantega SSO plugin logs, then the issue is most likely another filter installed in Tomcat with configuration in web.xml file.
An example of a filter that may stop a request is CORS filter like org.apache.catalina.filters.CorsFilter
Related article on configuration of CorsFilter with Confluence can be found here:
https://jira.atlassian.com/browse/CONFSERVER-41269
Tomcat documentation:
https://tomcat.apache.org/tomcat-9.0-doc/config/filter.html#CORS_Filter
What to do if you get an AWS-related session problem?
We sometimes see that AWS load balancer, when used in front of a multi-node cluster (of Confluence, Jira et al.), has problems retaining session stickiness. It seems to improve stability of a clustered setup by enabling application stickiness in AWS load balancer configured to the cookie used in your application (by default cookie is named JSESSIONID). See more about this here: https://docs.aws.amazon.com/elasticloadbalancing/latest/application/sticky-sessions.html#application-based-stickiness.
Tycical symptoms for this problem can be:
login loops
login session suddenly dropping
AWS cookie
AWSALB
suddenly changing causing node change for browser which again typcally causes login session to drop (user gets logged out)
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, Kantega SSO will not log in users. Users are presented with the default product login page. The KSSO admin panel will still function and will show a notification that the license is invalid.
How does the features in Kantega SSO look in a architectural diagram?
Below is a diagram that shows many of the features in Kantega SSO.