From e9ca1611efaef0f8f114eaebc03649871c373e33 Mon Sep 17 00:00:00 2001 From: Ajith Prasad <37380177+aji-aju@users.noreply.github.com> Date: Wed, 18 Jun 2025 08:02:41 +0530 Subject: [PATCH] Scim provisioning doc for collate (#21813) * Scim provisioning doc for collate * bug fixed --- .../teams-and-users/scim-provisioning.md | 163 ++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 openmetadata-docs/content/v1.8.x-SNAPSHOT/how-to-guides/admin-guide/teams-and-users/scim-provisioning.md diff --git a/openmetadata-docs/content/v1.8.x-SNAPSHOT/how-to-guides/admin-guide/teams-and-users/scim-provisioning.md b/openmetadata-docs/content/v1.8.x-SNAPSHOT/how-to-guides/admin-guide/teams-and-users/scim-provisioning.md new file mode 100644 index 00000000000..596091639b6 --- /dev/null +++ b/openmetadata-docs/content/v1.8.x-SNAPSHOT/how-to-guides/admin-guide/teams-and-users/scim-provisioning.md @@ -0,0 +1,163 @@ +# Collate SCIM Provisioning Guide + +## Prerequisites + +For a user to log in using SSO, you must configure SSO from your identity provider to Collate. + +## Important Notes + +- **Default Provisioning Schedule**: + - Azure provisioning happens once every 40 minutes by default + - Okta provisioning can be configured for real-time or scheduled intervals +- **Group Provisioning Behavior in OpenMetadata**: + - **New Group**: If your identity provider sends a group that doesn't yet exist in Collate, we'll create it at the root (under the Organization) with team type as "group" + - **Existing Group**: If the group already exists—no matter where it sits in Collate's hierarchy—we'll simply add or remove the user in that group +- **Requirement**: For provisioning to happen, you must assign users/groups to the SCIM App in your identity provider dashboard + +--- + +## Step 1: Configure Collate + +> **Note**: As of now, we will enable SCIM from the backend for the customer. In future releases, we will bring out the option to enable/disable from the UI. + +To get the secret token: +1. Navigate to **Settings** → **Bot** → **SCIM-Bot** +2. Copy the bot token + +--- + +## Step 2A: Configure Microsoft Entra ID (Azure) + +### 2A.1 Create Enterprise Application + +1. In your Azure portal, go to **Microsoft Entra ID** → **Enterprise Applications** +2. Click **+ New Application** above the application list +3. Click on **Create your own Application** +4. Enter a **Name** for the application and click **Create** + +### 2A.2 Configure Provisioning + +1. Under the **Manage** menu, click **Provisioning** +2. Set **Provisioning Mode** to **Automatic** +3. Set the **SCIM API endpoint URL** (will be provided by Collate) +4. Set **Secret Token** to the Collate SCIM token that you generated in Step 1 +5. Click **Test Connection** and wait for the confirmation message that the credentials are authorized to enable provisioning +6. Click **Save** + +### 2A.3 Assign Users and Groups + +1. In the application page, click on **Users and Groups** +2. Click **Add user/group** +3. Select the desired **user/group** +4. Click **Assign** +5. Navigate to **Overview** → **Start Provisioning** to begin the provisioning process + +--- + +## Step 2B: Configure Okta + +### 2B.1 Create SCIM Application + +1. In your Okta Admin Console, go to **Applications** → **Applications** +2. Click **Create App Integration** +3. Select **SAML 2.0** or **OIDC** for SSO (if not already configured) +4. For SCIM provisioning, go to the **Provisioning** tab in your existing application + +### 2B.2 Configure SCIM Settings + +1. In the application, click on the **Provisioning** tab +2. Click **Configure API Integration** +3. Check **Enable API integration** +4. Set the **Base URL** to the SCIM API endpoint URL (will be provided by Collate) +5. Set the **API Token** to the Collate SCIM token from Step 1 +6. Click **Test API Credentials** to verify the connection +7. Click **Save** + +### 2B.3 Configure Provisioning Settings + +1. Go to **Provisioning** → **To App** +2. Click **Edit** and enable the following: + - **Create Users**: Enable to create users in Collate + - **Update User Attributes**: Enable to sync user attribute changes + - **Deactivate Users**: Enable to deactivate users when removed from Okta +3. Configure attribute mappings: + - **userName** → **userName** + - **email** → **email** + - **firstName** → **firstName** + - **lastName** → **lastName** + - **displayName** → **displayName** +4. Click **Save** + +### 2B.4 Assign Users and Groups + +1. Go to the **Assignments** tab +2. Click **Assign** → **Assign to People** or **Assign to Groups** +3. Select the users or groups you want to provision +4. Click **Assign** and then **Save and Go Back** +5. Click **Done** + +### 2B.5 Configure Group Provisioning + +1. In the **Provisioning** tab, go to **To App** +2. Scroll down to **Group Push** section +3. Configure group provisioning options: + - **Push Groups**: Click **Push Groups** → **Find groups by name** or **Push groups by name/rule** + - **Create Groups**: Enable to automatically create groups in Collate + - **Update Group Attributes**: Enable to sync group changes +4. For automatic provisioning, set up **Push groups by name/rule**: + - Define rules like groups starting with "OM_" or "Collate_" + - Groups matching these rules will be automatically provisioned +5. Click **Save** + +> **Note**: Once configured, groups will be automatically provisioned when they match your rules or when manually pushed. You don't need to click "Push Groups" repeatedly for automatic provisioning. + +### 2B.6 Start Provisioning + +1. Go to **Provisioning** → **To App** +2. The provisioning will start automatically once users/groups are assigned +3. You can monitor the status in the **Provisioning** dashboard + +--- + +## Managing Provisioning + +### Microsoft Entra ID (Azure) +- **Stop Provisioning**: Click on **"Pause Provisioning"** +- **Test Provisioning**: Use **"Provision on demand"** +- **View Logs**: Access provisioning logs from the provisioning section + +### Okta +- **Stop Provisioning**: Disable API integration in the Provisioning tab +- **Test Provisioning**: Use **"Test API Credentials"** or check individual user provisioning status +- **View Logs**: Go to **Reports** → **System Log** and filter by the application name + +--- + +## Troubleshooting + +### Common Issues for Both Providers + +1. **Connection Issues**: + - Verify the SCIM endpoint URL is correct + - Ensure the secret token is valid and properly configured + - Check network connectivity and firewall settings + +2. **User/Group Assignment Issues**: + - Confirm users/groups are properly assigned to the application + - Verify user attributes are mapped correctly + - Check for duplicate users or conflicting email addresses + +3. **Provisioning Failures**: + - Review provisioning logs for specific error messages + - Ensure required user attributes are populated + - Verify user permissions in Collate + +### Microsoft Entra ID Specific +- Check the provisioning logs for error messages +- Verify the application is properly configured in Enterprise Applications + +### Okta Specific +- Check the System Log for SCIM-related errors +- Verify API integration is enabled and credentials are correct +- Ensure attribute mappings are configured properly +- Check if users are in the correct state (ACTIVE) in Okta