Integrate Atlassian Cloud with ForgeRock Identity Cloud

[nick.hangartner]

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:

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

Create a Hosted IDP:

1. Select Applications > Federation > Entity Providers
2. Select Add Entity Provider and choose Hosted
3. 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
4. Enter a value in Identity Provider, for e.g. idp
5. Select the name of the CoT you created from the Circles of Trust list box
6. 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:

1. Goto the Identity Cloud admin UI page and sign in
2. 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:

1. Goto the Atlassian Administration URL of your tenant and sign in
2. Select Settings from the top level navigation bar
3. Select Domains on the left navigation bar
4. Choose DNS or HTTPS as the verification method, depending on whether you have access to the DNS records or web server for the domain
5. Follow the instructions for the verification method you chose
6. Select the Verify domain button
7. 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.

1. Goto the Atlassian Administration URL of your tenant and sign in
2. Select Security from the top level navigation bar
3. Select Identity providers on the left navigation bar
4. Choose Other provider from the list of identity providers
5. Enter a descriptive value in Directory name, for e.g. ForgeRock
6. Select the Add button
7. On the next screen select **Set up SAML single sign-on **to start the configuration wizard
8. Select the Next button
9. 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
10. Enter Identity provider SSO URL using the value of the Location attribute from the metadata element
11. Enter Public x509 certificate using the contents of the cert.pem file you prepared in the previous section
12. Select the Next button
13. Make a note of both URLs - they will be required when configuring Atlassian as an service provider in ForgeRock
14. Select the Next button
15. Choose the domain that you verified from the list
16. Select the Next button
17. Select the Confirm move button
18. Select the Set up provisioning button
19. Make a note of SCIM Base URL and API Key for configuration in ForgeRock
20. Select the Next button and save the configuration

Configure Atlassian Authentication Policy

1. Goto the Atlassian Administration URL of your tenant and sign in
2. Select Security from the top level navigation bar
3. Select Authentication policies on the left navigation bar
4. Select the Edit button next to the directory you set up previously which should display Single sign-on as disabled
5. Select the Enforce single sign-on option
6. 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.

Sign in and Select Directory, Users.

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" : "1",
        "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();