diff --git a/docs/vendor/team-management-saml-auth.md b/docs/vendor/team-management-saml-auth.md index c7b93970b3..cf0d8d9d2b 100644 --- a/docs/vendor/team-management-saml-auth.md +++ b/docs/vendor/team-management-saml-auth.md @@ -4,17 +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. -### Enabling SAML in Your Vendor Account +### Service Provider-Initiated Login -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/). +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. + +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 -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 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 @@ -24,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 - -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. +## Supported SAML Providers -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 tests several SAML providers, but the service should be compatible with any SAML 2.0 compliant service provider. -* Okta. For more information about integrating Okta with Replicated, see [Configure Okta](#configure-okta). +Replicated provides full support for the following SAML providers: +* 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. @@ -69,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. @@ -96,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 new file mode 100644 index 0000000000..847476ce56 --- /dev/null +++ b/docs/vendor/team-management-scim-provisioning.mdx @@ -0,0 +1,342 @@ +# 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 + +The following operations are supported: + +- User creation +- User deactivation +- User deletion +- User filtering +- Pagination +- Email migration (automatic handling of email conflicts across teams) + +## Limitations + +The following operations are not supported: + +- 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. + +## Requirements + +Before you configure SCIM, ensure that: + +* 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. +* Your identity provider supports SCIM v2.0. + +## Configure SCIM + +### 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. +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 +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 + +:::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. + +### 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. + +## 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 + +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 [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. + 1. Confirm that the system returns the existing user by email as expected: + + ```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. + +1. Gradually assign all existing users, testing frequently. + +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: + +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. + +1. Verify the SCIM migration: + + ```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 + ``` + 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. + +## 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 + +# 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 +``` + +### 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 the identity provider and Replicated audit logs. + +## SCIM API + +### 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. + +**Example:** + +```bash +curl -H "Authorization: Bearer YOUR_TOKEN" \ + https://api.replicated.com/vendor/scim/v2/Users +``` + +### 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. + +**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. + +### 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 +} +``` + +## 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 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',