Keycloak (SAML)

Prior to this guide, User Federation with LDAP has been set up in Keycloak, against the Active Directory domain example.com. This allows user provisioning of the same users and groups into Jira/Confluence/etc using an LDAP user directory. If you cannot use LDAP, you will need to use SAML JIT provisioning instead. This makes Kantega SSO create new users in Internal Directory the first time they log in. We'll get into the details later.

We have used userPrincipalName as the Keycloak username attribute. These settings are found under User Federation for the example.com realm in Keycloak.

Settings:
Username LDAP attribute: userPrincipalName
RDN LDAP attribute: userPrincipalName

Mappers:
LDAP Mappers,username, LDAP Attribute: userPrincipalName

Open

In KSSO, add a new identity provider, selecting “Keycloak" from the dropdown:

Open

In the Prepare step, Copy the ACS URL value and save it for later. Press Next.

Open a separate browser tab and log into 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 KSSO Prepare step.

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

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:

If you intend to use Managed groups with JIT provisioning, 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:

• Set Name and Friendly Name to Group 

• Set Group attribute name to http://schemas.xmlsoap.org/claims/Group

• Set Full group path to OFF

Now that the client and optionally mappers have been configured, 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.

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

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

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 SAML JIT 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 further earlier 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.

Press Next.

Review the summary, then press Finish.

You should now be able to test SAML login with Keycloak.