Configure SAML Single Sign-On (SSO) for Jira Using Keycloak

 2.1: Service Provider Metadata

If you intend to customize your IDP setup from the start, you can find the required Service Provider (SP) metadata under the SP Metadata section. It contains essential information about your SP configuration that you will need to provide to your IDP for seamless integration.

There are multiple ways to add this metadata to your IDP:

 2.1.1: Importing the metadata

• Depending on how your IDP accepts the metadata, you can either provide the metadata URL or you can use the Download Metadata button to download an XML file for the same.

 2.1.2: Manually add the metadata

If you wish to add the metadata manually, you will find the following information in this section. You will need to provide these details to your IDP.

• SP Entity ID
• ACS URL
• SP Certificate

 2.2: Configuring Your Identity Provider

The manual setup flow allows you to dive into the complete set of configurations provided by the plugin to add a SAML IDP.

The steps to configure an IDP using the Manual Setup option are:

 2.2.1: Adding IDP Metadata

There are three ways you can configure IDP settings with the information you have been given by your IDP team:

 2.2.1.1: By Metadata URL

• Click on the Import from Metadata tab.
• Select IDP – Import From Metadata URL.
• Enter IDP metadata URL – paste the metadata URL that we fetched before initiating the Service Provider .
• If your IDP changes certificates at intervals (Eg. Azure AD), you can refresh your IDP metadata accordingly:
• Navigate to the Advanced SSO options from the menu on the left-hand side of the page.
• Enter your metadata URL in the Certificate Rollover field.
• Toggle the Refresh Certificate periodically option on.
• Use the drop-down provided to set the interval for a periodic refresh. We recommend you select five minutes for the best results.
• Click Import.


 2.2.1.2: By Uploading Metadata XML File

• Click on the Import from Metadata tab.
• Select IDP: Import from Metadata File.
• Upload metadata file.
• Click Import.


 2.2.1.3: Manual Configuration

Go to Manual Configuration tab and enter the following details:

• IDP Entity ID.
• Single Sign On URL.
• Single Logout URL.
• X.509 Certificate.


Note: If you need to add an additional X.509 Certificate, you can do so by clicking on the Add button below the textbox.

 2.3: User Profile

• Next we will be setting up user profile attributes for Jira. The settings for this can be found in the User Profile section.


 2.3.1: Finding correct attributes

• Go to the IDP Configuration section. Scroll down and click on Test Configuration.
• You will see all the values returned by your IDP to Jira in a table. If you don't see value for First Name, Last Name, Email, or Username, change the required settings in your IDP so that it returns this information.
• Once you see all the values in Test Configuration, keep the window open and go back to the User Profile section.

 2.3.2: Setting profile attributes

• In the User Profile section, fill the values by matching the name of the attribute. For instance, if the Attribute Name in the Test Configuration window is NameID, enter NameID against Username.
• For user registration, ensure both the Username and Email fields are set up. If you're only allowing existing users to log in, configure the attribute that will match the user in Jira.

 2.3.3: Matching a user

When a user logs into Jira, one of their attributes from the IDP is used to search for their account. This enables Jira to detect the user and log them into the corresponding account.

You can configure it using the steps given below:

• Select Username or Email for the Login user account by option.
• Enter the attribute name from IDP which corresponds to Username or Email using Finding Correct Attributes.

 2.4: User Groups

Now, let's move on to configure user group attributes for Jira. This feature allows you to replicate the user groups present in your IDP within your Service Provider (SP) environment.

You can accomplish this in the following ways:

 2.4.1: Setting default group

• Select the users' Default Group in the User Groups tab. If no group is mapped, users are added to this group by default.
• You can enable default groups for All Users or New Users using the option. Select None if you don't want to assign any default group to SSO users.


 2.4.2: Finding Group Attribute

Similarly to how you identified the Attribute Names for User Profiles, you will need to locate the attribute name corresponding to group information.

Here’s how you can do this:

• Go to the IDP Configuration section. Scroll down and click on Test Configuration.
• A table will display all the values returned by your IDP to Jira. If you don't see group information in this table, you'll need to adjust your IDP settings to ensure it returns the appropriate group names.
• In the User Groups tab, enter the Attribute Name for groups in the Group Attribute field.
• Enter the Attribute Name of the group against Group Attribute.
• If you don't want to update groups of existing users, check the Disable Group Mapping option.

 2.4.3: Group Mapping

Group Mapping can be done in two ways:

 2.4.3.1: Manual Group Mapping

• If the names of groups in Jira are different from the corresponding groups in IDP, then you should use Manual group mapping.
• Check Restrict User Creation Based on Group Mapping option if you want new users to be created only if at least one of the user's IDP groups is mapped to a group in the application.
• To do the mapping, first select a Jira group from the dropdown which lists all groups present in Jira and then enter the name of the IDP group to be mapped in the textbox beside.
• For example, if you want all users in the 'dev' group in IDP to be added to Jira-software-users, you will need to select Jira-software-users from the dropdown and enter 'dev' against Jira-software-users.
• Use '+1' and '+10' buttons to add extra mapping fields.
• Use the '-' button next to each mapping to delete that mapping.


  2.4.3.2: On-The-Fly Group Mapping

• If the names of groups in Jira and IDP are the same, we recommend you use On-The-Fly group mapping.
• Check Create New Groups option if you want new groups from IDP to be created if not found in Jira.
• If the user is part of some group in Jira and that group is not present in the SAML response returned by IDP, then the user will be removed from that group in Jira.
• If you don't want On-The-Fly group mapping to affect Jira groups which are managed locally then add those groups in the Exclude Groups field.

 2.5: Troubleshooting and Support

• You can verify if your SAML SSO configuration is correct by clicking the Test Configuration button on the IDP configuration tab of the plugin.
• After a successful test configuration, you will be able to review the results on the Troubleshooting and Support page. This includes the attributes received from your Identity Provider (IDP), the SAML request sent, and the SAML response received.
• In case you encounter any issues or errors while setting up your IDP, refer to the Troubleshooting section for guidance on how to contact our support team.