​

SCIM Integration Guide

Portkey supports SCIM (System for Cross-domain Identity Management) to automate user provisioning and deprovisioning. This guide will walk you through integrating SCIM with your identity provider to manage users and workspaces seamlessly.

​

Table of Contents

• What is SCIM?
• SCIM Base URL
• Authentication
• Supported Operations
• Required Configuration
• Identity Provider Setup
• Troubleshooting

​

What is SCIM?

SCIM is an open standard that allows organizations to automate the management of user identities and groups across applications. By integrating with SCIM, you can:

• Automatically provision and update user accounts.
• Deprovision users when they leave your organization.
• Sync user attributes and workspace memberships.

​

SCIM Base URL

To integrate SCIM with our platform, get the SCIM Base URL from Portkey Control Plane.

Admin Settings > Authentication Settings > SCIM Provisioning > SCIM URL

​

Authentication

We use Bearer Token Authentication for SCIM requests.

You need to generate an API token from Portkey Control Plane (“Admin Settings > Authentication Settings > SCIM Provisioning`) and use it as a bearer token in the SCIM requests.

You need to include the following header in the SCIM requests:

Authorization: Bearer <your-api-token>

​

Supported Operations

Our SCIM implementation supports the following operations:

​

Required Configuration

Before integrating SCIM, ensure you have the following details:

• SCIM Base URL: Provided above.
• Bearer Token: Generate this token from our platform’s API Settings section.

You will need to provide these details in your identity provider’s SCIM configuration section.

​

Identity Provider Setup

Follow your identity provider’s documentation to set up SCIM integration. Below are the key fields you’ll need to configure:

​

Common Identity Providers

​

Azure Active Directory (Azure AD)

Reference

Setting up Azure Entra for SCIM provisioning consists of the following steps:

• New Entra Application & SCIM Provisioning
• Application Roles
• SCIM Attribute Mapping Update

New Entra Application

First, create a new Azure Entra application to set up SCIM provisioning with Portkey.

1. Navigate to the Entra Applications Page and click Create your own application.

2. Complete the required fields to create a new application.

3. Once the application is created, navigate to the application’s Provisioning page under the Manage section.

4. Click New Configuration to go to the provisioning settings page.

5. Obtain the Tenant URL and Secret Token from the Portkey Admin Settings page (if SCIM is enabled for your organization).

   • Portkey Settings Page

6. Fill in the values from the Portkey dashboard in Entra’s provisioning settings and click Test Connection. If successful, click Create.

If the test connection returns any errors, please contact us at [email protected].

Application Roles

Portkey supported roles should match Entra’s application roles.

1. Navigate to App Registrations under Enterprise Applications, click All Applications, and select the application created earlier.
2. Go to the App Roles page and click Create app role.

   Portkey supports two application-level roles:

   • member (Member)
   • admin (Group)

Users assigned any other role will default to the member role.

3. To support group roles, create a role with the value group and a name in title-case (e.g., Group for the value group).

4. Assign users to the application with the desired role (e.g., member or admin) for the organization.

Attribute Mapping

Adding a New Attribute

1. Go to the Provisioning page and click Attribute Mapping (Preview) to access the attributes page.

2. Enable advanced options and click Edit attribute list for customappsso.

3. Add a new attribute called roles with the following properties:

   • Multi-valued: Enabled
   • Type: String

Removing Unnecessary Attributes

Delete the following unsupported attributes:

• preferredLanguage
• addresses (all fields)
• phoneNumbers

Updating Attributes

1. Edit the displayName field to concatenate firstName + lastName instead of using the default displayName value from Entra records.

2. Save the changes and enable provisioning on the Overview page of the provisioning settings.

Group (Workspace) Provisioning

Portkey supports RBAC (Role-Based Access Control) for workspaces mapped to groups in Entra. Use the following naming convention for groups:

• Format: ws-{group}-role-{role}
  • Role: One of admin, member, or manager
• A user should belong to only one group per {group}.

Example: For a Sales workspace:

• ws-Sales-role-admin
• ws-Sales-role-manager
• ws-Sales-role-member

Users assigned to these groups will inherit the corresponding role in Portkey.

By following these steps, you can successfully configure Azure Entra for SCIM provisioning with Portkey.

• Okta:
  Okta SCIM Setup Guide

• Google:
  Google

​

Troubleshooting

​

Common Issues

• Invalid Token: Ensure the bearer token is correctly generated and included in the request header.
• 403 Forbidden: Check if the provided SCIM Base URL and token are correct.
• User Not Provisioned: Ensure the user attributes meet our platform’s requirements.

For further assistance, please contact our support team at [email protected].