From acf22d68e45c1e741ff5aa94bee6ac83c1d95fd2 Mon Sep 17 00:00:00 2001 From: Grant Miller Date: Tue, 19 Aug 2025 08:49:54 -0500 Subject: [PATCH 1/4] scim --- docs/vendor/team-management-saml-auth.md | 8 +- .../team-management-scim-provisioning.mdx | 308 ++++++++++++++++++ docs/vendor/team-management.md | 6 +- sidebars.js | 1 + 4 files changed, 320 insertions(+), 3 deletions(-) create mode 100644 docs/vendor/team-management-scim-provisioning.mdx diff --git a/docs/vendor/team-management-saml-auth.md b/docs/vendor/team-management-saml-auth.md index c7b93970b3..9907136bc2 100644 --- a/docs/vendor/team-management-saml-auth.md +++ b/docs/vendor/team-management-saml-auth.md @@ -8,13 +8,17 @@ After starting out with Replicated, most teams grow, adding more developers, sup Using SAML, everyone on your team logs in with their existing usernames and passwords through your identity provider's dashboard. Users do not need to sign up through the Vendor Portal or log in with a separate Vendor Portal account, simplifying their experience. +### Service Provider Initiated Login + +You can start the SAML sign-in flow directly from the Vendor Portal. Go to the SAML login page at `https://vendor.replicated.com/login-saml`. Based on your team's SAML configuration, the Vendor Portal redirects you to your identity provider to complete authentication. IdP-initiated login from your identity provider dashboard is also supported. By default this only works for existing and invited users, however your account team can optionally enable JIT provisioning of users who input email addresses that match your team's domain (this will redirect any email with @domain.com to your IDP for auth.) + ### Enabling SAML in Your Vendor Account To enable SAML in your Vendor Portal account, you must have an Enterprise plan. For access to SAML, you can contact Replicated through [Support](https://vendor.replicated.com/support). For information about the Enterprise plan, see [pricing](https://www.replicated.com/pricing/). ### SCIM -Replicated does not implement System for Cross-domain Identity Management (SCIM). Instead, we use SAML to authenticate and create just-in-time user identities in our system. We resolve the username (email address) as the actor and use this to ensure that audit log events follow these dynamically provisioned users. If a user's email address is already associated with a Replicated account, by using your SAML integration to access the Vendor Portal, they automatically leave their current team and join the team associated with the SAML login. +For automated user provisioning and deprovisioning, you can enable System for Cross-domain Identity Management (SCIM). SCIM requires SAML to be configured first. For more information, see [Manage SCIM Provisioning (Beta)](team-management-scim-provisioning). ### Compatibility with Two-Factor Authentication @@ -31,8 +35,8 @@ You must retrieve the metadata and x.509 public certificate files from your SAML Replicated tests several SAML providers, but the service should be compatible with any SAML 2.0 compliant service provider. We provide full support for the following SAML providers: * Okta. For more information about integrating Okta with Replicated, see [Configure Okta](#configure-okta). - * OneLogin +* Duo ## Configure Okta diff --git a/docs/vendor/team-management-scim-provisioning.mdx b/docs/vendor/team-management-scim-provisioning.mdx new file mode 100644 index 0000000000..90d9d9015e --- /dev/null +++ b/docs/vendor/team-management-scim-provisioning.mdx @@ -0,0 +1,308 @@ +# Manage SCIM Provisioning (Beta) + +This topic describes how to configure SCIM (System for Cross-domain Identity Management) v2.0 provisioning for the Replicated Vendor Portal. + +:::note +SCIM provisioning is Beta. Features and availability are subject to change. +::: + +## Overview + +The Replicated Vendor Portal supports SCIM v2.0 for automated user provisioning and deprovisioning. With SCIM you can: + +- Automatically provision users from your identity provider to Replicated +- Keep user information synchronized between systems +- Automatically deprovision users when they leave your organization +- Manage the user lifecycle through your existing identity provider + +## Prerequisites + +Before you configure SCIM, ensure that: + +1. SAML SSO is configured. For more information, see [Manage SAML Authentication](team-management-saml-auth). +2. Your team has the SAML entitlement enabled. +3. You have a Vendor Service Account token with permissions to manage team members. +4. You have administrative access to your identity provider. + +## SCIM Endpoints + +Base URL: `https://api.replicated.com/vendor/scim/v2` + +### Discovery Endpoints + +- `GET /ServiceProviderConfig` — SCIM implementation capabilities +- `GET /ResourceTypes` — Supported resource types (User, Group) +- `GET /Schemas` — Detailed schema information + +### User Management Endpoints + +- `GET /Users` — List users with filtering and pagination +- `POST /Users` — Create users +- `GET /Users/{userId}` — Get a user (`userId` is the email address) +- `PATCH /Users/{userId}` — Update user (deactivation only) +- `PUT /Users/{userId}` — Replace user (deactivation only) +- `DELETE /Users/{userId}` — Delete user + +### Group Endpoints + +- `GET /Groups` — Returns an empty list (read-only for compliance) + +## Unique Identifier + +- Primary identifier: `userName` (must be the user's email address) +- Resource ID: The `id` in responses is the user's email address +- Path parameter: `userId` for endpoints like `/Users/{userId}` is the user's email address +- Uniqueness: Email must be unique within your Replicated team. Updating a user's email via SCIM is not supported; create a new user with the new email and deactivate the old one. + +:::tip +Email precedence: +1. If any entry in `emails[]` has `primary: true`, that value is used even if `userName` is set. +2. Otherwise, if `userName` is set, it is used. +3. Otherwise, if `emails[]` has values, the first `emails[0].value` is used. +::: + +## Authentication + +- Scheme: OAuth 2.0 Bearer Token +- Header: `Authorization: Bearer ` +- Token type: Replicated Vendor Service Account token scoped to your team with permissions to manage team members +- Prerequisite: SAML entitlement must be enabled for SCIM access + +Example: + +```bash +curl -H "Authorization: Bearer YOUR_TOKEN" \ + https://api.replicated.com/vendor/scim/v2/Users +``` + +## Identity Provider Configuration + +### Okta Configuration + +#### Step 1: Add Replicated Application +1. In the Okta Admin Console, go to **Applications > Applications**. +2. Create a custom SAML 2.0 application. +3. Click **Add Integration**. + +#### Step 2: Configure SAML +1. Configure SAML settings as described in [Manage SAML Authentication](team-management-saml-auth). +2. Ensure SAML is working before you proceed with SCIM. + +#### Step 3: Enable SCIM Provisioning +1. In your Okta account's Replicated application listing, go to the **Provisioning** tab. +2. Click **Configure API Integration**. +3. Check **Enable API integration**. +4. Enter the following settings: + - Base URL: `https://api.replicated.com/vendor/scim/v2` + - Unique ID: email + - Authentication Mode: HTTP + - Supported Actions: Import Users, Push New Users, Push Profile Updates (deactivate only) + - API Token: Your Replicated Vendor API token + +#### Step 4: Configure Provisioning Settings +1. Go to **Provisioning > To App**. +2. Enable the following: + - Create Users + - Update User Attributes + - Deactivate Users + +#### Step 5: Attribute Mapping +Configure the following attribute mappings: + +| Okta Attribute | Replicated Attribute | Required | Notes | +| --- | --- | --- | --- | +| `user.email` | `userName` | Yes | Primary identifier | +| `user.email` | `emails[0].value` | Recommended | Used if marked primary; otherwise only when `userName` is missing | +| `user.firstName` | `name.givenName` | Recommended | Used for display purposes | +| `user.lastName` | `name.familyName` | Recommended | Used for display purposes | +| `user.displayName` | `displayName` | Optional | Auto-generated if not provided | + +Note: Only email is strictly required. If name fields are not provided, users are created but may have incomplete profile information. Internally, Replicated stores names as `firstName` and `lastName`; these map to SCIM `name.givenName` and `name.familyName` respectively. + +#### Step 6: Assign Users +1. Go to the **Assignments** tab. +2. Assign users or groups who should have access to Replicated. +3. Users are provisioned to your Replicated team automatically. + +## Migrating from Existing User Management + +### Pre-SCIM User Synchronization + +If your team already has users in Replicated before you enable SCIM, synchronize existing users with your identity provider. + +#### Option 1: Automatic User Matching (Recommended) +1. Before you enable SCIM provisioning, ensure that all existing Replicated users have matching accounts in your identity provider. +2. Configure SCIM as described above, but do not assign users yet. +3. Test with a single user: + - Assign one existing user to the Replicated app in your identity provider. + - The system matches by email and returns the existing user. +4. Gradually assign all existing users to complete the sync. + +#### Option 2: Manual User Migration +If email addresses do not match exactly or users exist in other teams: +1. Update email addresses in Replicated or your identity provider so that they match. +2. For users existing in other Replicated teams: + - Domain authorized: The system automatically migrates the existing user's email and creates a new user. + - Domain not authorized: Manual intervention is required. Contact support. +3. Ensure that your SAML domain authorization includes all relevant email domains. + +#### Verification Steps +After migration, verify the setup: + +```bash +# List all users via SCIM to confirm sync +curl -H "Authorization: Bearer YOUR_TOKEN" \ + https://api.replicated.com/vendor/scim/v2/Users + +# Check a specific user by email +curl -H "Authorization: Bearer YOUR_TOKEN" \ + https://api.replicated.com/vendor/scim/v2/Users/user@example.com +``` + +### Migration Best Practices + +1. Test environment first. +2. Staged rollout starting with a small group of users. +3. Communicate the migration timeline. +4. Document the current user list and permissions before migration. +5. Monitor for provisioning errors during the first few days. + +### Generic SCIM Provider Configuration + +For identity providers that support SCIM v2.0: + +#### Basic Settings + +- SCIM Base URL: `https://api.replicated.com/vendor/scim/v2` +- Authentication Method: Bearer Token +- Bearer Token: Your Replicated Vendor API token +- SCIM Version: 2.0 + +#### Required Attributes + +Minimum required attributes (only email is strictly required): + +```json +{ + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], + "userName": "user@example.com" +} +``` + +Recommended full attribute set: + +```json +{ + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], + "userName": "user@example.com", + "emails": [ + { + "value": "user@example.com", + "type": "work", + "primary": true + } + ], + "name": { + "givenName": "John", + "familyName": "Doe" + }, + "active": true +} +``` + +## Supported Features + +### Supported Operations + +- User creation +- User deactivation +- User deletion +- User filtering +- Pagination +- Email migration (automatic handling of email conflicts across teams) + +### Unsupported Operations + +- User reactivation +- Password management +- Group management (read-only, returns empty results) +- Bulk operations +- Updating user attributes other than deactivation + +## Troubleshooting + +### Common Issues + +#### Authentication errors (401) + +- Verify that your API token is valid and has appropriate permissions. +- Ensure that the token is sent as `Authorization: Bearer YOUR_TOKEN`. +- Check that your team has the SAML entitlement enabled. + +#### User not found errors (404) + +- Verify that the email address is correct. SCIM uses the email as `userId`. +- Ensure that the user belongs to the correct team. +- Check that SAML domain authorization is configured properly. + +#### Email conflicts + +The system automatically handles email conflicts when a user exists in any other team if your email domain is authorized for SAML. + +If the email domain is authorized for SAML: + +- The original user's email is migrated with a `+moved{date}` suffix. +- A new user is created with the original email in the target team. +- An email notification is sent to inform the user their account was moved. +- Migration proceeds automatically. + +If the email domain is not authorized for SAML: + +- Migration is blocked for security. +- The API returns the error: "Email is already associated with another team". +- Manual intervention is required. Contact support or use a different email. + +#### Provisioning failures + +1. Check SCIM endpoint connectivity. +2. Verify that all required attributes are being sent. +3. Ensure that SAML is configured and working. +4. Review identity provider logs for specific error messages. + +### Testing SCIM Integration + +#### Manual testing + +Use curl to test SCIM endpoints: + +```bash +# Test service provider configuration +curl -H "Authorization: Bearer YOUR_TOKEN" \ + https://api.replicated.com/vendor/scim/v2/ServiceProviderConfig + +# List users +curl -H "Authorization: Bearer YOUR_TOKEN" \ + https://api.replicated.com/vendor/scim/v2/Users + +# Create user +curl -X POST \ + -H "Authorization: Bearer YOUR_TOKEN" \ + -H "Content-Type: application/scim+json" \ + -d '{ + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], + "userName": "test@example.com", + "emails": [{"value": "test@example.com", "primary": true}], + "name": {"givenName": "Test", "familyName": "User"}, + "active": true + }' \ + https://api.replicated.com/vendor/scim/v2/Users +``` + +#### Identity provider testing + +1. Test the connection using your identity provider's test feature. +2. Provision a test user and verify creation. +3. Deprovision the test user and verify deactivation. +4. Review both identity provider and Replicated audit logs. + + diff --git a/docs/vendor/team-management.md b/docs/vendor/team-management.md index dc33ede07a..86c8dbdcfb 100644 --- a/docs/vendor/team-management.md +++ b/docs/vendor/team-management.md @@ -14,6 +14,10 @@ The [Team](https://vendor.replicated.com/team/members) page provides a list of a All users, including read-only, can see the name of the RBAC role assigned to each team member. When SAML authentication is enabled, users with the built-in read-only policy cannot see the RBAC role assigned to team members. +### SCIM + +You can enable System for Cross-domain Identity Management (SCIM) for automated provisioning and deprovisioning. SCIM requires SAML to be configured first. For more information, see [Manage SCIM Provisioning (Beta)](team-management-scim-provisioning). + ## Invite Members By default, team administrators can invite more team members to collaborate. Invited users receive an email to activate their account. The activation link in the email is unique to the invited user. Following the activation link in the email also ensures that the invited user joins the team from which the invitation originated. @@ -95,7 +99,7 @@ As a Vendor Portal team admin, you can remove team members, except for the accou If the team member that you remove added their GitHub username to their Account Settings page in the Vendor Portal to access the Replicated collab repository, then the Vendor Portal also automatically removes their username from the collab repository. For more information, see [Manage Access to the Collab Repository](team-management-github-username). -SAML-created users must be removed using this method to expire their existing sessions because Replicated does not support System for Cross-domain Identity Management (SCIM). +If SCIM is not enabled, remove SAML-created users using this method to end their existing sessions. If SCIM is enabled, deprovision the user from your identity provider to deactivate the account in Replicated. To remove a member: diff --git a/sidebars.js b/sidebars.js index 6a6abea9c5..09ecd1cd5f 100644 --- a/sidebars.js +++ b/sidebars.js @@ -136,6 +136,7 @@ const sidebars = { 'vendor/team-management-two-factor-auth', 'vendor/team-management-google-auth', 'vendor/team-management-saml-auth', + 'vendor/team-management-scim-provisioning', ], }, 'vendor/team-management-slack-config', From b08e90261ef83cb20b23e7226370ea9d3cc74c32 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 19 Aug 2025 10:12:11 -0600 Subject: [PATCH 2/4] docs edits --- docs/vendor/team-management-saml-auth.md | 41 +-- .../team-management-scim-provisioning.mdx | 308 ++++++++++-------- 2 files changed, 188 insertions(+), 161 deletions(-) diff --git a/docs/vendor/team-management-saml-auth.md b/docs/vendor/team-management-saml-auth.md index 9907136bc2..cf0d8d9d2b 100644 --- a/docs/vendor/team-management-saml-auth.md +++ b/docs/vendor/team-management-saml-auth.md @@ -4,21 +4,19 @@ This topic describes how to enable or disable SAML authentication for the Replic ## About Using SAML with the Vendor Portal -After starting out with Replicated, most teams grow, adding more developers, support engineers, and sales engineers. Eventually, managing access to the Vendor Portal can become difficult. Replicated supports logging in using SAML, which lets you manage access (provisioning and unprovisioning accounts) through your SAML identity provider. +After starting out with Replicated, most teams grow, adding more developers, support engineers, and sales engineers. Eventually, managing access to the Vendor Portal can become difficult. Replicated supports logging in using SAML, which lets you manage access (provisioning and deprovisioning accounts) through your SAML identity provider. Using SAML, everyone on your team logs in with their existing usernames and passwords through your identity provider's dashboard. Users do not need to sign up through the Vendor Portal or log in with a separate Vendor Portal account, simplifying their experience. -### Service Provider Initiated Login +### Service Provider-Initiated Login -You can start the SAML sign-in flow directly from the Vendor Portal. Go to the SAML login page at `https://vendor.replicated.com/login-saml`. Based on your team's SAML configuration, the Vendor Portal redirects you to your identity provider to complete authentication. IdP-initiated login from your identity provider dashboard is also supported. By default this only works for existing and invited users, however your account team can optionally enable JIT provisioning of users who input email addresses that match your team's domain (this will redirect any email with @domain.com to your IDP for auth.) +You can start the SAML sign-in flow directly from the Vendor Portal on the SAML login page at `https://vendor.replicated.com/login-saml`. Based on your team's SAML configuration, the Vendor Portal redirects you to your identity provider to complete authentication. -### Enabling SAML in Your Vendor Account - -To enable SAML in your Vendor Portal account, you must have an Enterprise plan. For access to SAML, you can contact Replicated through [Support](https://vendor.replicated.com/support). For information about the Enterprise plan, see [pricing](https://www.replicated.com/pricing/). +IdP-initiated login from your identity provider dashboard is also supported. By default, this only works for existing and invited users. However, your account team can optionally enable JIT provisioning of users who input email addresses that match your team's domain. This will redirect any email with `@domain.com` to your IDP for authentication. ### SCIM -For automated user provisioning and deprovisioning, you can enable System for Cross-domain Identity Management (SCIM). SCIM requires SAML to be configured first. For more information, see [Manage SCIM Provisioning (Beta)](team-management-scim-provisioning). +For automated user provisioning and deprovisioning, you can also enable System for Cross-domain Identity Management (SCIM). SCIM requires SAML to be configured first. For more information, see [Manage SCIM Provisioning (Beta)](team-management-scim-provisioning). ### Compatibility with Two-Factor Authentication @@ -28,18 +26,25 @@ If SAML authentication is configured for your team, Replicated two-factor authen Replicated supports Role Based Access Control (RBAC) in the Vendor Portal. To use RBAC with SAML, you must configure policies and add users to the policies by their username. Usernames are the identity of the user in your identity provide (IDP). Typically, this username is the full email address. For more information about configuring RBAC, see [Configure RBAC Policies](team-management-rbac-configuring). -## Downloading Certificates from Supported SAML providers +## Supported SAML Providers -You must retrieve the metadata and x.509 public certificate files from your SAML provider before configuring SAML in the Vendor Portal. The certificate file must be in PEM format. +Replicated tests several SAML providers, but the service should be compatible with any SAML 2.0 compliant service provider. -Replicated tests several SAML providers, but the service should be compatible with any SAML 2.0 compliant service provider. We provide full support for the following SAML providers: +Replicated provides full support for the following SAML providers: -* Okta. For more information about integrating Okta with Replicated, see [Configure Okta](#configure-okta). +* Okta * OneLogin * Duo +## Configure and Enable SAML + +### Prerequisites + +* To enable SAML in your Vendor Portal account, you must have an Enterprise plan. For access to SAML, you can contact Replicated through [Support](https://vendor.replicated.com/support). For information about the Enterprise plan, see [pricing](https://www.replicated.com/pricing/). -## Configure Okta +* Download certificates from supported SAML providers: You must retrieve the metadata and x.509 public certificate files from your SAML provider before configuring SAML in the Vendor Portal. The certificate file must be in PEM format. + +### Configure Okta The first part of the Vendor Portal and Okta integration is configured in the Okta dashboard. This configuration lets you download the XML Metadata file and x.509 public certificate in PEM format required for the SAML authentication. @@ -73,18 +78,14 @@ To configure Okta and download the required files: 1. Click **Identity provider metadata** to download the Metadata.xml file. This likely opens an XML download that you can right-click and select **Save Link As…** to download this file. -### Next Step +#### Next Step Configure and enable SAML in the Vendor Portal. For more information, see [Configure SAML](#configure-saml). -## Configure SAML +### Configure SAML When you initially configure SAML, we do not recommend that you disable username/password access at the same time. It is possible, and recommended during testing, to support both SAML and non-SAML authentication on your account simultaneously. -**Prerequisite** - -- Download your XML Metadata file and x.509 public certificate PEM file from your SAML provider. For more information on supported SAML providers and how to find these files, see [Supported SAML providers](#downloading-certificates-from-supported-saml-providers). - To configure SAML: 1. Log in to the Vendor Portal [Team Members page](https://vendor.replicated.com/team/members) as a user with Admin access. @@ -100,11 +101,11 @@ To configure SAML: 1. Click **Upload Metadata & Cert**. -### Next Step +#### Next Step At this point, SAML is configured, but not enabled. The next step is to enable SAML enforcement options. For more information, see [Enable SAML Enforcement](#enable-saml-enforcement). -## Enable SAML Enforcement +### Enable SAML Enforcement After you have uploaded the metadata and x.509 public certificate PEM file, you must enable SAML enforcement options. Replicated provides options that can be enabled or disabled at any time. You can also change the IDP metadata if needed. diff --git a/docs/vendor/team-management-scim-provisioning.mdx b/docs/vendor/team-management-scim-provisioning.mdx index 90d9d9015e..1e10fb80c8 100644 --- a/docs/vendor/team-management-scim-provisioning.mdx +++ b/docs/vendor/team-management-scim-provisioning.mdx @@ -15,67 +15,37 @@ The Replicated Vendor Portal supports SCIM v2.0 for automated user provisioning - Automatically deprovision users when they leave your organization - Manage the user lifecycle through your existing identity provider -## Prerequisites +The following operations are supported: -Before you configure SCIM, ensure that: - -1. SAML SSO is configured. For more information, see [Manage SAML Authentication](team-management-saml-auth). -2. Your team has the SAML entitlement enabled. -3. You have a Vendor Service Account token with permissions to manage team members. -4. You have administrative access to your identity provider. - -## SCIM Endpoints - -Base URL: `https://api.replicated.com/vendor/scim/v2` - -### Discovery Endpoints - -- `GET /ServiceProviderConfig` — SCIM implementation capabilities -- `GET /ResourceTypes` — Supported resource types (User, Group) -- `GET /Schemas` — Detailed schema information - -### User Management Endpoints - -- `GET /Users` — List users with filtering and pagination -- `POST /Users` — Create users -- `GET /Users/{userId}` — Get a user (`userId` is the email address) -- `PATCH /Users/{userId}` — Update user (deactivation only) -- `PUT /Users/{userId}` — Replace user (deactivation only) -- `DELETE /Users/{userId}` — Delete user - -### Group Endpoints +- User creation +- User deactivation +- User deletion +- User filtering +- Pagination +- Email migration (automatic handling of email conflicts across teams) -- `GET /Groups` — Returns an empty list (read-only for compliance) +## Limitations -## Unique Identifier +The following operations are not supported: -- Primary identifier: `userName` (must be the user's email address) -- Resource ID: The `id` in responses is the user's email address -- Path parameter: `userId` for endpoints like `/Users/{userId}` is the user's email address -- Uniqueness: Email must be unique within your Replicated team. Updating a user's email via SCIM is not supported; create a new user with the new email and deactivate the old one. +- User reactivation +- Password management +- Group management (read-only, returns empty results) +- Bulk operations +- Updating user attributes other than deactivation. For example, updating a user's email via SCIM is not supported; create a new user with the new email and deactivate the old one. -:::tip -Email precedence: -1. If any entry in `emails[]` has `primary: true`, that value is used even if `userName` is set. -2. Otherwise, if `userName` is set, it is used. -3. Otherwise, if `emails[]` has values, the first `emails[0].value` is used. -::: +## Requirements -## Authentication +Before you configure SCIM, ensure that: -- Scheme: OAuth 2.0 Bearer Token -- Header: `Authorization: Bearer ` -- Token type: Replicated Vendor Service Account token scoped to your team with permissions to manage team members -- Prerequisite: SAML entitlement must be enabled for SCIM access +* SAML SSO is configured. For more information, see [Manage SAML Authentication](team-management-saml-auth). +* Your team has the SAML entitlement enabled. +* You have a Vendor Service Account token with permissions to manage team members. See [Generate API Tokens](/vendor/replicated-api-tokens). +* You have administrative access to your identity provider. -Example: +## Configure SCIM -```bash -curl -H "Authorization: Bearer YOUR_TOKEN" \ - https://api.replicated.com/vendor/scim/v2/Users -``` - -## Identity Provider Configuration +You can configure SCIM using identity providers that support SCIM v2.0. ### Okta Configuration @@ -93,11 +63,11 @@ curl -H "Authorization: Bearer YOUR_TOKEN" \ 2. Click **Configure API Integration**. 3. Check **Enable API integration**. 4. Enter the following settings: - - Base URL: `https://api.replicated.com/vendor/scim/v2` - - Unique ID: email - - Authentication Mode: HTTP - - Supported Actions: Import Users, Push New Users, Push Profile Updates (deactivate only) - - API Token: Your Replicated Vendor API token + - **Base URL:** `https://api.replicated.com/vendor/scim/v2` + - **Unique ID:** email + - **Authentication Mode:** HTTP + - **Supported Actions:** Import Users, Push New Users, Push Profile Updates (deactivate only) + - **API Token:** Your Replicated Vendor API token #### Step 4: Configure Provisioning Settings 1. Go to **Provisioning > To App**. @@ -117,59 +87,84 @@ Configure the following attribute mappings: | `user.lastName` | `name.familyName` | Recommended | Used for display purposes | | `user.displayName` | `displayName` | Optional | Auto-generated if not provided | -Note: Only email is strictly required. If name fields are not provided, users are created but may have incomplete profile information. Internally, Replicated stores names as `firstName` and `lastName`; these map to SCIM `name.givenName` and `name.familyName` respectively. +:::note +If name fields are not provided, users are still created, but might have incomplete profile information. Internally, Replicated stores names as `firstName` and `lastName`; these map to SCIM `name.givenName` and `name.familyName` respectively. +::: #### Step 6: Assign Users 1. Go to the **Assignments** tab. -2. Assign users or groups who should have access to Replicated. -3. Users are provisioned to your Replicated team automatically. +2. Assign users or groups to grant access to Replicated. + +Users are provisioned to your Replicated team automatically. + +### Migrate from Existing User Management + +If your team already has users in Replicated before you enable SCIM, you can synchronize the existing users with your identity provider. Before you begin, review the best practices: +* Test the environment first. +* Perform a staged rollout starting with a small group of users. +* Communicate the migration timeline. +* Document the current user list and permissions before migration. +* Monitor for provisioning errors during the first few days. + +#### (Recommended) Automatic User Matching + +To automatically match users: + +1. Ensure that all existing Replicated users have matching accounts in your identity provider. If email addresses do not match exactly or users exist in other teams, follow the steps in [Manual User Migration](#manual-user-migration) below. + +1. Configure SCIM as described in [Idenitty Provider Configuration](#identity-provider-configuration) above, but do not assign any users yet. -## Migrating from Existing User Management +1. Test with a single user: + 1. Assign one existing user to the Replicated application in your identity provider. + 1. Confirm that the system returns the existing user by email as expected: -### Pre-SCIM User Synchronization + ```bash + # Check a specific user by email + curl -H "Authorization: Bearer YOUR_TOKEN" \ + https://api.replicated.com/vendor/scim/v2/Users/user@example.com + ``` + Where `YOUR_TOKEN` is a Replicated Vendor Service Account token scoped to your team with permissions to manage team members. For more information, see [Authentication](#authentication) below. -If your team already has users in Replicated before you enable SCIM, synchronize existing users with your identity provider. +1. Gradually assign all existing users, testing frequently. -#### Option 1: Automatic User Matching (Recommended) -1. Before you enable SCIM provisioning, ensure that all existing Replicated users have matching accounts in your identity provider. -2. Configure SCIM as described above, but do not assign users yet. -3. Test with a single user: - - Assign one existing user to the Replicated app in your identity provider. - - The system matches by email and returns the existing user. -4. Gradually assign all existing users to complete the sync. +1. Run the following command to confirm that all users were synchronized: + + ```bash + # List all users via SCIM to confirm sync + curl -H "Authorization: Bearer YOUR_TOKEN" \ + https://api.replicated.com/vendor/scim/v2/Users + ``` + +#### Manual User Migration + +If email addresses do not match exactly or users exist in other teams, you can manually sync users instead. + +To manually migrate users: -#### Option 2: Manual User Migration -If email addresses do not match exactly or users exist in other teams: 1. Update email addresses in Replicated or your identity provider so that they match. -2. For users existing in other Replicated teams: - - Domain authorized: The system automatically migrates the existing user's email and creates a new user. - - Domain not authorized: Manual intervention is required. Contact support. -3. Ensure that your SAML domain authorization includes all relevant email domains. -#### Verification Steps -After migration, verify the setup: +2. For users existing in other Replicated teams: + - **Domain authorized:** The system automatically migrates the existing user's email and creates a new user. + - **Domain not authorized:** Manual intervention is required. Contact support. -```bash -# List all users via SCIM to confirm sync -curl -H "Authorization: Bearer YOUR_TOKEN" \ - https://api.replicated.com/vendor/scim/v2/Users +3. Ensure that your SAML domain authorization includes all relevant email domains. -# Check a specific user by email -curl -H "Authorization: Bearer YOUR_TOKEN" \ - https://api.replicated.com/vendor/scim/v2/Users/user@example.com -``` +1. Verify the SCIM migration: -### Migration Best Practices + ```bash + # List all users via SCIM to confirm sync + curl -H "Authorization: Bearer YOUR_TOKEN" \ + https://api.replicated.com/vendor/scim/v2/Users -1. Test environment first. -2. Staged rollout starting with a small group of users. -3. Communicate the migration timeline. -4. Document the current user list and permissions before migration. -5. Monitor for provisioning errors during the first few days. + # Check a specific user by email + curl -H "Authorization: Bearer YOUR_TOKEN" \ + https://api.replicated.com/vendor/scim/v2/Users/user@example.com + ``` + Where `YOUR_TOKEN` is a Replicated Vendor Service Account token scoped to your team with permissions to manage team members. For more information, see [Authentication](#authentication) below. ### Generic SCIM Provider Configuration -For identity providers that support SCIM v2.0: +For identity providers that support SCIM v2.0, use the basic settings and attributes described below to configure SCIM. For more information, see [SCIM API](#scim-api) below. #### Basic Settings @@ -210,70 +205,61 @@ Recommended full attribute set: } ``` -## Supported Features +## SCIM API -### Supported Operations +### Authentication -- User creation -- User deactivation -- User deletion -- User filtering -- Pagination -- Email migration (automatic handling of email conflicts across teams) +- **Scheme:** OAuth 2.0 Bearer Token +- **Header:** `Authorization: Bearer ` +- **Token type:** Replicated Vendor Service Account token scoped to your team with permissions to manage team members. -### Unsupported Operations +**Example:** -- User reactivation -- Password management -- Group management (read-only, returns empty results) -- Bulk operations -- Updating user attributes other than deactivation - -## Troubleshooting - -### Common Issues - -#### Authentication errors (401) +```bash +curl -H "Authorization: Bearer YOUR_TOKEN" \ + https://api.replicated.com/vendor/scim/v2/Users +``` -- Verify that your API token is valid and has appropriate permissions. -- Ensure that the token is sent as `Authorization: Bearer YOUR_TOKEN`. -- Check that your team has the SAML entitlement enabled. +### SCIM Endpoints -#### User not found errors (404) +Base URL: `https://api.replicated.com/vendor/scim/v2` -- Verify that the email address is correct. SCIM uses the email as `userId`. -- Ensure that the user belongs to the correct team. -- Check that SAML domain authorization is configured properly. +#### Discovery Endpoints -#### Email conflicts +- `GET /ServiceProviderConfig` — SCIM implementation capabilities +- `GET /ResourceTypes` — Supported resource types (User, Group) +- `GET /Schemas` — Detailed schema information -The system automatically handles email conflicts when a user exists in any other team if your email domain is authorized for SAML. +#### User Management Endpoints -If the email domain is authorized for SAML: +- `GET /Users` — List users with filtering and pagination +- `POST /Users` — Create users +- `GET /Users/{userId}` — Get a user (`userId` is the email address) +- `PATCH /Users/{userId}` — Update user (deactivation only) +- `PUT /Users/{userId}` — Replace user (deactivation only) +- `DELETE /Users/{userId}` — Delete user -- The original user's email is migrated with a `+moved{date}` suffix. -- A new user is created with the original email in the target team. -- An email notification is sent to inform the user their account was moved. -- Migration proceeds automatically. +#### Group Endpoints -If the email domain is not authorized for SAML: +- `GET /Groups` — Returns an empty list (read-only for compliance) -- Migration is blocked for security. -- The API returns the error: "Email is already associated with another team". -- Manual intervention is required. Contact support or use a different email. +### Unique Identifier -#### Provisioning failures +- **Primary identifier:** `userName` (must be the user's email address) +- **Resource ID:** The `id` in responses is the user's email address +- **Path parameter:** `userId` for endpoints like `/Users/{userId}` is the user's email address +- **Uniqueness:** Email must be unique within your Replicated team. Updating a user's email via SCIM is not supported; create a new user with the new email and deactivate the old one. -1. Check SCIM endpoint connectivity. -2. Verify that all required attributes are being sent. -3. Ensure that SAML is configured and working. -4. Review identity provider logs for specific error messages. +**Email precedence:** +1. If any entry in `emails[]` has `primary: true`, that value is used even if `userName` is set. +2. Otherwise, if `userName` is set, it is used. +3. Otherwise, if `emails[]` has values, the first `emails[0].value` is used. -### Testing SCIM Integration +## Test the SCIM Integration -#### Manual testing +### Test SCIM Endpoints -Use curl to test SCIM endpoints: +You can use the following curl commands to manually test SCIM endpoints: ```bash # Test service provider configuration @@ -298,11 +284,51 @@ curl -X POST \ https://api.replicated.com/vendor/scim/v2/Users ``` -#### Identity provider testing +### Test Using Your Identity Provider + +To test the SCIM integration using your identity provider: 1. Test the connection using your identity provider's test feature. 2. Provision a test user and verify creation. 3. Deprovision the test user and verify deactivation. -4. Review both identity provider and Replicated audit logs. +4. Review both the identity provider and Replicated audit logs. + +## Troubleshooting + +The section includes information about troubleshooting common issues with SCIM. + +#### Authentication errors (401) + +- Verify that your API token is valid and has appropriate permissions. +- Ensure that the token is sent as `Authorization: Bearer YOUR_TOKEN`. +- Check that your team has the SAML entitlement enabled. + +#### User not found errors (404) + +- Verify that the email address is correct. SCIM uses the email as `userId`. +- Ensure that the user belongs to the correct team. +- Check that SAML domain authorization is configured properly. + +#### Email conflicts +The system automatically handles email conflicts when a user exists in any other team if your email domain is authorized for SAML. + +If the email domain is authorized for SAML: + +- The original user's email is migrated with a `+moved{date}` suffix. +- A new user is created with the original email in the target team. +- An email notification is sent to inform the user their account was moved. +- Migration proceeds automatically. + +If the email domain is not authorized for SAML: +- Migration is blocked for security. +- The API returns the error: "Email is already associated with another team". +- Manual intervention is required. Contact support or use a different email. + +#### Provisioning failures + +1. Check SCIM endpoint connectivity. +2. Verify that all required attributes are being sent. +3. Ensure that SAML is configured and working. +4. Review identity provider logs for specific error messages. \ No newline at end of file From 862f100dc6210c8c339f7f28454a740706bdf79e Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 19 Aug 2025 10:55:02 -0600 Subject: [PATCH 3/4] edit --- docs/vendor/team-management-scim-provisioning.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/vendor/team-management-scim-provisioning.mdx b/docs/vendor/team-management-scim-provisioning.mdx index 1e10fb80c8..5c4576154a 100644 --- a/docs/vendor/team-management-scim-provisioning.mdx +++ b/docs/vendor/team-management-scim-provisioning.mdx @@ -164,7 +164,7 @@ To manually migrate users: ### Generic SCIM Provider Configuration -For identity providers that support SCIM v2.0, use the basic settings and attributes described below to configure SCIM. For more information, see [SCIM API](#scim-api) below. +For identity providers that support SCIM v2.0, use the basic settings and attributes described below to integrate with Replicated. For more information, see [SCIM API](#scim-api) below. #### Basic Settings From 4e4d586d621d2df850e9dda5d00d3c59600f8f4b Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 19 Aug 2025 17:08:19 -0600 Subject: [PATCH 4/4] edits --- .../team-management-scim-provisioning.mdx | 154 +++++++++--------- 1 file changed, 81 insertions(+), 73 deletions(-) diff --git a/docs/vendor/team-management-scim-provisioning.mdx b/docs/vendor/team-management-scim-provisioning.mdx index 5c4576154a..847476ce56 100644 --- a/docs/vendor/team-management-scim-provisioning.mdx +++ b/docs/vendor/team-management-scim-provisioning.mdx @@ -42,13 +42,14 @@ Before you configure SCIM, ensure that: * Your team has the SAML entitlement enabled. * You have a Vendor Service Account token with permissions to manage team members. See [Generate API Tokens](/vendor/replicated-api-tokens). * You have administrative access to your identity provider. +* Your identity provider supports SCIM v2.0. ## Configure SCIM -You can configure SCIM using identity providers that support SCIM v2.0. - ### Okta Configuration +This section describes how to enable SCIM provisioning for Replicated in Okta. For other identity providers, see [Other Identity Providers](#other-identity-providers) below. + #### Step 1: Add Replicated Application 1. In the Okta Admin Console, go to **Applications > Applications**. 2. Create a custom SAML 2.0 application. @@ -92,27 +93,45 @@ If name fields are not provided, users are still created, but might have incompl ::: #### Step 6: Assign Users + +:::note +If your team already has users in Replicated, synchronize them with Okta before you assign users. See [Migrate from Existing User Management](#migrate) below. +::: + +To assign users in Okta: 1. Go to the **Assignments** tab. 2. Assign users or groups to grant access to Replicated. Users are provisioned to your Replicated team automatically. -### Migrate from Existing User Management +### Other Identity Providers + +For identity providers other than Okta, you can use the following basic settings to configure SCIM: +- **SCIM Base URL:** `https://api.replicated.com/vendor/scim/v2` +- **Authentication Method:** Bearer Token +- **Bearer Token:** Your Replicated Vendor API token +- **SCIM Version:** 2.0 + +For more information, see [SCIM API](#scim-api) below. -If your team already has users in Replicated before you enable SCIM, you can synchronize the existing users with your identity provider. Before you begin, review the best practices: +## Migrate from Existing User Management {#migrate} + +If your team already has users in Replicated before you enable SCIM, you can synchronize the existing users with your identity provider. + +The following are best practices for migrating from existing user management: * Test the environment first. * Perform a staged rollout starting with a small group of users. * Communicate the migration timeline. * Document the current user list and permissions before migration. * Monitor for provisioning errors during the first few days. -#### (Recommended) Automatic User Matching +### (Recommended) Automatic User Matching To automatically match users: 1. Ensure that all existing Replicated users have matching accounts in your identity provider. If email addresses do not match exactly or users exist in other teams, follow the steps in [Manual User Migration](#manual-user-migration) below. -1. Configure SCIM as described in [Idenitty Provider Configuration](#identity-provider-configuration) above, but do not assign any users yet. +1. Configure SCIM as described in [Okta Configuration](#okta-configuration) above, but do not assign any users yet. 1. Test with a single user: 1. Assign one existing user to the Replicated application in your identity provider. @@ -135,7 +154,7 @@ To automatically match users: https://api.replicated.com/vendor/scim/v2/Users ``` -#### Manual User Migration +### Manual User Migration If email addresses do not match exactly or users exist in other teams, you can manually sync users instead. @@ -162,48 +181,43 @@ To manually migrate users: ``` Where `YOUR_TOKEN` is a Replicated Vendor Service Account token scoped to your team with permissions to manage team members. For more information, see [Authentication](#authentication) below. -### Generic SCIM Provider Configuration - -For identity providers that support SCIM v2.0, use the basic settings and attributes described below to integrate with Replicated. For more information, see [SCIM API](#scim-api) below. +## Test the SCIM Integration -#### Basic Settings +### Test SCIM Endpoints -- SCIM Base URL: `https://api.replicated.com/vendor/scim/v2` -- Authentication Method: Bearer Token -- Bearer Token: Your Replicated Vendor API token -- SCIM Version: 2.0 +You can use the following curl commands to manually test SCIM endpoints: -#### Required Attributes +```bash +# Test service provider configuration +curl -H "Authorization: Bearer YOUR_TOKEN" \ + https://api.replicated.com/vendor/scim/v2/ServiceProviderConfig -Minimum required attributes (only email is strictly required): +# List users +curl -H "Authorization: Bearer YOUR_TOKEN" \ + https://api.replicated.com/vendor/scim/v2/Users -```json -{ - "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], - "userName": "user@example.com" -} +# Create user +curl -X POST \ + -H "Authorization: Bearer YOUR_TOKEN" \ + -H "Content-Type: application/scim+json" \ + -d '{ + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], + "userName": "test@example.com", + "emails": [{"value": "test@example.com", "primary": true}], + "name": {"givenName": "Test", "familyName": "User"}, + "active": true + }' \ + https://api.replicated.com/vendor/scim/v2/Users ``` -Recommended full attribute set: +### Test Using Your Identity Provider -```json -{ - "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], - "userName": "user@example.com", - "emails": [ - { - "value": "user@example.com", - "type": "work", - "primary": true - } - ], - "name": { - "givenName": "John", - "familyName": "Doe" - }, - "active": true -} -``` +To test the SCIM integration using your identity provider: + +1. Test the connection using your identity provider's test feature. +2. Provision a test user and verify creation. +3. Deprovision the test user and verify deactivation. +4. Review both the identity provider and Replicated audit logs. ## SCIM API @@ -255,43 +269,37 @@ Base URL: `https://api.replicated.com/vendor/scim/v2` 2. Otherwise, if `userName` is set, it is used. 3. Otherwise, if `emails[]` has values, the first `emails[0].value` is used. -## Test the SCIM Integration - -### Test SCIM Endpoints - -You can use the following curl commands to manually test SCIM endpoints: - -```bash -# Test service provider configuration -curl -H "Authorization: Bearer YOUR_TOKEN" \ - https://api.replicated.com/vendor/scim/v2/ServiceProviderConfig +### Required Attributes -# List users -curl -H "Authorization: Bearer YOUR_TOKEN" \ - https://api.replicated.com/vendor/scim/v2/Users +Minimum required attributes (only email is strictly required): -# Create user -curl -X POST \ - -H "Authorization: Bearer YOUR_TOKEN" \ - -H "Content-Type: application/scim+json" \ - -d '{ - "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], - "userName": "test@example.com", - "emails": [{"value": "test@example.com", "primary": true}], - "name": {"givenName": "Test", "familyName": "User"}, - "active": true - }' \ - https://api.replicated.com/vendor/scim/v2/Users +```json +{ + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], + "userName": "user@example.com" +} ``` -### Test Using Your Identity Provider - -To test the SCIM integration using your identity provider: +Recommended full attribute set: -1. Test the connection using your identity provider's test feature. -2. Provision a test user and verify creation. -3. Deprovision the test user and verify deactivation. -4. Review both the identity provider and Replicated audit logs. +```json +{ + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], + "userName": "user@example.com", + "emails": [ + { + "value": "user@example.com", + "type": "work", + "primary": true + } + ], + "name": { + "givenName": "John", + "familyName": "Doe" + }, + "active": true +} +``` ## Troubleshooting