Overview

SCIM (System for Cross-domain Identity Management) is a standard for managing user and group provisioning in an Identity Provider (IdP), ensuring that updates to users and groups are reflected in any relying parties, such as Persona. Persona supports some SCIM functionality for customers using Okta as their IdP.

High-Level Steps to Enable SCIM Provisioning for a Persona Organization:**

1. Enable 'SCIM Provisioning' for the relevant Okta app.
2. Configure the SCIM integration in the 'Provisioning' tab for the app.
3. Import users and groups from Persona.
4. Create groups in Okta that will be mapped to Persona groups/roles.

Availability

SCIM is available on Growth and Enterprise plans.

Prerequisite

SCIM is a highly sensitive feature, and API keys do not have SCIM permissions enabled by default. Persona recommends creating a dedicated API key (distinct from the one used for general calls to persona-web) for SCIM purposes.

Creating an API Key

1. Navigate to your Persona Dashboard > API
2. Create a new API key via ‘+ Create API key’
3. Once you’ve provided a name and description of the new API Key, you’ll be dropped in the configuration of the newly created API key
4. Select the ‘Permissions’ tab, expand the ‘API’ drop-down, and check the checkbox for ‘Use API Key for SCIM’ Click on “Save”, and keep this in mind as we’ll need the API key for SCIM integration

Enabling SCIM Provisioning

1. Log in to your Okta Admin Dashboard and navigate to the application you have pervious set up for the Persona SAML integration. For the purpose of this guide, we’ll refer to it as, Persona Application.
2. Once you’ve selected the Persona Application, go to the 'General' tab. Under 'App Settings', click 'Edit' and enable ‘SCIM’ provisioning, then click 'Save'.

Configuring the SCIM Integration

1. Navigate to the 'Provisioning' tab for the Persona Application

2. Edit the 'SCIM Connection' with the following:

   SCIM connector base URL	https://withpersona.com/scim/v2
   Unique identifier field for users	userName
   Supported provisioning actions	Select the following: Import New Users and Profile Updates, Push New Users, Push Profile Updates, Push Groups, Import Groups
   Authentication Mode	HTTP Header

3. Under HTTP Header, fetch the Persona SCIM API Key created in the prerequisite step and paste it into the field next to 'Bearer' in the dialog. You can get the API key by visiting https://withpersona.com/dashboard/api-configuration in your Persona account

4. Click 'Test Connector Configuration' to ensure the connection is successful.

5. Be sure to click 'Save', to save the configuration

Provisioning to App

1. Once the SCIM configuration is saved, you should see ‘Provisioning to App’, click ‘Edit’ to start the configuration

2. We recommend the following configuration for provisioning controls

   Create Users	[ x ] Enable
   Update User Attributes	[ x ] Enable
   Deactivate Users	[ x ] Enable
   Sync Password	[ ] Enable

3. Make sure you save the configuration before moving into the Import Users and Groups section

Import Users and Groups

1. Navigate to the 'Import' tab for the Persona Application
2. Click 'Import Now'. This will query Persona’s SCIM API to get a list of all users and groups in your Persona organization. You'll have the ability to map those to Okta users. After the import finishes, you should see a confirmation of how many Users and Groups were scanned.

3. Once scanned, you can move towards the next section to map the Users and Groups.

Create and map groups in Okta

1. Now, navigate to 'Directory > Groups' on the left side of your Okta dashboard
2. Filter by ‘Group source type: App groups’, you can see the default groups of Admin, Analyst, and Developer, which correspond to the default roles in a Persona organization. As well as any other custom roles you have created inside your Persona Dashboard.
3. We'll need to map those to Okta groups. If you don't have existing Okta groups that you'd like to map to these app groups, you should create them now.
   1. Click 'Add Group', and give your groups a name and (optionally) a description. In this example, we'll create three new groups called Persona-Admin, Persona-Analyst, and Persona-Developer.
4. For each of the new groups (those with the Persona- prefix), assign them to the Persona Application and assign the appropriate roles to people in your organization.
   1. To update the Persona-Admin group, click on its name, then click 'Applications', and assign it to the Persona Application.
   2. Click 'People' and add the appropriate users to each group.
5. Once done for each group, we are ready to connect the Okta groups to the app groups you imported. Return to the page for your Persona Application and navigate to the 'Push Groups' tab.
6. Click 'Push Groups', and then 'Find Groups by Name'. Begin typing the name of one of the groups until it appears.
7. Select one of the groups. A dialog will appear with an option on the right that defaults to 'Create Group'. Change that to 'Link Group' and select the appropriate app group.
8. You may see a message like "Linking to this group will rename the group in Persona Application". This is okay. Save, and repeat for each group. We recommend leaving 'Push group memberships immediately' checked.
   1. Perform this for each of the Roles/Groups that you have created

And your SCIM setup is now complete!