# 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 Groups 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](#scim-setup) * [Direct role assignment](#direct-role-assignment) * [Group-based role assignment](#group-based-role-assignment) ## SCIM setup #### BirdCRM Steps 1. Navigate to the SCIM Settings page which is available [here](https://app.bird.com/settings/security/scim-settings) 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. ). 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 UR**L: 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 Groups 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**.

{% hint style="info" %} 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 Groups in BirdCRM. * Have roles directly assigned by Okta and SCIM. {% endhint %} ### 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. {% hint style="warning" %} 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. {% endhint %} 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](https://app.bird.com/settings/security/access-roles).

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.

### Group-based role assignment Group-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 Group-based Role Assignment, you first need to push any groups to BirdCRM Groups and then assign the roles you would like per Group. Once you have the roles setup any users you add to the synced Okta groups will automatically receive the roles defined on the BirdCRM Groups. #### 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 **Groups** section of the **Organization tab** in **Settings** which is available [here](https://app.bird.com/settings/organization/groups). 2. Click on the **Group** you would like to assign a role or multiple roles to and click Edit team.

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

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

3. Click on **Update** and the roles will then be assigned to any Users of the Group. {% hint style="info" %} Any new users that are added to the linked Okta group will then get added to the group and receive the associated roles. {% endhint %}