[Legacy] Keycloak

This guide is for an older version of Kantega SSO Enterprise and is no longer maintained. New guides are here: https://kantega-sso.atlassian.net/l/c/rNTaTonz .

This guide takes you through the steps of setting up Keycloak login to the following Atlassian applications:

  • Jira SERVER DATA CENTER

  • Confluence SERVER DATA CENTER

  • Bitbucket SERVER DATA CENTER

  • Bamboo SERVER

  • Fisheye / Crucible SERVER

 

 

You find a link to Atlassian Marketplace in the upper right corner of your Atlassian application. Click Manage apps and search for “Kantega”. Click “Free trial” or “Buy now” to install the app.

 

 

Add identity provider

A welcome message is shown when you select to configure the app for the very first time. Click “Start setup” and then “Setup SAML / OIDC”.

Select “Keycloak” in the identity provider gallery.

Keycloak allow you to setup single sign-on over both SAML and the OpenID Connect protocol. This knowledge base article describe the practical differences of these two protocols.

In the first wizard step, you select which SSO protocol to use. Click “Next”. Follow the protocol specific setup guides below.

 

1. Select provisioning method

The Atlassian applications needs to have information about users logging in and their permissions. At this wizard step, we choose whether user and permission data already exist when users log in with SSO or if user records should be created dynamically (just-in-time provisioning).

You can also specify whether users logging in through Keycloak should be added as members to a set of default groups automatically. Alternatively, you can also retrieve and assign group memberships individually based on attributes in the SAML response. Such configurations are available after the initial setup.

Select whether users already exist or if you wish to have users automatically created upon login. If using LDAP-provisioning, select "Accounts already exist in JIRA when logging in". 

Otherwise, select the second option to enable just-in-time provisioning. Note that for users to be created, a name, username and an email must be sent in the SAML response (see instructions on configuring Mappers later in this guide.)

Optionally assign a default group for new users - all new users will be added to that group.

This can all be further configured and changed after initial setup, as well.

Select provisioning method, default groups and click “Next”.

 

2. Configure identity provider

Sign in to the keycloak admin console.

Select the correct realm (we are using example.com).

Select Clients, then Create.

  • In Client ID, paste the ACS URL from the prepare step in the Kantega SSO wizard.

  • Select SAML as the Client Protocol.

  • Press Save.

In Settings

  • Set Client Signature Required to Off

  • Paste the ACS URL  into the following fields:

    • Valid Redirect URIs.

    • Master SAML Processing URL.

Mappers (Just-in-time provisioning)

If you intend to use JIT provisioning to create user accounts the first time they log in, you will need to configure Mappers. Mappers make Keycloak include the requisite SAML Response attributes (email and name). If users already exist in JIRA (using LDAP or some other means of provisioning), you can skip this step.

Open the Mappers tab. We are going to add:

  • lastName

  • givenName

  • email

  • managed groups sent via SAML response

Create mapper for lastName:

Create mapper for givenName

Create mapper for email:

Mappers (Managed Groups)

If you intend to use Managed groups (manage Jira groups from Keycloak), you also need a mapper for group claims. If not, you can skip this step.

Create mapper for https://kantega-sso.atlassian.net/wiki/spaces/KSE/pages/55935147:

 

3. Import metadata

Go back to the KSSO setup wizard tab. On the metadata import step, provide the metadata URL (recommended): https://<keycloak.example.com>/auth/realms/<example.com>/protocol/saml/descriptor

  • Substitute <keycloak.example.com> with the DNS of your keycloak server.

  • Substitute the realm identifier <example.com> with your realm.

Alternatively, you can also download the metadata file to disk and upload it in the KSSO wizard.

Keycloak v. < 6 has a known bug in the SAML meta data files found under the installation tab in the Keycloak client settings (KEYCLOAK-3373). Use the link above to access proper SAML metadata.

Press Next once you have uploaded the metadata.

On the Location step, give the Identity Provider a name (this name is visible to end users when logging in). Click Next.

Review the imported signing certificate (this step is purely informational). Click Next.

Review the setting and click Finish.

8. Test and verify setup

On the next page you will be given a link to perform a test of your setup.

The test verifies that users are allowed to authenticate with the current configuration, and you get feedback on whether the current user is found in Atlassian application. You are also able to fix user lookup issues (selecting the right username attribute and express username transformation rules) and select data attributes for just-in-time provisioning here. More info about testing av verifying identity provider configurations.

6. Redirection mode

By default, Kantega SSO Enterprise will forward all users to the configured identity provider. However, you can configure both a subset of users who should be login through this identity provider and how they are redirected. More about configuration of redirection rules.

1. Select provisioning method

The Atlassian applications needs to have information about users logging in and their permissions. At this wizard step, we choose whether user and permission data already exist when users log in with SSO or if user records should be created dynamically (just-in-time provisioning).

You can also specify whether users logging in through Keycloak should be added as members to a set of default groups automatically. Alternatively, you can also retrieve and assign group memberships individually based on attributes in the SAML response. Such configurations are available after the initial setup.

Select whether users already exist or if you wish to have users automatically created upon login. If using LDAP-provisioning, select "Accounts already exist in JIRA when logging in". 

Otherwise, select the second option to enable just-in-time provisioning. Note that for users to be created, a name, username and an email must be sent in the SAML response (see instructions on configuring Mappers later in this guide.)

Optionally assign a default group for new users - all new users will be added to that group.

This can all be further configured and changed after initial setup, as well.

Select provisioning method, default groups and click “Next”.

2. Callback URL

The field “Callback URL” will be needed when configuring your identity provider. Copy this URL value (We will make use of this in the next step)

3. Configure identity provider

Sign in to the keycloak admin console.

Select the correct realm (we are using example.com).

Select Clients, then Create.

  • In Client ID field, give the client a unique name.

  • Select openid-connect as the Client Protocol.

  • Insert the base url to your Atlassian application in the Root URL field (in the example below, we have a Jira instance available at issues.example.com).

  • Press Save.

 

Give the client a name (in the example below we call it “My Jira”), and set the Access Type to confidential. You can also paste in the callback url from the Kantega SSO wizard in the “Valid Redirect URIs”, to make the set here more strict. Click Save.

 

Mappers (Managed Groups or Auto create groups)

If you intend to use Managed groups (manage your users' group meberships in Keycloak) or Auto create groups, you also need a mapper for group claims. If not, you can skip this step.

Create mapper for:

  • Set Name and Friendly Name to Group 

  • Set Group attribute name to “Groups”

  • Set Full group path to OFF

4. Import metadata

Go to the Import step in the Kantega SSO setup wizard. Complete the discovery URL by inserting the host url and realm name. Click Next.

5. Identity provider name

Fill in a name for your configuration, by default this is “Keycloak”. Click “Next

6. Client id and secret

In this step, we will insert client credentials from Keycloak.

The client ID is found in the Setting tab, while the secret is found in the Credentials tab in the client settings.

Copy these values into the field above.

 

Click “Next”, and you will see a summary page of your Kantega SSO setup.

7. Summary

Validate your setup and click “Finish”.

 

8. Test and verify setup

On the next page you will be given a link to perform a test of your setup.

The test verifies that users are allowed to authenticate with the current configuration, and you get feedback on whether the current user is found in Atlassian application. You are also able to fix user lookup issues (selecting the right username attribute and express username transformation rules) and select data attributes for just-in-time provisioning here. More info about testing av verifying identity provider configurations.

6. Redirection mode

By default, Kantega SSO Enterprise will forward all users to the configured identity provider. However, you can configure both a subset of users who should be login through this identity provider and how they are redirected. More about configuration of redirection rules.