Atlassian

This document provides instructions for migrating from Confluence and Jira Cloud provisioning apps in the Okta Integration Network (Atlassian Jira Cloud, Atlassian Jira, and Atlassian Confluence Cloud) to the Atlassian Cloud OIN app.

Overview

With the release of the Atlassian Cloud app integration in the Okta Integration Network (OIN) (built and maintained by Atlassian) that supports Security Assertion Markup Language (SAML) Single Sign-On (SSO) and System for Cross-domain Identity Management (SCIM) provisioning functionality, Okta recommends that you migrate the following app integrations to Atlassian Cloud:

  • Atlassian Confluence Cloud: In alignment with Atlassian’s removal of the SOAP API used by the Confluence Cloud app, the provisioning functionality has been deprecated. Switching to the Atlassian Cloud is mandatory to continue using provisioning.
  • Atlassian Jira Cloud: Provisioning functionality for this app integration is not deprecated and although you can continue using this integration if preferred, we recommend that you migrate to the new Atlassian Cloud app.
  • Jira (Atlassian): Provisioning functionality for this app integration is not deprecated and although you can continue using this integration if preferred, we recommend that you migrate to the new Atlassian Cloud app.

Remember: You may have changed the default names for these apps when configuring them in your org.

The Atlassian Cloud app integration is your one-stop shop to enable SAML and manage users via SCIM provisioning for all Atlassian Cloud products listed above (and more). It offers enhanced functionality and a better user experience by allowing you to set up SAML at an organization level and push groups and their members to the Atlassian Cloud. The app integration is periodically updated and maintained by Atlassian so you are encouraged to upgrade at their earliest opportunity.

Note: If you are using a Confluence or Jira server with these app integrations, there is no action required. The migration is only applicable if you use cloud products.

Plan the migration

  • Budget at least 1-2 weeks for the project, including planning, testing, and rollout.
  • Review the migration documentation below to understand the available SSO and SCIM functionality.
  • Setup and test the new Atlassian Cloud integration available in the OIN.
  • Migrate all users to the new Atlassian Cloud integration before the End of Life date.

For questions about the End of Life of the Atlassian Confluence Cloud and Atlassian Jira Cloud integrations, contact support.okta.com. For questions about Atlassian products, the new Atlassian Cloud integration or migration, contact Atlassian support.

Feature Comparison

Atlassian Cloud Atlassian Confluence Cloud Atlassian Jira Cloud Jira (Atlassian)
SWA ● ● ● ●
OMM ● ● ● ●
SAML ●
Push User Deactivation ●
Reactivate Users ●
Push Profile Updates ● ● ●
Push New Users ● ● ●
Push Groups ● ● ●
Import New Users ● ● ●
Import Profile Updates ● ● ●
Push Password Updates

Deprecated in alignment with Atlassian’s removal of the SOAP API used by the Confluence Cloud app. (For reference, see Confluence Cloud SOAP API Migration Guide.

Requirements

  • To take advantage of the Atlassian Cloud app and use both SAML and SCIM functionality, you have to have an Atlassian Access subscription. For more information see Atlassian Access.
  • The Okta-built Confluence or Jira applications allow you to manage users at a site level. The Atlassian-built Atlassian Cloud application allows you to manage users at an organization level. As per Atlassian documentation, Atlassian organizations can have multiple sites and are a centralized place managing products and users. Before proceeding to the migration steps below, make sure that you have added your Jira or Confluence sites to your Atlassian organization. For more information see Explore an Atlassian organization.
  • Test the migration flow with sample users or groups to ensure everything is working properly before you proceed with production data.
  • It is not recommended to use individual assignments when assigning users to the Atlassian Cloud application. As mentioned throughout the migration steps below, assigning users should be done via group assignment as product access is granted to the groups. Members of those groups will automatically have the product access that was granted to the groups they belong to. If you use individual user assignment when pushing users via your Atlassian Cloud application in Okta, that user will not have any product access until you add that user to a group.
  • If you are pushing groups via the Atlassian Cloud application that you previously pushed using the Okta-built Jira applications, the groups will automatically be linked and any product access you granted to that group should remain the same.
  • If you want the users you pushed via the Jira or Confluence applications to be a part of the same groups, you have to assign them to those groups in Okta before you push them via the Atlassian Cloud application.

    Note: Unlike the Okta-built Jira or Confluence applications, the Atlassian Cloud app does not support Group Discovery when pushing new users.

  • For the Atlassian Cloud app, user accounts can only be pushed if they use a domain that is verified using your Atlassian organization. At an Atlassian organization level, you need to verify you own a domain to be able to push and manage accounts using that domain:

    • Atlassian verify domains

  • At the Atlassian site level, users with any domain you grant access to can be added to the site. You don't have to verify that you own the domain at the Atlassian organization level:

    Atlassian define Site access

  • Remember the following when you are migrating: If you have users at a the site level using a domain that you can't verify at an organization level, you will not be able to push that user using the Atlassian Cloud app.

Migration steps

The Atlassian Cloud app has been added to the Okta Integration Network (OIN) to provide you with a better experienc. This application adds Lifecycle Management support for the Atlassian identity platform.

To take advantage of these updates, add a new instance of Atlassian Cloud in your Okta org. If you previously added any of the Okta-built Jira or Confluence Cloud applications, follow the steps below to migrate from these applications to the Atlassian Cloud application:

  1. Sign in to your Okta org as an Admin.

  2. In the Admin Console, go to ApplicationsApplications.

  3. Click Add Applications:

    Add Application in Okta

  4. Add a new instance of Atlassian Cloud:

    Add new Atlassian instance in Okta

  5. Configure the application depending on the features you would like to use (SWA, OMM, SAML, Provisioning):
    • SWA: Under the Sign On tab, select SWA as the sign on method and choose the desired option for saving user credentials, then click Save:

      Select SWA as sign on method

      1. If you were using the SWA sign-on mode for your old Jira or Confluence Cloud application, the credentials for all users that will be assigned to the new Atlassian Cloud application need to be re-entered. Note: If users need to retrieve their passwords, they can do so by following the steps below:

        • On their Okta homepage, hover over the Jira or Confluence Cloud application, then click the gear icon:

          click Confluence gear icon

        • On the See Password tab, click Reveal Password. Users are prompted to re-authenticate to see the credentials:

          Reveal password

        • Before de-activating or deleting your old Jira or Confluence Cloud app instance, make sure that all users who need to retrieve their passwords have done so to avoid re-setting their passwords via Jira or Confluence Cloud.

      2. Make sure to select or add the same Application Username Format from the existing Jira or Confluence app:

        select Application Username Format

      3. Scroll down to the Sign On Policy section. Copy all sign on policies to the new app, the way you had them configured for the old app.

        See App sign-on policies for details.

        Copy sign on policy from old apps

    • OMM: Under the Mobile tab, enable all desired Mobile applications that you want to be available to your users for download in the Okta Mobile App Store.

      Mobile tab, enable atlassian mobile apps for Okta mobile store

      Note: If you activated the Jira or Confluence Cloud OMM applications in your old Jira or Confluence Cloud application, you would need to re-activate these again after adding the new Atlassian Cloud application.
    • SAML: Under the Sign On tab, choose SAML as the sign on method. Click View Setup Instructions and follow all the steps to configure SAML for your Atlassian Cloud app:

      For SAML sign on method, select View Setup Instructions

    • SCIM: Follow the steps outlined in the Atlassian Cloud SCIM Configuration Guide. Remember that user provisioning via the Atlassian Cloud SCIM app should be done via Group assignment. User product access is assigned via Groups.

      Common provisioning scenarios not described in the Atlassian Configuration Guide

      • Pushing existing groups that were pushed using the Okta-built Jira apps

        As mentioned in the Requirements section, pushing groups that were previously pushed using the Okta-built Jira apps to the Atlassian Cloud app should link the groups correctly. Any product access granted to those groups will stay the same. No special step is needed to push the same groups.

      • Pushing groups using a rule

        If you previously set-up a rule in your Okta-built Jira or Confluence apps to push groups automatically, make sure that you add the same rule in your Atlassian Cloud app instance.

        add push groups rule to new apps

        This is important if you import groups from an external source (e.g. Active Directory, LDAP) to ensure that any groups created from those sources continue to be pushed automatically

      • Using custom mappings when pushing users

        The Atlassian Cloud app currently does not support the Second Email and Mobile Phone attributes. These two attributes were supported in the Okta-built Jira or Confluence apps. All other attributes are supported. For a full list of the Atlassian Cloud SCIM app default attributes and mappings, see the Atlassian Cloud SCIM Configuration Guide. If you need to add or delete attributes in your SCIM app, update mappings to any of the attributes to match your old Jira or Confluence attribute mappings.

        Note: Once you push a user at an org level, any attribute mappings set using the Atlassian Cloud app will overwrite any attribute mappings set using the Okta-built Jira or Confluence apps.

  6. After you have enabled all the features you want, go to the Assignments tab of your new Atlassian Cloud application. Click Assign and start assigning the same users or groups that are assigned to your old Jira or Confluence Cloud applications.

    IMPORTANT

    1. Make sure you assign all the users to your new Atlassian Cloud instance to avoid any accidental de-provisioning or loss of access for your users.
    2. If you are enabling Provisioning, it is important to go through the Atlassian Cloud SCIM configuration guide before assigning users to the application. To provision users properly with the correct product access permissions, it is necessary for users to be assigned via Group assignment (these Groups should be pushed first before assignment).

    Assing new app to same users/groups

  7. Go back to your Admin Console.
  8. Open your Jira or Confluence Cloud applications.

    Note: This is the previous application you added before adding a new one in step 4.

  9. Optional: If you previously used Provisioning for your Jira or Confluence Cloud app:
    1. Go to the Provisioning tab.
    2. Under SETTINGS , select API Integration.
    3. Click Edit, then clear Enable API Integration.
    4. Click Save:

      5. Provisioning > API, uncheck Enable API Integration

  10. You can now deactivate or delete your old Jira or Confluence Cloud application and continue using the new Atlassian Cloud application you added. However we recommend you hide the app for a short time period (1~2 weeks) and have users test with the new application before deactivating the old Jira or Confluence app. Follow these steps:
    1. Hide your old Jira or Confluence app.
      1. Go to the old Jira or Confluence app, then select the General tab.
      2. Select Do not display application icon to users.
      3. If the app is setup for mobile access, also check Do not display application icon in the okta mobile app.
      4. Click Save.

      The old Jira or Confluence app is now hidden to end users.

      Hide old icon on dashboard

    2. Deactivate your old Jira or Confluence Cloud application.

      Click the Active status dropdown menu under your Jira or Confluence Cloud application label, then click Deactivate:

      deactivate old apps

    3. Delete your old Jira or Confluence Cloud application.

      Deactivate the old app as described in step b above. After the app has been deactivated, on the Inactive status dropdown. You are given the option to Activate or Delete the app. Choose Delete. You are prompted to confirm whether you want to really delete the application. Click Delete Application:

      delete old apps