Configure user provisioning with Okta

We’re currently rolling out changes that affect the content on this page. From your organization at, if the Users list and Groups list are under the Directory tab, you have the improved user management experience. We’ll note changes for the improved experience in the content below.

A diagram of an new view that shows a new Directory tab instead of Users and Groups

Provisioning is available for all Atlassian accounts, which means that you can create, update, and deactivate accounts from your identity provider. Syncing groups is only currently available for Jira products and Confluence and not yet available for Bitbucket.

User provisioning integrates an external user directory with your Atlassian organization. This page describes how to configure user provisioning when Okta is your identity provider. For the operations that user provisioning supports, see User provisioning features for more details.

After you configure user provisioning, you can manage user attributes and group memberships from your identity provider.

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 app. When you unassign users from the app, you disable their accounts, which also removes their access to Atlassian products.


There are a couple of things you need to do before you can provision external users into your sites and products:

  1. Get the user provisioning functionality for your Okta account. See Lifecycle Management for more details.

  2. Make sure you're an admin for an Atlassian organization. See Organization administration.

  3. Verify one or more or your domains in your organization. See Domain verification.

  4. Subscribe to Atlassian Access from your organization. See Security with Atlassian Access.

  5. You should be an admin for at least one Jira or Confluence site that you want to grant synced users access to.

Step 1. Create a SCIM Directory

  1. Go to Select your organization if you have more than one.

  2. Select Directory > User provisioning
    This step is different if you have the improved user management experience. Select Settings > User provisioning.

  3. Select Create a token
    This step is different if you have the improved user management experience. Select Create a directory.

  4. Enter a name to identify the user directory, for example Okta users, then select Create.

Screenshot of Create a directory screen with a text box for the name and a Create button. The name entered is Okta users

4. 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.

Okta users API key screen. Includes directory base URL and API key.

Users and groups will automatically be provisioned to Jira and Confluence sites linked to your organization. See the user provisioning page for more details on how your users and groups sync to your organization.

Step 2. Enable SCIM API integration in Okta

For this step you'll need the directory base URL and bearer token from Step 1. Create a SCIM Directory above.

  1. Log in to Okta and add the Atlassian Cloud application.

  2. From the application, click on the Provisioning tab and then click Configure API integration:

Okta UI with info box called Atlassian: Configuration guide, and a Configure API Integration button..

3. Select Enable API integration:

Okta UI. An unselected checkbox for Enable API integration, and a Save button.

4. Enter the Directory base URL and API key you created in your Atlassian organization:

Enable API integration checkbox selected. Boxes to enter the Directory base URL and API key.

5. Click Test API Credentials. If the test passes, click Save.

6. CIick To App under Settings.

7. 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.

Provisioning Okta to app with option to cancel. Enable/disable create users, update user attributes, deactivate users.

8. Click Save to apply the integration settings.

Step 3. Make sure the email address is correct in Okta

User provisioning uses an email address to identity a user in the Atlassian app 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:

  1. From the User provisioning tab in Okta, note the field that maps to the Primary email attribute. The default is email, as shown in the screenshot.

A table of attributes with an arrow pointing to email, which is the primary email entry.

2. 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 for the specified attribute is old and you have another attribute that stores the current user email address of, 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.

3. Make sure Application username format is set to the same attribute specified as Primary email in the previous step.

4. Make sure that Update application username on is set to Create and update. Click Save to apply your changes.

Okta username is the selected application username format. Update application username on is set to Create and update.

5. Click Update Now to push the change faster than the Okta automatic update.

Step 4. Push groups to the organization

We recommend using the group synchronization feature to automatically manage user privileges and licenses using your directory, instead of manually managing these from the organization. This section describes how to configure group-based management.

Pushing a group does not sync any users and only pushes the group to your Atlassian organization.

  1. 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.

Push groups to Atlassian cloud SCIM screen. Top menu on Push Groups, side menu on By name. Group names to choose from.

In the screenshot above, we use the atlassian-confluence-users group to manage product access to Confluence.

Pushing a group does not sync any users and only pushes the group to your Atlassian organization.

2. Review to make sure all desired groups have been pushed:

Shows 2 the groups in Okta, with last push time and date, and push status set to active for both.

Step 5. Assign users to the Atlassian application in Okta

  1. In Okta, click the Assignments tab of the Atlassian application:

Assignment tab, Assign set to Groups. Empty list of groups, with priority and assignment columns.

2. Click Assign, then Groups. Select the group you'd like to assign. In our example, the group is atlassian-confluence-users.

Assignment tab, Assign to groups is selected.
Assign Atlassian Cloud SCIM Groups list. Every group has an Assign button. There is a Done button at the bottom.

3. 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.

 Group attributes that are empty and can be assigned values: preferred language, time zone, organization, and department

4. From your Atlassian organization, verify that users are synced. You can check either the Okta logs or the User provisioning page:

User provisioning screen in There are 3 synced users and 1 synced group. On Groups tab

Step 6. Configure product access for the provisioned groups and users

To grant product access to any newly provisioned users, select Edit product access and set up product access for existing groups. To learn more about configuring product access, see Update product access settings.

User provisioning section in, on Product access tab. 2 groups are listed, with Edit product access links

Additional Help