Important Update Effective February 1, 2024!
Due to recent changes in Jira and Confluence, we've made the tough decision to discontinue the OpenID Connect (OIDC)/OAuth app and no longer provide new versions for the newest Jira/Confluence releases as of January 31, 2024.
This is due to some necessary components no longer shipping with Jira/Confluence, which would require some extensive rewrites of the OIDC App.
Important Update! This app will be discontinued soon!
Due to recent changes in Jira, which no longer ships with some components required for our Read Receipts app to run, we've made the tough decision to discontinue the app, as of Februar 5, 2025.
Important Update! This app will be discontinued soon!
We've made the tough business decision to discontinue the app, as of January 11, 2025.
Keycloak with User Sync
Goal
Configure SAML Single Sign-On to work with Keycloak, using Just-in-Time provisioning to automatically create and update users during Single Sign On.
Prerequisites
- Identity Provider Keycloak
- Your Atlassian application must be accessible via HTTPS. (read more about it in the Atlassian documentation, i.e. for Jira or Confluence)
Step-by-Step Setup Guide
This setup guide describes how to complete the initial setup for SAML Single Sign On (SSO) Add-on with Keycloak,
applicable for Add-on version starting 3.1.0. If you need any further support, please feel free to contact us here.
Install the SAML SSO app
In your Atlassian product, open the in-product marketplace as described in the Atlassian documentation.
Search for "resolution saml" and click "Install" for SAML Single Sign On (SSO) by resolution Reichert Network Solutions GmbH.
After the installation is complete, click on Manage, then choose Configure.
Now, you are on the Add-on / app configuration page and the first step of the setup wizard will appear.
Configure Keycloak for User Sync
Configuration in the Keycloak Web Console
Login to your Keycloak instance with administrator privileges and enter the Administration Console
Select the realm of the users who should be synchronized and click on Clients in the left-hand navigation bar.
Click on the Create client button of the client view to register a new client for the User & Group Sync connector
Provide a name for the Client ID and make sure that the Client type is OpenID Connect and click on Next.
In the Capability config tab, enable both the Client authentication and Authorization options, and have the other options as the following screenshot, then click on Next:
Keep the settings in the next tab as is, and click on Save.
The following assignment might not be required when registering a client in the master realm.
Switch to the Service account roles tab and click on the Assign role button.
Select "Filter by clients" and search for "manage-users" then click enter. Choose "realm-management / manage-users" and click on Assign.
The settings should look like the below now:
Go to the Credentials tab, and copy the Client secret. You may regenerate it at any time.
Configuration in User & Group Sync Configuration page
Navigate to the administration console for Jira, Confluence, or Bitbucket
Confluence: search for USERS & SECURITY under which you'll find User & Group Sync
Jira: navigate to the User management tab in which you'll find User & Group Sync
Bitbucket: navigate to Administration/ Accounts you'll find User & Group Sync listed here
Click on Add Connector and choose Keyloak Connector.
Set a name, insert your Keycloak URL appending /auth at the end, and provide
- realm name
- client-id
- secret
as per your Keycloak setup earlier. Use the Save and Test Connection button to check if User Sync can connect to Keycloak successfully.
To schedule a periodic synchronization of your Keycloak directory with User & Group Sync, click on Show Advanced Settings at the very bottom of the page.
Enable Scheduled Synchronization needs to be checked, the default cron expression would then cause a sync every day at 2 am.
Click Save and Return to finish the configuration.
You are now ready to commence either a simulated or a full sync. By simulating the sync first you will be able to verify your configuration and see what changes User Sync would apply like what users will be added, modified, or not modified. With the full sync, User Sync will apply those changes. Both sync actions will run a full sync and will have the same sync duration. For more information on the sync simulation please refer to Using the Simulated Sync Feature.
Please read here, if you already have users in your system which you want to migrate, without losing their history. Don't hesitate to reach out to https://www.resolution.de/go/support, if you need any help with achieving this.
Additional Resources:
- User Sync Endpoints
- Group Management- And Filtering With User Sync
- Cleanup Behaviour and Scheduled Synchronization
- How To Migrate An Internal Directory To UserSync
Configure SAML SSO app
Add new Identity Provider (IdP)
Click on Add new IdP to start the wizard.
Adding a new IdP can also be done outside the wizard in the app configuration section Identity Providers
Select Keycloak for the Identity Provider. For the Authentication Protocol keep SAML2.
You may also change the name and add a description. The name needs to be unique.
Click on Next.
Retrieve SAML Metadata for Keycloak Client
The next step enables you to retrieve the information Keycloak needs to work with our SAML SSO app.
Right click on the link highlighted below and save the linked content, a file in xml format.
Click on Next and pause the SAML SSO app configuration for a moment.
Configure Keycloak for SSO
Head over to your Keycloak administration console
Select the realm, if you've more than one configured (this example is using the realm called zizo)
Select Clients and Import client
and use Browse to open the xml file you've saved earlier, then click on Save
Leave the main settings untouched unless you know what to configure beyond standard configuration.
You may now continue with the SAML SSO app configuration.
Import Keycloak IdP Metadata into the SAML SSO for Atlassian Data Center app
You can choose from the following options in the Metadata Upload dropdown
- Help me generate a metadata URL
- I have a metadata URL
- I have a metadata XML file
- I want to past my metadata XML
- I don't have any metadata and want to enter the data manually
The preferred option is 2, using the metadata URL from Keycloak which will allow automatic updates of the metadata later.
You can construct the metadata URL yourself:
https://<your-keycloak-instance-name/auth/realms/<your-realm-in-lowercase>/protocol/saml/descriptor
Opening the URL should reveal an XML file with a first node called <EntitiesDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" Name="urn:keycloak">
In the Import SAML IdP Metadata screen of the wizard, select the following options and paste the URL:
Proceed with the next steps described below.
Configure remaining SAML SSO app settings
User ID attribute and transformation
It's recommended to leave this option checked.
Click on Next.
User creation and update
This part of the configuration defines how users are provisioned in the Atlassian application, during Single Sign On with Keycloak.
- select Update with UserSync-Connector as User Update Method
- check the Reactivate inactive users checkbox, if you want
- select the User Sync connector created earlier
Click Save & Next to proceed as this is all you'll need to do when using User Sync for user provisioning with SAML SSO.
Test configuration of SAML SSO app
As a last step you can test your settings which can be executed by clicking on the corresponding Start test button.
Copy the link displayed and paste it into a new incognito/ private browsing window, and execute a login against Keycloak,
using a user and password which is a member of your realm in Keycloak.
The status of the authentication process is permanently updated in the window.
If there is any error at this point you need help with, please refer to the troubleshooting guide, which will also help us, should you open a support ticket with us.
Of course the test window above will display a lot of information about the errors already, but requires some deeper knowledge of the SAML protocol.
Enable login redirection
The last step is to configure redirect options, which you should only do if the test before succeeded.
Selecting Enable SSO Redirect will ensure that users are getting redirected to be logged in via SAML,
instead via the login form as before the SSO setup.
The Override Logged Out URL Method can be left at the default option.
It will redirect users after log out to a default page where they can login again via username and password or SSO again.
Save & Close to complete the setup and close the wizard. You are now ready to use Keycloak with SAML SSO in your Atlassian application.
If Enable SSO Redirect is enabled, you can login to your Atlassian application manually by browsing to the URL that fits your Atlassian application as listed below.
Use this URL, if you need to login a local user unknown to the ADFS or if there are any issues with Single Sign On.
- Jira: https://<baseurl>/login.jsp?nosso
- Confluence: https://<baseurl>/login.action?nosso
- Bitbucket: https://<baseurl>/login?nosso