Setting up SCIM provisioning with OKTA

Anh Phung

Updated January 11, 2023 11:54

In this article, you’ll learn how to set up SCIM provisioning with Okta.

SCIM provisioning allows you to manage all your accounts in one central location – Okta, from creation until deactivation.

Note: The new version of Productboard’s Okta application that allows SCIM provisioning is currently in the approval process with Okta. You can choose to wait until our application is approved or you can use SCIM provisioning now by setting it up manually.

To learn more about SCIM provisioning in Okta, please take a look at this Okta documentation.

Prerequisites

To get started, you’ll need the following:

An Okta subscription. If you don't have a subscription, you can sign up for a one-month free trial.
A Productboard single sign-on (SSO) enabled subscription (available on the Enterprise plan).

Setting up SAML SSO for SCIM

The new version of Productboard’s Okta application that allows SCIM provisioning is currently in the approval process with Okta. If you want to use SCIM provisioning now, you can configure it via the custom app integration. Once the new version is approved, you’ll find SCIM provisioning in the Productboard application in Okta’s catalog.

If you don’t have SAML SSO set up yet. Please follow the steps in this article and make sure you don’t use Productboard application from Okta’s catalog. You can skip configuration for default role in Okta because SCIM provisioning will update the Productboard member roles from now on.
If you’ve set up SAML SSO using the custom app integration based on this SSO article, then please proceed to Configure SCIM provisioning. Also, we recommend you get rid of the configuration for the default role because SCIM will update the roles from now on.
If you’ve set up SAML SSO by adding the Productboard application from Okta’s catalog, then please follow the next steps.
If you don’t know if your SAML SSO was set up with custom app integration or with the Productboard application from Okta’s catalog, then please check for the check box in General > App Settings Enable SCIM provisioning. If it’s checked, then the custom app integration method was used.

Note: For advanced OKTA admins – You can use one application in OKTA for SSO and one for provisioning, but we consider that a bit tedious therefore we don’t recommend it.

Configure custom app integration

Go to Applications, select Applications, and then select Add Application.
Click on Create App Integration and set the application as the following:

Make sure you fill in the following fields correctly:
- Single sign on URL:
```
https://{workspace_name}.productboard.com/users/auth/saml/callback
```
  and check the option Use this for Recipient URL and Destination URL.
- Audience URI (SP Entity ID):
```
productboard
```
```
 
```
- Name ID format:
```
EmailAddress
```
- Attribute statements:
  - lastName: user.lastName
  - firstName: user.firstName
Click on Save new application.
Fill out the feedback section according to the screenshot below and click Finish.

Assigning members

Now, assign all your Productboard members to the new custom app integration you’ve just created. Make sure to add yourself because you will have to authorize the SAML SSO in the next step.

Authorizing SAML SSO in Productboard

First, open the Sign On tab in the Productboard app in Okta, then select Actions and click on View IdP metadata.
Open the link (View IdP metadata) and Copy the URL over there. The URL should look like this:
```
https://<your_okta_space>.okta.com/app/asdasdadgtrrd/sso/saml/metadata
```

Go to

https://<your_workspace>.productboard.com/

Go to Settings under the Profile menu. Your SSO configuration should look like the screenshot below.
Select From Metadata.
Paste the new URL you copied in step 2 to the Manifest URL field.
Click Save & authorize.
Click the red Authorize button.
You will be redirected to Productboard, where you will be asked to sign in under SAML SSO to authorize the configuration.
Click on Sign in with Okta account. If the configuration leads to an error, your old configuration is still there and working, so your users can still log in to Productboard with SSO. You can check the SAML SSO configuration and try again. To troubleshoot the issue, please go to Troubleshooting Okta issues.
The old Productboard application in Okta is not used anymore because SAML SSO goes through the new one we’ve just created. You can delete the old one in Okta.

Configuring SCIM provisioning

Go to

https://<your_workspace>.productboard.com/

Go to Settings under the Profile menu.
Toggle on SCIM Provisioning
Go to your Okta and in your Productboard custom app integration, select the General tab**.**
Check the option Enable SCIM provisioning.
Click Save.
Then go to the Provisioning tab and click on Edit.
Make sure you fill in the following fields correctly:
- SCIM connector base URL:
```
https://api.productboard.com/scim/v2
```
- Unique identifier field for users:
```
userName
```
Check Supported provisioning actions according to the screenshot below.
For Authentication Mode, choose HTTP Header.

To generate the authorization token, go to

https://<your_workspace>.productboard.com/

Go to Integrations under the Profile menu.
In the Public API section, click on (+) button to generate a new access token and provide a name for the Access token.
Click Copy, go to Okta and paste the token to the Authorization field (see screenshot in step 8).
Click on Test Connector Configuration. If the filled-in data are correct, you should see this screenshot below. Close the Test Connector Configuration dialog.
Save the configuration.
You will be redirected to the Provisioning tab. Update the configuration according to the screenshot below.
Click Save.
Go to Directory, then Profile Editor and find your productboard User and open it.
Click on + Add Attribute and make sure you fill out the following fields correctly:
- Data type:
```
string
```
- Variable name:
```
role
```
- External name:
```
roles.^[primary==true].value
```
- External namespace:
```
urn:ietf:params:scim:schemas:core:2.0:User
```
Check the Define enumerated list of values and define these Productboard roles: admin, maker, contributor, viewer, and check Attribute required.
Click on Save.

Note: Leave the User Personal attribute unchecked if you want to configure roles (admin, contributor, etc.) on a group basis. Check User Personal if you want to manage roles on a user basis only. We talk about roles in Okta in detail in this article. For now, you can leave it unchecked because it allows you to do both.

Provisioning your users

Users assigned before SCIM provisioning was enabled

Once you’ve enabled SCIM provisioning, all your user assignments will show an error (see the screenshot below). Click on Provision User and those errors will disappear. It schedules a job that links Okta users with members in Productboard. If there’s no such member in Productboard it creates a new member.

Screenshot_2022-12-20_at_18.53.56.png

In Productboard, the existing users are now SCIM provisioned and won’t be editable. For example, the last user in the screenshot below isn’t SCIM provisioned and is still editable.

Screenshot_2022-12-20_at_20.18.17.png

Note: The Role in Okta and in Productboard does not match. At this point, every user in Okta seemingly has the admin role assigned. It’s not actually assigned to them though, it’s just the first option you can choose. admin was the first option you filled in during the configuration of the Role field. Once you choose the option and click Save it gets actually set and updated in Productboard. To learn more about how to handle Productboard roles in Okta, read this article.

Screenshot_2022-12-30_at_15.57.30.png

Provisioning new users

In your Productboard application in Okta, assign a new user.
Select the Role attribute that we defined in step 20 above.

Screenshot_2022-12-20_at_22.25.24.png

You should see the new user right away in Productboard.

You can play around and test that everything is working.