Integrate Atlassian Cloud with ForgeRock Identity Cloud

Author:

Nick Hangartner

Created at:

Mar 2023

Updated at:

Aug 2023

Introduction

This article describes the steps necessary to integrate Atlassian Cloud (Atlassian) with ForgeRock Identity Cloud (ID Cloud) to achieve the following outcomes:

Users can access Atlassian applications using their ID Cloud account
SSO experience when accessing Atlassian and other services integrated with ID Cloud
Centralised management of user profiles and Atlassian access rights in ID Cloud

Note:

Both cloud services are updated on a regular basis and the instructions provided here may differ from the current version
The integration can also be achieved using a ForgeRock self-managed or on-premises deployment, however the instructions here are based on ID Cloud

What you will need

The following components are required and require administrative access to perform the configuration steps:

ForgeRock Identity Cloud tenant
A running instance of ForgeRock Remote Connector Server, connected to the tenant
Atlassian Cloud account including Atlassian Access | Security & SSO for Jira, Confluence, Etc. Both are available (at the time of writing) as trials, however Access is limited to 30 days

Integration Approach

The integration consists of two interfaces:

SAML v2 : used by Atlassian redirect authentication of users to ID Cloud. Atlassian does not support SLO so SAML is used exclusively to verify user credentials during sign in.
SCIM : In contrast to other services that offer JIT (Just in time) provisioning of users during sign in, Atlassian relies on the SCIM protocol. This is used to manage both user and group information in Atlassian

Configure SSO

Configure ForgeRock IDP

Skip this section if you already have an existing SAML IDP configured in your tenant.

Create a Circle of Trust:

Goto the Identity Cloud admin UI page and sign in
Open the Access Management from the Native Consoles menu
Select Applications > Federation > Circles of Trust
Select the Add Circle of Trust button
Enter a name and select the Create button

Create a Hosted IDP:

Select Applications > Federation > Entity Providers
Select Add Entity Provider and choose Hosted
Enter a unique value in Entity ID. You can use the same value of the Entity Provider Base URL which defaults to the AM URL of your tenant
Enter a value in Identity Provider, for e.g. idp
Select the name of the CoT you created from the Circles of Trust list box
Select the Create button

Prepare ForgeRock IDP Metadata

Follow these steps to prepare the information necessary to configure your IDP in Atlassian.

Export the IDP metadata:

Goto the Identity Cloud admin UI page and sign in
Open the following URL replacing the text in brackets with your own values

https://[tenant-env-fqdn]/am/saml2/jsp/exportmetadata.jsp?entityid=[entityID]&realm=/[realmname]

Example:

https://openam-example-demo.forgeblocks.com/am/saml2/jsp/exportmetadata.jsp?entityid=https://openam-example-demo.forgeblocks.com/am&realm=/alpha

For the Identity provider Entity ID in Atlassian use the value of the entityID attribute in the following element:

<EntityDescriptor . . . entityID="https://openam-example-demo.forgeblocks.com/am">

The Location attribute in the following element corresponds to the Identity provider SSO URL:

<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://openam-example-demo.forgeblocks.com/am/SSOPOST/metaAlias/alpha/idp"/>

Save the value of the ds:X509Certificate element to a file cert.der:

<KeyDescriptor use="signing">
<ds:KeyInfo>
<ds:X509Data>
<ds:X509Certificate>signing_certificate_data<\ds:X509Certificate>

Convert the file with certificate data you saved in the previous step into the format required by Atlassian configuration as Public x509 certificate:

#!/bin/bash
# convert certificate from base64 encoded der to pem
base64 -D < cert.der | openssl x509 -inform der -outform pem -out cert.pem

Verify Domain in Atlassian

Verify the domain(s) of the user’s who access Atlassian using ID Cloud:

Goto the Atlassian Administration URL of your tenant and sign in
Select Settings from the top level navigation bar
Select Domains on the left navigation bar
Choose DNS or HTTPS as the verification method, depending on whether you have access to the DNS records or web server for the domain
Follow the instructions for the verification method you chose
Select the Verify domain button
When the status of the domain listed under Domains is VERIFIED proceed to the next step

Configure Atlassian SSO and User Provisioning

The steps required are based on the instructions for 3rd party IDP integration from the Atlassian online documentation Connecting to a SAML identity provider for single sign-on | Hipchat Data Center and Server Server | Atlassian Documentation.

Goto the Atlassian Administration URL of your tenant and sign in
Select Security from the top level navigation bar
Select Identity providers on the left navigation bar
Choose Other provider from the list of identity providers
Enter a descriptive value in Directory name, for e.g. ForgeRock
Select the Add button
On the next screen select Set up SAML single sign-on to start the configuration wizard
Select the Next button
Enter Identity provider Entity ID using the value of the entityID element from the IDP metadata, for e.g. https://openam-example-demo.forgeblocks.com/am
Enter Identity provider SSO URL using the value of the Location attribute from the metadata element
Enter Public x509 certificate using the contents of the cert.pem file you prepared in the previous section
Select the Next button
Make a note of both URLs - they will be required when configuring Atlassian as an service provider in ForgeRock
Select the Next button
Choose the domain that you verified from the list
Select the Next button
Select the Confirm move button
Select the Set up provisioning button
Make a note of SCIM Base URL and API Key for configuration in ForgeRock
Select the Next button and save the configuration

Configure Atlassian Authentication Policy

Goto the Atlassian Administration URL of your tenant and sign in
Select Security from the top level navigation bar
Select Authentication policies on the left navigation bar
Select the Edit button next to the directory you set up previously which should display Single sign-on as disabled
Select the Enforce single sign-on option
Select Update and confirm changes

Configure Atlassian SP in ForgeRock

Prepare the metadata for importing into ForgeRock by saving the following code block and replacing the values of the following attributes with values from the SAML configuration in Atlassian :

sp_entity_url with the value of Service provider entity URL
sp_assertion_consumer_url with the value of Service provider assertion consumer service URL

<?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
    entityID="service_provider_entity_url">
    <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
            Location="sp_assertion_consumer_url"
            index="1" />
    </md:SPSSODescriptor>
</md:EntityDescriptor>

Note:

The NameIDFormat element is set to emailAddress as Atlassian expects an email address to be returned and does not specify it in the authentication request.

Testing SSO

Testing SSO without user provisioning requires a valid user account in ForgeRock with an email address containing the domain you registered in Atlassian. Use a private browser window to ensure that you have no existing session in ForgeRock or Atlassian.

Example:

Sign in to your Atlassian tenant and enter an email address with a domain you verified in the Atlassian SSO configuration:

You should then be redirected to ForgeRock and prompted to sign in:

When the login journey is completed successfully you should be redirected back to Atlassian. If no user profile information has been provisioned via SCIM and your user account does not exist yet in Atlassian you will be prompted to request access:

Open another browser window and goto the Atlassian Administration URL of your tenant.

Enter the email address of the user and select Add team members. The user will be added to the list of users displayed at the bottom of the screen and shown as Invited:

Return to the browser with the user session and refresh. You should be prompted to answer or skip several questions:

And presented with the Atlassian dashboard:

Configure User Provisioning in ForgeRock

Configure SCIM Connector

Configure a SCIM connector using instructions Create a connector configuration over REST :: ForgeRock Identity Cloud Docs and modify the following properties before sending the configuration to ID Cloud using Postman:

authenticationMethod with TOKEN
SCIMEndpoint with the value of SCIM Base URL
authToken with the value of API Key

//excerpt of SCIM connector configuration
    "configurationProperties" : {
        "authenticationMethod" : "TOKEN",
        "SCIMEndpoint" : "scim_base_url",
        "authToken" : "api_key",
        "acceptSelfSignedCertificates" : false,
        "clientId" : null,
        "clientSecret" : null,
        "disableHostNameVerifier" : false,
        "httpProxyHost" : null,
        "httpProxyPort" : null,
        "maximumConnections" : "10",
        "password" : null,
        "SCIMVersion" : "2",
        "tokenEndpoint" : null,
        "user" : null
    }

Map User Data to SCIM Format

Create a mapping from Managed User to the connector created in the previous step. In minimum the mapping must include the following attributes:

Source

Target

mail

userName

mail

emails

Add the following transformation to script to the mail attribute which outputs a multi-value attribute as defined by the SCIM schema for the emails attribute. Note that other attributes such as phoneNumbers require similar transformation if used in the mapping.

/*
 * IDM transform script
 *
 * Converts mail attribute to a multi-value attribute
 *  defined by RFC 7643: SCIM Core Schema
 *
 */
function convertMailToScimFormat() {
    var mails = [];
    var obj = new Object();
    obj.value = source;
    obj.type = "work";
    obj.primary = true;
    mails.push(obj);
    return mails;
}

convertMailToScimFormat();

To enable or disable Atlassian accounts based on the status of the user object in ID Cloud map the accountStatus attribute to the active attribute and add the following transformation script:

/*
 * IDM transform script
 *
 * Converts "accountStatus" attribute to a boolean value for the "active" attribute
 *  defined by RFC 7643: SCIM Core Schema
 *
 */
if (source == "active") {
  active = true;
}
else {
  active = false;
}
active;

The attributes mapping should look like this:
mapping-attributes-grid

In this example the preview is showing two users where the value of accountStatus is “active” and one user with the value “inactive”:
map-source-preview

After selecting Reconcile users with an email that matches the domain that you registered in Atlassian will be synchronized and listed in the Atlassian Administration interface under Directory, Users. Note the Status of the user atlassian3@poc… is set to Deactivated:

atlassian-users