- Home
- OAuth SSO
- OAuth SSO Documentation
- OAuth/OpenID Single Sign On (SSO) into Confluence using Keycloak
OAuth/OpenID Single Sign On (SSO) into Confluence using Keycloak
Confluence OAuth/OpenID app gives the ability to enable OAuth/OpenID Single Sign-On for Confluence. Confluence is compatible with all OAuth/OpenID Providers. Here we will go through a guide to configure SSO between Confluence and your OAuth/OpenID Provider. By the end of this guide, users from your OAuth/OpenID Provider should be able to log in and register to Confluence.
Try it for freeVideo Setup Guide
Pre-requisites
To integrate your OAuth/OpenID provider with Confluence, you need the following items:
- Confluence should be installed and configured.
- Confluence Server is https enabled (optional).
- Admin credentials are set up in Confluence.
- Valid Confluence Server and Data center Licence.
Download and Installation
- Log into your Confluence instance as an admin.
- Navigate to the settings menu and Click Manage Apps.
- Click Find new apps or Find new add-ons from the left-hand side of the page.
- Locate Confluence OAuth/OpenID Connect Single Sign On (SSO), Confluence SSO via search.
- Click Try free to begin a new trial or Buy now to purchase a license for OAuth/OpenID Connect for Confluence SSO.
- Enter your information and click Generate license when redirected to MyAtlassian.
- Click Apply license.
Step 1: Set Up Keycloak as OAuth Provider
Follow the following steps to configure Keycloak as IdP to achieve Keycloak SSO
Select Keycloak version:
Pre-requisites : Download And Installation
- First of all, Download Keycloak and install it.
- Start the keycloak server based on your keycloak version. (See table below)
| For the Keycloak Version 16 and below |
Go to the Root Directory of keycloak bin standalone.bat |
| For the Keycloak Version 17 and above |
Go to the Root Directory of keycloak bin kc.bat and run the below commands.
|
Configure Keycloak as IdP
- Navigate to the plugin configuration page, click the "Add New Provider" button (located either in the middle or top-right corner), select Keycloak as the application, and copy the callback URL from the plugin and keep it handy, as you'll need it to configure Keycloak as the OAuth provider.
- Add Realm : Now login to keycloak administration console and navigate to your desired realm. You can add new realm by selecting Add Realm option.
- Create realm: Enter Realm Name and keep the realm name handy as it will required later to configure the Realm under the plugin. Click on CREATE to add realm.
- Create OpenID client: Click on the Clients and choose create to create a new client. Enter client id and select client protocol openeid-connect and select Save.
- Change Access type: After client is created change its access type to confidential.
- Enter Valid Redirect URIs: Copy callback URL from plugin and then click on
SAVE. Ex -- https://
/oauth/callback - Get Client Secret: Now we need to get client secret. So select Clients and select credentials and copy your secret from here.
- Plugin Configuration: Enter copied Client Secret under Client secret field in the OAuth Client plugin, and enter the Client Name under the Client ID field.
- Add User: We need to add users to realm who will be able to access the resources of realm. Click on the Users and choose to Add a new User.
- User Configuration: After user is created following action needs to be performed on it.
- Map User: We need to map user to a role. Click on Role Mappings and assign the user desired role from available roles and clicking on add selected.
- Create ROLE: The Role will be used by your applications to define which users will be authorized to access the application. Click on the Roles and choose Add Role.
- Create groups: Click on the Groups and choose New to create a new group.
- Assign user to group: Select the user whom you want to add in group. Choose Groups option from tab and then select the group-name and click on join.
- Keycloak Group Mapper: Now to get group details we need to perform its client mapping with group membership else group details will not be fetched. So in Client section, select your client and then click on mapper->create.
- Now, select mapper type as Group Membership and enter the name and token claim name i.e the attribute name corresponding to which groups will be fetched. Turn Off the full group path, Add to ID token and Add to access token options, and click on Save.
- Keycloak Role Mapper: Now to get role details we need to perform its client mapping with role membership else role details will not be fetched. So in Client section, select your client and then click on mapper->create.
- Now, select mapper type as user realm Role Membership and enter the name. and token claim name i.e the attribute name corresponding to which groups will be fetched. Add to ID token and Add to access token options, and click on Save.
- Navigate to the plugin configuration page, click the "Add New Provider" button (located either in the middle or top-right corner), select Keycloak as the application, and copy the callback URL from the plugin and keep it handy, as you'll need it to configure Keycloak as the OAuth provider.
- Add Realm : Now login to keycloak administration console and navigate to your desired realm. You can add new realm by selecting Create Realm option.
- Create realm: Enter Realm Name and keep the realm name handy as it will required later to configure the Realm under the OAuth Client plugin. Click on CREATE to add realm.
- Create OpenID client: Click on the Clients and choose Create Client to create a new client. Enter Client id and select client protocol openeid-connect and Click Next.
- Enable the Client Authentication and Authorization toggle.
- Scroll down to the Access settings and enter your Callback/Redirect URL which you will get from your plugin present on your Client side under the CallBack URLs text-field.
- Go to the Credentials tab, copy the Client Secret and keep it handy as we will require it later while configuring plugin.
- Plugin Configuration: Enter copied Client Secret under Client secret field in the OAuth Client plugin, and enter the Client ID under the Client ID field.
- After Plugin Configurations, go to Client Scopes to configure the Group Mapper and create a client scope.
- Enter Name:- “Group” and Save.
- After saving, click on “Mappers” and configure a new Mapper.
- Select “Group Membership”
- Enter the Name, Token claim name and disable “Full group path” and Save.
- Then go to “Clients” and select your Client ID.
- Go to Client scopes and Add client scope.
- Select the client scope and Add (default).
- Add User: We need to add users to realm who will be able to access the resources of realm. Click on the Users and Click on Create new user to Add a new User.
- User Configuration: After user is created following action needs to be performed on it.
- Map User: We need to map user to a role. Click on Role Mappings and assign the user desired role from available roles.
- Create ROLE: The Role will be used by your applications to define which users will be authorized to access the application. Click on the Roles and choose Create Role.
- Navigate to the plugin configuration page, click the "Add New Provider" button (located either in the middle or top-right corner), select Keycloak as the application, and copy the callback URL from the plugin and keep it handy, as you'll need it to configure Keycloak as the OAuth provider.
- Add Realm : Now login to keycloak administration console and navigate to your desired realm. You can add new realm by selecting Create Realm option.
- Create realm: Enter Realm Name and keep the realm name handy as it will required later to configure the Realm under the OAuth Client plugin. Click on CREATE to add realm.
- Create OpenID client: Click on the Clients and choose Create Client to create a new client. Enter Client id and select client protocol openeid-connect and Click Next.
- After Plugin Configurations, go to Client Scopes to configure the Group Mapper and create a client scope.
- Enter Name:- “Group” and Save.
- After saving, click on “Mappers” and configure a new Mapper.
- Select “Group Membership”
- Enter the Name, Token claim name and disable “Full group path” and Save.
- Then go to “Clients” and select your Client ID.
- Go to Client scopes and Add client scope.
- Select the client scope and Add (default).
- Enable the Client Authentication and Authorization toggle.
- Scroll down to the Access settings and enter your Callback/Redirect URL which you will get from your plugin present on your Client side under the CallBack URLs text-field.
- Go to the plugin and copy the Client Secret and keep it handy as we will require it later while configuring plugin.
- Plugin Configuration: Enter copied Client Secret under Client secret field in the plugin, and enter the Client ID under the Client ID field.
- Add User: We need to add users to r+ealm who will be able to access the resources of realm. Click on the Users and Click on Create new user to Add a new User.
- User Configuration: After user is created following action needs to be performed on it.
- Map User: We need to map user to a role. Click on Role Mappings and assign the user desired role from available roles.
- 1) Setting a password for it so click on Credentials and set a new Password
for the user.
NOTE : Disabling Temporary will make user password permanent.
Step 1.1: Steps to fetch Keycloak Groups [Premium]
Note: -- If full path is on group path will be fetched else group name will be fetched.
Step 1.2: Steps to fetch Keycloak Roles [Premium]
- 1) Setting a password for it so click on Credentials and set a new Password
for the user.
NOTE : Disabling Temporary will make user password permanent.
x
- 1) Setting a password for it so click on Credentials and set a new Password
for the user.
NOTE : Disabling Temporary will make user password permanent.
Step 2: Set Up Confluence as OAuth Client
- Go to Confluence Manage Apps -> click Configure under OAuth/OpenID Connect (OIDC) for Confluence SSO. Then click on Add New Provider button. Select Keycloak as your OAuth provider.
- enter copied Client ID, Secret in the plugin.
- Enter the Host Name (Base URL of the Keycloak server For eg. http://example.com) and Realm Name you copied from the keycloak server.
- Finally, click on Test Configuration to verify the accuracy of the provided details.
- Additionally, you can provide the JWKS Endpoint URL or Public Key for signature validation. You can find this option under the Advanced Settings tab.
Step 3: User Profile Mapping
Navigate to the User Profile section at the top to configure user profile attributes for Confluence. If your user directory is read-only, disable the User Profile Mapping option in this tab and then proceed directly to the “Matching a User” step.
Click on Test Configuration.
User Attribute
Matching
When a user logs into Confluence, data or attributes from the OAuth/OpenID provider are used to search for that user in Confluence and facilitate login. To match the attributes:
- Navigate to the User Profile tab.
- Choose either Username or Email as the login for the Confluence user account.
- Enter the attribute name from the OAuth/OpenID Provider that corresponds to the Username or Email as identified in the Identifying Correct Attributes step.
Extended Attribute Mapping
You can configure additional user attributes received in the OAuth/OpenID response using the Configure User Properties (Extended Attributes) section.
- In the left dropdown, select the Confluence attribute you want to map as User Property Key (for example: Phone, Location).
- In the right field, input the corresponding value retrieved from the Attributes from Provider in the Test Configuration window.
- For example, to map user location: select Location on the left dropdown and enter the provider attribute name that returns the user’s location on the right.
- Click Add Attribute Mapping again to create additional mappings.
Step 4: User Group Mapping
As we proceed to configure user group attributes for Confluence, you have the option to enable group mapping.
If you wish to do so, please ensure to select Enable Group Mapping in the User Groups tab. Alternatively, you can proceed directly to setting the default group.
4.1 Setting the Default Group
- In the User Groups tab, select the default group for users. If no group is mapped, users are automatically added to this group.
- Using the Assign Default Group To option, you can assign default groups to all users or new users. Choose None if you prefer not to assign any default group to SSO users.
4.2 Finding Group Attribute
- To identify group Attribute, click on Test Configuration. Review the values returned by your OAuth/OpenID provider to Confluence in the table. If group values are missing, adjust the settings in your OAuth provider to include group names.
- Check Enable Group Mapping option if you disable this then group mapping wont be updated for existing users.
4.3 Group Mapping
Group mapping can be done manually or on the fly:
- Manual group mapping: If the names of groups in Confluence are different than the corresponding groups in OAuth/OpenID Provider, then you should use Manual group mapping.
- On-The-Fly group mapping: If the names of groups in Confluence and OAuth/OpenID Provider are same, you should use On-The-Fly group mapping.
I. Manual group mapping
- Check the Allow User Creation based on Group Mapping option if you want new users to be created only if at least one of the user's OAuth/OpenID Provider groups is mapped to a group in the application.
- Select a Confluence group from the dropdown list and enter the name of the OAuth/OpenID Provider group to be mapped in the Groups from Applications textbox.
- For instance, if you want all users in the 'dev' group of OAuth/OpenID providers to be added to Confluence-software-users, you will need to select Confluence-software-users from the dropdown and enter 'dev' against Confluence-software-users.
- If you want to add extra mapping fields, click on Add Groups button.
II. On-The-Fly group mapping
- If the group names in both Confluence and the OAuth/OpenID provider match, opt for On-The-Fly group mapping.
- Check the Create New Groups option to create new groups from the OAuth/OpenID Provider if not found in Confluence.
- Preserve existing user groups by selecting the Keep Existing User Groups option. Unticking this option will remove the user from a Confluence group if it's not present in the OAuth/OpenID response. However you can exclude some groups from removal in the exclude groups field
Step 5: Advanced SSO Configurations
- Enable PKCE to enhance security by adding an extra layer of protection to the OAuth flow, preventing authorization code interception attacks.
- Allow User Creation:- Enabling this will allow you to create new users through SSO.
- Directory for New User:- After a successful SSO, if the user is not found in Confluence , a new user account will be created in the selected user directory.
- Remote Directory Sync:- The user details will be synced from the remote directory on successful SSO only if the user exists in the remote directory.
- ACR Value: Requests additional information from the OpenID provider to determine the Level of Assurance for user authentication.
- State Parameter: Protects against CSRF attacks by sending a unique, non-guessable value with the authorization request, mandatory for certain providers.
- Add Custom Parameters: Allows the inclusion of extra parameters in the authentication request.
Step 6: SSO Setting
The configurations within the SSO Settings tab are pivotal in shaping the user experience for Single Sign-On.
6.1 Sign In
Settings
- Enable Auto Redirect to Application to redirect users to the OAuth/OIDC provider when accessing the Confluence login page. You can set a delay before redirection.
- Next, toggle the Enable Backdoor Login option for emergency access using a backdoor URL. Restrict access to this URL for specific groups if needed.
- You can use Domain Restriction to allow login for specific user domains and configure multiple allowed domains (semicolon-separated).
- The Secure Admin Login option ensures the re-authentication of admin users before accessing pages with administrative permissions.
6.2 Redirection Rules
- Redirection rules allow you to redirect users to login page or providers based on their email domains, groups, or directories. This functionality is especially useful when multiple providers are configured
- To create a new rule, go to the Redirection Rules tab and click Add Your First Rule.
- Next, give the rule a name and set the conditions for redirection. Click Save Rules once you’re done.
- You can also set a default rule if no other rule conditions are met.
- Once you set a redirection rule, users who fulfill its conditions will be shown a login form, prompting them to input their username/email address. You can set domain-based rules for directing users to specific providers as well.
6.3 Session Management
- Enable User Session Management option to set Remember Me-Cookie to keep users logged in until they are explicitly logged out.
6.4 Look and Feel
These settings will allow you to change the look and feel of the login page and error message. To access these settings click on the Look and Feel tab from the left sidebar.
- You can customize the default login button text as well as you can completely design the login page using a customizable template.
- The SSO Error Message section allows you to modify how error messages will be displayed to your users.
6.5 Post Logout Configurations
- If you want to redirect users to an URL after they log out then you can use Custom Logout URL under Post Logout Configuration tab.
- Similar to the customizable login template, you can also design the Logout page to improve the user experience.
6.6 Global SSO Settings
- SSO can be enabled/disabled from the Global SSO Settings tab in the left sidebar.
- You can change additional settings as Allow Users to Change Password, Restrict access to plugin APIs and Auto Activate Users on SSO.
Additional Resources
Did this page help you?
