OpenID Connect Client Creation in Keycloak
- Joseph Kinyanjui
In order to use the plugin you have to create an OpenID Connect client. This page describes how to create a client in Keycloak. If you wish to use the plugin with a different OpenID-connect provider please consult the manual of that provider.
Creating a new Client
Before creating the client make sure you are in the realm you want use for Jira/Confluence authentication. You can change the realm by clicking on the arrow below the Keycloak logo on the top left of the screen. To create a new client select the Clients menu on the left and then click Create. You will be prompted for a Client ID, a Client Protocol and a Root URL. A good choice for the client ID is the name of your application (jira, confluence or Bitbucket), the client protocol should be set to openid-connect and the root URL should be set to the URL under which Jira/Confluence/Bitbucket will be accessible (eg. https://jira.yourcompany.com/).
After saving you will be presented with the client configuration page where you can assign a name and description to the client if desired. The plugin uses Standard Flow for authentication, therefore all other flows (Implicit Flow and Direct Access Grants) can be disabled unless you want to enable REST authentication via SSO in which case Direct Access Grants needs to be enabled. The Root and Valid Redirect URLs should have already been set in accordance to the Root URL specified in the earlier step.
To allow for seamless background refreshing of user sessions, enter the Base URL of the Jira/Confluence/Bitbucket server (https://jira.yourcompany.com) in the Allowed-Origins field.
You can choose whether you want client access to Keycloak to be public or confidential and have to set the Access Type accordingly. Confidential clients are recommended to secure access to your Keycloak instance. After selecting confidential and saving the Credentials tab becomes available in which you can view and regenerate the secret used to authenticate. This secret in combination with the client ID is required for authentication and has to be specified on the plugin configuration interface (→ Setup & Configuration).
For more information on how to configure the clients in Keycloak please consult the documentation.
Further Configuration
It may be necessary to configure additional aspects of Keycloak in order for the plugin to work for your specific setup.
Username, Full Name and Email
The plugin uses the preferred_username claim in the ID token as username when logging in or creating new users. In Keycloak the username property is mapped to this field by default. You may want to change this if you want a different property to be used as username for the Jira/Confluence users. Please note that the preferred_username field is assumed to be constant for a user by the plugin, so please set up the desired username before configuring the plugin. The mapping of the field can be changed under the Mappers tab of the Jira/Confluence client by configuring the username Token mapper.
Similarly the name and email claims are used as full name and email. You can also set up mappers to use different fields in Keycloak to fill these claims.
Groups
The plugin has the ability to synchronize groups from Keycloak to Jira/Confluence/Bitbucket. This functionality is used when the plugin creates new users or updates groups for existing users on login. The plugin can use the Keycloak client roles as well as other custom claims to set the groups in Jira/Confluence/Bitbucket. These claims have to be set up for the group synchronisation to work properly. A guide on how to set up client roles for group synchronization can be found here.