User Creation & Group Management
- Joseph Kinyanjui
Our plugin supports the automatic creation of new users in Jira/Confluence/Bitbucket as well as the synchronization of groups for existing users. To enable both features, see the respective configuration settings Create User on Login and Update Group Memberships on Login (→ Setup & Configuration).
For the creation of new users on authentication the plugin uses the username, email and full name given by the OpenID-connect provider in the preferred_username, email and name claims of the ID token. The groups are synchronised according to the Custom Groups Claim option. For Keycloak the client roles assigned to the user (→ Keycloak documentation on client roles) are used by default. This claim is used for the group assignments on the initial user creation as well. If you plan on using user creation or group membership synchronisation make sure to set up the claim in the access token before enabling these options.
Setting up Client Roles
Client roles are a simple way to manage group memberships in Jira/Confluence/Bitbucket with Keycloak.
Specific client roles can be easily created using the Keycloak configuration interface: The menu can be accessed by selecting Clients, then choosing the Jira/Confluence/Bitbucket client and clicking on the Roles tab. Here new client roles can be created and existing ones can be modified. The names of the client roles have to correspond to the group names in Jira/Confluence, otherwise they will be ignored. Default groups are jira-software-users and jira-servicedesk-users for Jira, confluence-users for Confluence and stash-users for Bitbucket. The administrator groups are jira-administrators and confluence-administrators, respectively. Of course you can create additional groups in Jira/Confluence/Bitbucket manage your users.
These client roles can be directly assigned to a user by selecting Users, then choosing the user and clicking on the Role Mappings tab. The Jira/Confluence client can then be selected under Client Roles and the available roles will be listed.
In most setups the user roles will be available as realm roles (→ Keycloak documentation on realm roles), either set up manually (under Roles → Realm Roles) or synchronized from a LDAP user federation (User Federation → LDAP). In this case mappers can be set up to map realm roles to the corresponding client roles. A mapper can be created under Clients → Jira/Confluence/Bitbucket client → Mappers. For mapping realm to client roles a Role Name Mapper has to be created: Select the realm role you want to map to a Jira/Confluence group as Role and set the New Role Name to client.group, where client is the name of your Jira/Confluence/Bitbucket client in Keycloak (usually jira, confluence or Bitbucket) and group is the name of the group you want to map the realm role to. This way a general administrators group can be mapped to jira-administrators for the Jira client, confluence-administrators for the Confluence client.
Using other Access Token claims
In the Groups Settings tab of the plugin configuration you can specify other claims in the access token to be used for group synchronisation. In Keycloak this enables you to use client roles of other clients as well as realm roles as groups. You can also set up custom mappers to populate access token claims.
For other OpenID Connect providers claim to set as Custom Groups Claim depends on the provider. In order for this option to be available the provider has to serve JWT access tokens. Then any string array claim can be used as group membership list.
Synchronisation of the administrator groups
The administrator groups jira-administrators and confluence-administrators can be synchronized to Jira/Confluence like any other group. But if a user in either of these groups tries to change system settings or manage users, they will usually be prompted for a password. This additional security mechanism is called WebSudo. This can cause problems in setups where new administrators are created by the plugin. See Troubleshooting → Additional Authentication required for Administrators for more information.