Okta setup - Workspace IAM

To set up SCIM in Okta for Bird with the new Workspace IAM, first configure the SCIM connection and settings. For provisioning users with roles, you can either assign roles directly or push groups to Bird Groups.

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

SCIM setup

Bird Steps

1. Navigate to the SCIM Settings page which is available by visiting Admin Console and clicking on IAM and then SCIM accesskey.

1. Click on Create and a new SCIM access key will be created and presented. 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.

1. Give the application a name such as Bird 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.

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

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

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

1. Select SCIM under Provisioning and click Save.

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

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

• SCIM connector base URL: https://api.bird.com/<workspaceID>/scim/v2 where <workspaceId> is your own workspaceId you are setting up SCIM for.

• Unique identifier field for users: userName

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

• Authentication Mode: HTTP Header

• Authorization: The SCIM Access Key retrieved in Step 3. Of the Bird Instructions.

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

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

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

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

Bird Steps

1. To retrieve the Role Slugs and Role Names from Bird, first navigate to the Roles page under the IAM menu in Admin Console.

1. Make a note of each role you would like to be able to assign from Okta and take a copy of the Role Slug by selecting a role and clicking More details. The value listed is the Role Slug. In the example below it is managed:inbox_agent. 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 Bird SCIM SAML application in Okta, scroll down and click on Go to Profile Editor under your application name Attribute Mappings.

1. Click on Add Attribute in the Profile Editor.

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

• Enum: Select Define enumeration list of values

• Attribute type: Group

• Group priority: Combine values across groups

1. 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 Bird. The Value must be the Role Slug as this is what is used to match the role and assign it in Bird.

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

2. Now when you assign the Bird 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.