Jira Cloud Users & Groups Provisioning: Keycloak Sync Guide (REST API)

 3.1 Application Configuration

• Navigate back to the Configured Application tab on the main dashboard and click the + Add New App button.
• From the Configure Application directory screen, locate and select Keycloak as your chosen provider.

• In the App Configuration wizard > Application Configuration section enter,

Field	Value
Application Name	A unique label for this configuration
Client ID	The Client ID from Keycloak
Client Secret	The secret from the Keycloak Credentials tab
Domain URL	e.g., https://example.keycloak.com
Keycloak Version	The version of your Keycloak server
Realm Name	The Keycloak realm name

 3.2 Provisioning Operations

In the Provisioning Operations section, define your synchronization settings:

• Keycloak Directory: sync all users in the realm.
• Keycloak Groups: sync only users belonging to specific groups.
• Keycloak Roles: sync only users assigned to specific roles (see Step 2).

• Click Save Settings.

Group-Based Sync (optional)

• Enter the names of the Keycloak groups from which you want to sync users.
• Press Enter after entering each group name to add multiple groups. Group names are case-sensitive.
• To sync users from nested groups, enable the Enable Nested Group Sync option.
• When enabled, users from the selected groups and their nested child groups will also be synchronized.

Role-Based Sync (optional)

If you selected Keycloak Roles above, configure the roles in Keycloak:

• In your Keycloak client, open the Roles tab and click Create role. Create the roles you want to sync by.
• Open the Service Accounts Roles tab of the same client.
• Click Assign role, then add the roles the service account needs to read users, for example: view-users, view-clients.

User Operations:

Ensure the Import Users toggle is switched ON. In the Deactivated User Action dropdown, select the action that should be taken when a user is unassigned or deactivated in Keycloak.

Group Operations:

• Switch to Group Operations and enable Import Groups.
• Group operations can be performed either with On-the-Fly Group Mapping or Manual Group Mapping.

1. On the Fly Group Mapping:

• Select this tab to create groups dynamically as it is from IdP to Jira Cloud if they do not exist in Jira and map the users accordingly.
• You can enable the Apply Regular Expressions on Group Names option to transform group names using Regex patterns before mapping them to Jira groups.
• Under Filter Incoming Groups, you can configure how you want to filter group names received from the provider.

2. Manual Group Mapping:

To map groups from your IdP to Jira's native groups, select this tab. When the sync executes, the users from respective groups of the IdP will be mapped to Jira groups as per configuration.

Keep Existing Groups

This setting controls how a user's Jira group memberships are managed during user provisioning and deprovisioning operations performed by the Identity Provider (IdP).

Enabled:

For any new user added to IdP groups, it will be added to Jira groups. But if users are removed from IdP groups, Jira group memberships are preserved in the Jira directory.

• Current Jira groups: jira-software-users, jira-administrators
• Groups received from Keycloak: developers, employees
• Resulting Jira groups: jira-software-users, jira-administrators, developers, employees

No existing Jira group memberships are removed.

Disabled:

During provisioning, deprovisioning, or user unassignment, all existing Jira group memberships are removed except those specified in the Exclude Groups list. During provisioning, the user is subsequently assigned only to the groups received from the Identity Provider (IdP).

• Current Jira groups: jira-software-users, jira-administrators, support-team
• Groups received from Keycloak: developers, employees
• Excluded groups: jira-administrators
• Resulting Jira groups after provisioning: jira-administrators, developers, employees (jira-software-users and support-team are removed because they weren't received from Keycloak and aren't excluded)

After provisioning, the groups jira-software-users and support-team are removed because they are not received from the IdP and are not included in the exclusion list.

Exclude Groups: Use the Exclude Groups option to specify Jira groups that should never be removed during provisioning or deprovisioning operations, such as jira-administrators or org-admins. These groups will always be retained regardless of the user's group assignments in the IdP.

Scheduler Option:

To enable dynamic data synchronization at scheduled intervals, set Automate Synchronization to ON and define the processing interval by entering the desired number of days in the Synchronization Cycle (Days) field.

 3.3 Review and Save Configuration

• On the Review & Submit summary page, review your mapping details across the Application Configuration and Provisioning Operations summary tables to make sure everything looks right.
• Click the Save Configuration button in the bottom right corner.

 3.4 Run the Synchronization

• Return to the Configured App Tab.
• Click Synchronize on your Keycloak app.
• When the sync completes,verify the new and updated users under Jira’s user management section.
• If you set a scheduler in step 3.2, no manual action is needed for future syncs.

 3.5 Verification

• The app profile will appear on your main dashboard.
• Under the actions column for your new entry, run a sync (or wait for the scheduled cycle if the Scheduler is enabled).
• In Jira, navigate to User Management and confirm that users and groups from Keycloak appear in the directory. You can also review sync activity under the Audit Logs tab of the Plugin app.