Okta SCIM 2.0 configuration

User Sync Configuration

Go to your Atlassian product and navigate to the User & Group Sync settings. Click Create Connector and choose SCIM 2.0.

us_scim_connector

You can change or add a Name for your SCIM 2.0 Connector. You can copy your SCIM Base URL and the Bearer Token. We will need both later for the configuration of the IdP SCIM application.

us_scim_specific_settings

Don't forget to save "Save and Return" your settings!

We will have a look at the 'Provisioning' and 'Sync' settings later. However, first we create an Application (SCIM client) in your Okta admin portal.

Okta (SCIM Configuration)

Follow the instructions below to set up provisioning of users from Okta to your Atlassian instance using SCIM v2.

For the rest of the tutorial, we assume that you already have a configured SAML application running the re:solution SAML SSO plugin. We will use this application to configure SCIM as provisioning method.

Open the Okta admin portal
- Select Classic UI and then Applications
- choose your Application

okta_application

Enable SCIM provisioning

Now go back to the application settings (General). Click Edit and enable SCIM provisioning. Click Save

enable_scim_okta

Configure the SCIM connector

Go to the Provisioning tab. Click the Edit button to configure the SCIM connection:
- Copy the SCIM Base URL (from your User Sync connector setup) to the SCIM connector base URL field
- Type in userName in the Unique identifier field for users field
- Select HTTP header authentication mode
- Copy the Bearer token from your User Sync connector setup into the Bearer token value field
- Under supported provisioning actions, enable Push New Users, Push Profile Attributes, and Push Groups

scim_configuration_okta

Click Test Connector Configuration, then Save

Configure To App settings

In the To App settings, enable Create Users, Update User Attributes, and Deactivate Users.
Leave Sync Password unselected.
You should not need to change the Attribute Mapping settings on this screen.
Click Save

okta_provisioning-setup_to-app

At this point, any user or group assigned to the SCIM application in Okta will be provisioned to your Atlassian instance.

Push Groups

You still need to explicitly specify the groups to provision. To do this, navigate to the Push Groups tab and click the blue Push Groups button. Either add groups by name or create a rule. In the screenshot, we have added two groups by name. You can either push immediately or manually activate each group when you're done.

push_groups_okta

SCIM should now be configured and working.

User Sync fine-tuning

Back to our SCIM 2.0 User Sync Connector. Let's have a look at the Provisioning Settings tab first.

You can configure three main sections in the provisioning settings.

Copy Behaviour

Copy behaviour is useful if you add User Sync to an existing Atlassian application like Jira or Confluence and want to migrate existing data. It allows you to find the user record with the same username in a different Atlassian application directory and copy the contents to the User Sync directory (i.e. Group memberships, last login time, user properties, etc.).

Attribute Mapping

Within the Attribute Mapping, you can map data coming from SCIM 2.0’s API to fields within the Atlassian Application. You can also apply a lot of advanced functions to transform, change or filter the data from SCIM 2.0 before applying it to the Atlassian Application.

Group management

Group management can be one of the trickiest elements to understand in User Sync. Atlassian does not have the concept of groups from different sources, i.e., from SCIM 2.0 or groups created locally.
In its default configuration, User Sync treats SCIM 2.0 as the single-source of truth for group memberships of users synchronized from SCIM 2.0. If a synchronized user is a member of a group in your Atlassian application (i.e. locally assigned) but not in SCIM 2.0, the next sync does remove that membership. With the settings below, you can adjust this behaviour to your use case.

Common configurations are:

Automatically assign groups to every synchronized User
Do not use groups from SCIM 2.0 and treat every given group as local
Limit the groups assigned & imported from SCIM 2.0 to specific patterns
Allow mixed-use, where you define some groups as locally managed and others to be assigned & managed from SCIM 2.0.

IdP group management

Here, you configure in detail how the plugin deals with groups loaded from the Identity Provider. The two settings are:

Only Assign these Groups
If you add group names here, the plugin will only assign these from the IdP and drop all others that the IdP sends for a particular User. Essentially, this is a IdP group whitelist.
You can also use regular expressions (e.g: to match multiple group names at once, like jira-.* for everything that starts with jira-)

Never assign these Groups
If you add group names here, the plugin will never assign the groups from the IdP, but assign all others that the IdP sends for a particular User. Essentially, this is a IdP group blacklist.
You can also use regular expressions (e.g: to match multiple group names at once, like jira-.* for everything that starts with jira-)

Usually you only use one of the options and not necessarily both at the same time.

Local group management

Here, you control how the plugin adds/ removes groups that you may have assigned locally to the user.

Always assign Users to certain Groups
This allows you to add every user to the groups listed in this field. For example, it can be handy to add every user to an application access-group like jira-users. This is re-applied during every sync, so if you manually remove a user from one of these groups, he will be re-added during the next sync.

More flexible use-cases can be achieved with the attribute mapping's transformation features.

Never remove users from these Groups
You control which groups are not automatically removed by User Sync from users. By default, if we detect that a synchronized user is a member of a group in Jira, but that membership is not reported by SCIM 2.0, we would remove the User from that group. That is great for group memberships you want to be managed on SCIM 2.0. It's not suitable for those you would like to assign manually from within Jira via the UI.

You need to list all groups that User Sync should not remove in this setting. This can either be by listing the Group names as they appear in Jira or by using regular expressions.

Note

Applying .* in "Never Remove Users From These Groups" and .* in "Never Sync These SCIM 2.0 Groups" will only synchronize User Data from SCIM 2.0 but no group memberships. Essentially something like a "remote directory with local groups" that you know from Atlassian LDAP connections.

See https://wiki.resolution.de/doc/usersync/latest/knowledge-base/group-management-and-filtering-with-user-sync for more information.

Sync Settings

The Sync Settings give you the possibility to configure the Cleanup Behavior. What happens to users that have been synchronized into Confluence once...

they get deleted in SCIM 2.0
they are not member of any required groups anymore
they are dropped by a transformation in the attribute mapping

The default behaviour is to disable these users, as Atlassian recommends.