Okta setup

To set up SCIM in Okta for BirdCRM, first configure the SCIM connection and settings. For provisioning users with roles, you can either assign roles directly or push groups to BirdCRM Teams that have roles assigned to them.

This section is broken up into three parts to cover the initial SCIM setup and then the two role provisioning options:

• SCIM setup

• Direct role assignment

• Team-based role assignment

SCIM setup

BirdCRM Steps

1. Navigate to the SCIM Settings page which is available here or by visiting Settings and clicking on the Security tab and then SCIM Settings.

2. Click on Copy next to the SCIM base URL and take a copy of the Base URL as you will need it to configure Okta in the next section.

3. Click on Add new access key and fill out a meaningful Name and Description and click Save.

4. You will then be presented with your Access Key. Make sure you take a copy and save it securely as you will not be able to view it again and you will need it to configure Okta in the next section.

Okta steps

1. Navigate to Applications and select Create App Integration. Select SAML 2.0 and click Next.

2. Give the application a name such as BirdCRM SCIM, an optional logo and tick ‘Do not display application icon to users’ as this will only be used to provision users and not login from. Click Next.

3. In the next screen it is mandatory to complete the Single Sign-on URL and Audience URI but the values are not used so any valid value will suffice (e.g. https://localhost). The other value that must be set is the Application username which must be set to Email. Scroll down and click Next.

4. On the next page select This is an internal app that we have created and click Finish.

5. The SAML app has been created. Now navigate to the General tab and select Edit.

6. Select SCIM under Provisioning and click Save.

7. A new Provisioning tab will appear. Select it and then select Edit under the Integration Settings.

8. Complete the following fields and then click Test Connector Configuration:

• SCIM connector base URL: SCIM base URL from Step 2. In the BirdCRM Instructions

• Unique identifier field for users: userName

• Supported provisioning actions: Import New Users and Profile Updates, Push New Users, Push Profile Updates, and Push Groups is optional if you would like to sync Okta groups to Teams in BirdCRM.

• Authentication Mode: HTTP Header

• Authorization: The SCIM Access Key retrieved in Step 4. Of the BirdCRM Instructions.

9. The results of the Test Connector Configuration will be displayed and should look similar to this.

10. Click on Close and given all required tests passed you will be able to click Save. If any of the required tests failed, please carefully double check the values you entered in Step 8. You will then be presented with this screen which means that the SCIM integration has been setup but no SCIM users or groups are configured or enabled yet

11. In order to enable SCIM, click on Edit and select Enable for Create Users, Update User Attributes and Deactivate Users. Click Save.

At this stage, SCIM is set up and users can be assigned to the application via Individual or Group assignment. They will be created in your organization but won’t be assigned a role automatically, requiring manual role application for login access.

To automatically assign roles to users, you can:

• Use Push Groups and Teams in BirdCRM.

• Have roles directly assigned by Okta and SCIM.

Direct Role Assignment

Direct role assignment means that users will get roles assigned to their user in your organization directly from Okta.

This is a flexible setup that can allow you to setup Groups in Okta that have one or more roles assigned to them and any users in that group will be assigned the role(s) assigned.

Multiple role assignments across multiple groups are supported and will give the user the aggregate of all roles assigned across their groups.

One limitation of this approach is that you cannot assign a role to a specific Workspace or a group of Workspaces. To scope roles to Workspaces, use the Team-based Role Assignment method described below. Both methods can be combined if necessary.

In order to set up direct role assignments from Okta, you first need to retrieve the Role IDs and Role Names from BirdCRM and then setup the roles custom attribute in Okta to map to the Role IDs in BirdCRM.

BirdCRM Steps

1. To retrieve the Role IDs and Role Names from BirdCRM, first navigate to the Access Roles page here.

2. Make a note of each role you would like to be able to assign from Okta and take a copy of the Role ID by clicking on the Copy Role ID button next to the role name (this will copy the Role ID to your clipboard). You can of course also leave this tab open and switch to it to copy each role details as required.

Okta Steps

1. From the Provisioning tab of your BirdCRM SCIM SAML application in Okta, scroll down and click on Go to Profile Editor under your application name Attribute Mappings.

2. Click on Add Attribute in the Profile Editor.

3. Enter the following information into the Add Attribute dialog box:

• Data type: string array

• Display name: roles

• Variable name: roles

• External name: roles

• External namespace: urn:ietf:params:scim:schemas:core:2.0:User

• Description: Roles in BirdCRM

• Enum: Select Define enumeration list of values

• Attribute type: Group

• Group priority: Combine values across groups

4. The Attribute members section is where you fill out any Roles you want to be able to assign to users from Okta. The Display Name should be the Role Name but doesn’t have to match BirdCRM. The Value must be the UUID of the Role (Role ID) as this is what is used to match the role and assign it in BirdCRM.

5. Once you have added the Roles you require under Attribute Members you can click Save.

6. Now when you assign the BirdCRM SCIM application to a group or individual, you will be prompted to select one or more roles which will be automatically assigned to the users in the group (or individual user) via SCIM.

Team-based role assignment

Team-based Role Assignments allow a lot of flexibility in how you manage your user’s access to BirdCRM. You can scope roles to one or more workspaces and create granular access which is automatically managed via Okta.

In order to set up Team-based Role Assignment, you first need to push any groups to BirdCRM Teams and then assign the roles you would like per Team. Once you have the roles setup any users you add to the synced Okta groups will automatically receive the roles defined on the BirdCRM Teams.

Okta Steps

1. Identify any Okta Groups you would like to push to your BirdCRM organization. For each group you would like to push/sync, make sure to assign your BirdCRM SCIM application to the Group. It is also a good idea to assign your BirdCRM SSO application to the group to make sure any users can also use that to login. This is not mandatory though.

2. Next, navigate to the Push Groups tab of your BirdCRM SCIM application. If you do not see the Push Groups tab then you need to enable Push Groups which is described in Step 8. Of the SCIM Setup under the Okta Steps.

3. Click on the Push Groups button and select either option. For the sake of simplicity we will select Find groups by name to select a single group to push to BirdCRM.

4. Type in the name of the Okta group you would like to push to your BirdCRM organization and select it

5. You can leave the settings as default to automatically create the group in your BirdCRM organization or modify as desired and then click Save.

6. Repeat these steps for all Okta groups you would like to sync to your BirdCRM organization. If the Groups already have users in them they will be synced and all groups selected here will be created in your BirdCRM organization.

BirdCRM Steps

1. Navigate to the Teams section of the Organization tab in Settings which is available here.

2. Click on the Team you would like to assign a role or multiple roles to and click Edit team.

3. The Team settings page will open and you can click Add new role to allow a role to be selected.

4. Add one or more roles and optionally you can restrict the role to one or more workspaces per role.

5. Click on Update and the roles will then be assigned to any Users of the Team.

Any new users that are added to the linked Okta group will then get added to the team and receive the associated roles.