Skip to main content
Version: 5.21.0

Set Up Single Sign-On (SSO) for Atlassian Products

This guide provides step-by-step instructions for setting up single sign-on (SSO) on Atlassian products, such as Jira and Confluence, using miniOrange and Keycloak.

note

These steps are adapted from The Big Bang Documentation.

Prerequisites​

  • Make sure you have an instance of the Atlassian application (app) (either Confluence or Jira) up and running.
  • Do not log into the Atlassian app until instructed in the following steps.

Initial Setup in Atlassian App (Confluence/Jira)​

Log In as Administrator User​

  1. Navigate to your Atlassian app (Confluence/Jira) and log in as the administrator (admin) user.
  2. Complete the initial settings as prompted. Select "Start with a blank project", if unsure.
  1. Click on the Settings gear icon in the top-right corner.
  2. Select Manage Apps. Note: For Jira, also click Manage Apps on the left side.

Adjust Settings​

  1. Scroll to the bottom, and click Settings.
  2. Uncheck Connect to the Atlassian Marketplace, and click Apply.

Disable Marketplace

Upload miniOrange SSO App​

  1. Click Upload app.

  2. Navigate to and select the miniOrange SSO app suitable for your installation. Download links:

    a. For Jira

    b. For Confluence

Note: Ensure the miniOrange app files are uploaded to an S3 bucket as part of your data transfer.

Activate License​

Paste your valid miniOrange SSO app license key, and click Update.

Keycloak Configuration​

  1. Log in to Keycloak as an admin user.
  2. Make sure to select the appropriate realm.

Create User Groups​

  1. Navigate to Groups under Manage on the left menu.
  2. Create the following groups: Jira-Users, Jira-Admins, Confluence-Users, Confluence-Admins.

Keycloak Groups

Assign Users to Groups​

Any user designated as an admin, must belong to both the Admins and Users groups for the specific application.

Export Groups and Obtain IDs​

  1. Export groups and roles to a JSON file.
  2. Open the JSON file and obtain the IDs for Jira-Users and Confluence-Users.

Create OpenID Connect Clients​

  1. Navigate to Clients, and click Create.
  2. For Client ID, use the pattern structsure_{{ id }}_{{ application_name }} (replace {{ id }} and {{ application_name }} accordingly).
  3. Choose openid-connect as the client protocol.
  4. Click Save.

Additional Client Settings​

  1. Change Access type to Confidential.
  2. Enter the valid redirect URL as indicated in the miniOrange plugin (found under the Configure button).
  3. Save your changes in Keycloak.

Example Redirect URLs:

  • Confluence: https://confluence.example.com/plugins/servlet/oauth/callback
  • Jira: https://jira.example.com/plugins/servlet/oauth/callback

Configure Attribute Mappers​

  1. Navigate to Clients, then go to the Mappers tab.

  2. Add built-in attribute mappers based on the application:

    a. For Jira: family name, email, username, full name

    b. For Confluence: email, full name

  3. Add a custom "groups" mapper (see more details below).

Get Client Secret​

  1. Navigate to Clients, select your Client ID, and click the Credentials tab.
  2. Note down the 'Secret' for the next steps.

Final Configuration in Atlassian App (Confluence/Jira)​

Configure OAuth in miniOrange Plugin​

  1. Navigate to the miniOrange plugin in your Atlassian app.

  2. Go to the Configure OAuth tab.

  3. Select Keycloak in the application drop-down menu.

  4. Enter the following details:

    a. Client ID (from Keycloak)

    b. Client Secret (from Keycloak)

    c. Hostname (e.g., https://sso.example.com)

    d. Realm name (e.g., example-realm)

  5. Under Advanced Settings, select JWKS EndPoint URL, and enter the appropriate URL.

Map User Attributes​

  1. Go to the User Profile tab.

  2. Configure user mapping as follows:

    a. Username: preferred_username

    b. Email: email

User Attribute Mapping

Configure User Groups​

  1. Navigate to the User Groups tab.
  2. Set Assign Default Group To to None.
  3. Enable Manual Group Mapping and configure as per your needs (see examples below).

Confluence Group Mapping Jira Group Mapping

Sign-In Settings​

  1. Navigate to the Sign-In Settings tab.
  2. Set the "login button text" to something descriptive (e.g., Company SSO).
  3. Click Save.