Configure user provisioning with Okta
User provisioning integrates an external user directory with your Atlassian Cloud products. This page describes how to configure user provisioning when Okta is your identity provider (IdP). For the operations that user provisioning supports, see User provisioning features for more details.
After you configure user provisioning, you manage all user attributes and group memberships from your IdP.
As an Atlassian Cloud admin, there are a couple of things you need to do before you can provision external users into your Cloud sites and products:
- Get the user provisioning functionality for your Okta account. See Lifecycle Management for more details.
- You're an admin for an Atlassian Cloud organization. See Organization administration.
- Verify one or more or your domains in your Cloud organization. See Domain verification.
- Subscribe to Atlassian Access from your Atlassian Cloud organization. See Security with Atlassian Access.
- You should be an admin for at least one Jira or Confluence site that you want to grant synced users access to.
Now you can continue with the instructions below to connect your identity provider with your Atlassian Cloud products.
Step-by-step configuration instructions for Okta
In this section, we'll show you how to connect Okta and Atlassian Cloud and how to provision users automatically.
If this is the first time you're following these steps
To get started, we recommend trying these setup instructions with test accounts and test groups in Okta, e.g. atlassian-test-jira-users and atlassian-test-confluence-users.
Starting with test accounts can help to avoid disruption when someone unintentionally unassigns users from the Atlassian Cloud app. When you unassign users from the app, you disable their accounts, which also removes their access to Atlassian products.
1. Create a SCIM token in Atlassian Cloud
From your organization at admin.atlassian.com,click Directory and then User provisioning.
While we make updates to the admin experience, you may not need to click Directory to get to User provisioning.
- Choose User provisioning on the left, then click Create a token.
- Enter a name to identify the user directory, for example Okta users, then click Create.
Copy the values for Directory base URL and API key. You'll need those for when you configure the Okta application later.
Make sure you store these values in a safe place, as we won't show them to you again.
- Now add Jira or Confluence sites to your organization. You need to do this so that provisioned users can be granted access to the products.
On the 'User provisioning' page, click Add a site, select the site you want to add (e.g. example.atlassian.net), and follow the on-screen instructions.
2. Configure the Atlassian Cloud application in Okta
Note that for this step you'll need the Directory base URL and Bearer token that you created in the 'Create a SCIM token in Atlassian Cloud' section above.
Part 1: Enable SCIM API integration for user provisioning
- Log in to Okta and add the Atlassian Cloud application.
- In the Atlassian Cloud application, click on the Provisioning tab and then click Configure API integration:
- Select Enable API integration:
- Enter the Directory base URL and API key you created in your Atlassian organization:
Click Test API Credentials. If the test passes, click Save.
CIick To App under Settings.
Click Edit and select Enable for the options you'd like to have.
Use this step to map user attributes or leave them with default settings. For the operations that Atlassian supports, see User provisioning features for more details.
Click Save to apply the integration settings.
Part 2: Make sure the email address attribute is the same for SAML SSO and user provisioning
User provisioning uses an email address to identity a user in Atlassian Cloud and then create a new Atlassian account or link to an existing Atlassian account. As a result, if the email address attribute for a user is inconsistent between the SAML SSO setting and the SCIM user provisioning setting in the Okta app, the user could end up with duplicate Atlassian accounts.
To avoid duplicate accounts, make sure the email address attribute that maps user account is the same for SAML SSO and SCIM user provisioning:
- From the User provisioning tab in Okta, note the field that maps to the Primary email attribute. The default is
Click the Sign on tab. From the Credentials details section, look for the Application username format setting. Okta passes this field from a user's account as the SSO email address when creating or linking an Atlassian account.
If Application username format specifies to pass an old value (e.g. the email address of email@example.com for the specified attribute is old and you have another attribute that stores the current user email address of firstname.lastname@example.org), here's what you can do:
- Ask the user to log in with their Atlassian account once before you complete this step.
- If the user still ends up with duplicate accounts, contact Atlassian support with the user's email addresses.
- Make sure Application username format is set to the same attribute specified as Primary email in the previous step.
- Make sure that Update application username on is set to Create and update. Click Save to apply your changes.
- Click Update Now to push the change faster than the Okta automatic update.
Part 3: Push groups to Atlassian Cloud
We recommend using the group synchronization feature to automatically manage user privileges and licenses using your directory, instead of manually managing these in Atlassian Cloud. This section describes how to configure group-based management.
- In Okta, click on the Push Groups tab and then By name. Select the group name (e.g. atlassian-test-jira-users or atlassian-test-confluence-users) and click Save.
In the screenshot above, we use the atlassian-confluence-users group to manage product access to Confluence.
Note that pushing a group does not synchronize any users. This will only push the group to Atlassian Cloud.
- Now review to make sure all desired groups have been pushed:
Part 4: Assign users to the Atlassian Cloud application in Okta
- In Okta, click the Assignments tab of the Atlassian Cloud application:
- Click Assign, then Groups. Select the group you'd like to assign. In our example, the group is atlassian-confluence-users.
- You'll see this dialog to set default values. These default values will be used only if the user profile does not have them set. All of these fields are optional and can be left blank. When you are done with this step, click Save and Go Back.
- Verify that users are synchronized with Atlassian Cloud. You can check either the Okta logs or the User provisioning page in the Atlassian Cloud admin area:
3. Configure product access for the provisioned groups and users
To set up the product access any new provisioned users get granted, let's grant the product access the groups have.
- In the Atlassian product site (example.atlassian.net) you added in 'Create a SCIM token in Atlassian Cloud' step 5 above, go to Product access in the admin area, and find the Confluence section. Click Add group and enter the name of the synchronized group. Click Grant access to confirm the change. Read more about how to configure product access.
Do not make a synced group from your identity provider a default group. This may cause collisions when attempting to add users to the product that are not managed via SCIM.