Skip to content

Commit acf22d6

Browse files
grantmillergrantmiller
committed
scim
1 parent 771dd44 commit acf22d6

File tree

4 files changed

+320
-3
lines changed

4 files changed

+320
-3
lines changed

‎docs/vendor/team-management-saml-auth.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,17 @@ After starting out with Replicated, most teams grow, adding more developers, sup
88

99
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.
1010

11+
### Service Provider Initiated Login
12+
13+
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.)
14+
1115
### Enabling SAML in Your Vendor Account
1216

1317
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/).
1418

1519
### SCIM
1620

17-
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.
21+
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).
1822

1923
### Compatibility with Two-Factor Authentication
2024

@@ -31,8 +35,8 @@ You must retrieve the metadata and x.509 public certificate files from your SAML
3135
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:
3236

3337
* Okta. For more information about integrating Okta with Replicated, see [Configure Okta](#configure-okta).
34-
3538
* OneLogin
39+
* Duo
3640

3741

3842
## Configure Okta

‎docs/vendor/team-management-scim-provisioning.mdx‎

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
1+
# Manage SCIM Provisioning (Beta)
2+
3+
This topic describes how to configure SCIM (System for Cross-domain Identity Management) v2.0 provisioning for the Replicated Vendor Portal.
4+
5+
:::note
6+
SCIM provisioning is Beta. Features and availability are subject to change.
7+
:::
8+
9+
## Overview
10+
11+
The Replicated Vendor Portal supports SCIM v2.0 for automated user provisioning and deprovisioning. With SCIM you can:
12+
13+
- Automatically provision users from your identity provider to Replicated
14+
- Keep user information synchronized between systems
15+
- Automatically deprovision users when they leave your organization
16+
- Manage the user lifecycle through your existing identity provider
17+
18+
## Prerequisites
19+
20+
Before you configure SCIM, ensure that:
21+
22+
1. SAML SSO is configured. For more information, see [Manage SAML Authentication](team-management-saml-auth).
23+
2. Your team has the SAML entitlement enabled.
24+
3. You have a Vendor Service Account token with permissions to manage team members.
25+
4. You have administrative access to your identity provider.
26+
27+
## SCIM Endpoints
28+
29+
Base URL: `https://api.replicated.com/vendor/scim/v2`
30+
31+
### Discovery Endpoints
32+
33+
- `GET /ServiceProviderConfig` — SCIM implementation capabilities
34+
- `GET /ResourceTypes` — Supported resource types (User, Group)
35+
- `GET /Schemas` — Detailed schema information
36+
37+
### User Management Endpoints
38+
39+
- `GET /Users` — List users with filtering and pagination
40+
- `POST /Users` — Create users
41+
- `GET /Users/{userId}` — Get a user (`userId` is the email address)
42+
- `PATCH /Users/{userId}` — Update user (deactivation only)
43+
- `PUT /Users/{userId}` — Replace user (deactivation only)
44+
- `DELETE /Users/{userId}` — Delete user
45+
46+
### Group Endpoints
47+
48+
- `GET /Groups` — Returns an empty list (read-only for compliance)
49+
50+
## Unique Identifier
51+
52+
- Primary identifier: `userName` (must be the user's email address)
53+
- Resource ID: The `id` in responses is the user's email address
54+
- Path parameter: `userId` for endpoints like `/Users/{userId}` is the user's email address
55+
- 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.
56+
57+
:::tip
58+
Email precedence:
59+
1. If any entry in `emails[]` has `primary: true`, that value is used even if `userName` is set.
60+
2. Otherwise, if `userName` is set, it is used.
61+
3. Otherwise, if `emails[]` has values, the first `emails[0].value` is used.
62+
:::
63+
64+
## Authentication
65+
66+
- Scheme: OAuth 2.0 Bearer Token
67+
- Header: `Authorization: Bearer <YOUR_VENDOR_API_TOKEN>`
68+
- Token type: Replicated Vendor Service Account token scoped to your team with permissions to manage team members
69+
- Prerequisite: SAML entitlement must be enabled for SCIM access
70+
71+
Example:
72+
73+
```bash
74+
curl -H "Authorization: Bearer YOUR_TOKEN" \
75+
https://api.replicated.com/vendor/scim/v2/Users
76+
```
77+
78+
## Identity Provider Configuration
79+
80+
### Okta Configuration
81+
82+
#### Step 1: Add Replicated Application
83+
1. In the Okta Admin Console, go to **Applications > Applications**.
84+
2. Create a custom SAML 2.0 application.
85+
3. Click **Add Integration**.
86+
87+
#### Step 2: Configure SAML
88+
1. Configure SAML settings as described in [Manage SAML Authentication](team-management-saml-auth).
89+
2. Ensure SAML is working before you proceed with SCIM.
90+
91+
#### Step 3: Enable SCIM Provisioning
92+
1. In your Okta account's Replicated application listing, go to the **Provisioning** tab.
93+
2. Click **Configure API Integration**.
94+
3. Check **Enable API integration**.
95+
4. Enter the following settings:
96+
- Base URL: `https://api.replicated.com/vendor/scim/v2`
97+
- Unique ID: email
98+
- Authentication Mode: HTTP
99+
- Supported Actions: Import Users, Push New Users, Push Profile Updates (deactivate only)
100+
- API Token: Your Replicated Vendor API token
101+
102+
#### Step 4: Configure Provisioning Settings
103+
1. Go to **Provisioning > To App**.
104+
2. Enable the following:
105+
- Create Users
106+
- Update User Attributes
107+
- Deactivate Users
108+
109+
#### Step 5: Attribute Mapping
110+
Configure the following attribute mappings:
111+
112+
| Okta Attribute | Replicated Attribute | Required | Notes |
113+
| --- | --- | --- | --- |
114+
| `user.email` | `userName` | Yes | Primary identifier |
115+
| `user.email` | `emails[0].value` | Recommended | Used if marked primary; otherwise only when `userName` is missing |
116+
| `user.firstName` | `name.givenName` | Recommended | Used for display purposes |
117+
| `user.lastName` | `name.familyName` | Recommended | Used for display purposes |
118+
| `user.displayName` | `displayName` | Optional | Auto-generated if not provided |
119+
120+
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.
121+
122+
#### Step 6: Assign Users
123+
1. Go to the **Assignments** tab.
124+
2. Assign users or groups who should have access to Replicated.
125+
3. Users are provisioned to your Replicated team automatically.
126+
127+
## Migrating from Existing User Management
128+
129+
### Pre-SCIM User Synchronization
130+
131+
If your team already has users in Replicated before you enable SCIM, synchronize existing users with your identity provider.
132+
133+
#### Option 1: Automatic User Matching (Recommended)
134+
1. Before you enable SCIM provisioning, ensure that all existing Replicated users have matching accounts in your identity provider.
135+
2. Configure SCIM as described above, but do not assign users yet.
136+
3. Test with a single user:
137+
- Assign one existing user to the Replicated app in your identity provider.
138+
- The system matches by email and returns the existing user.
139+
4. Gradually assign all existing users to complete the sync.
140+
141+
#### Option 2: Manual User Migration
142+
If email addresses do not match exactly or users exist in other teams:
143+
1. Update email addresses in Replicated or your identity provider so that they match.
144+
2. For users existing in other Replicated teams:
145+
- Domain authorized: The system automatically migrates the existing user's email and creates a new user.
146+
- Domain not authorized: Manual intervention is required. Contact support.
147+
3. Ensure that your SAML domain authorization includes all relevant email domains.
148+
149+
#### Verification Steps
150+
After migration, verify the setup:
151+
152+
```bash
153+
# List all users via SCIM to confirm sync
154+
curl -H "Authorization: Bearer YOUR_TOKEN" \
155+
https://api.replicated.com/vendor/scim/v2/Users
156+
157+
# Check a specific user by email
158+
curl -H "Authorization: Bearer YOUR_TOKEN" \
159+
https://api.replicated.com/vendor/scim/v2/Users/[email protected]
160+
```
161+
162+
### Migration Best Practices
163+
164+
1. Test environment first.
165+
2. Staged rollout starting with a small group of users.
166+
3. Communicate the migration timeline.
167+
4. Document the current user list and permissions before migration.
168+
5. Monitor for provisioning errors during the first few days.
169+
170+
### Generic SCIM Provider Configuration
171+
172+
For identity providers that support SCIM v2.0:
173+
174+
#### Basic Settings
175+
176+
- SCIM Base URL: `https://api.replicated.com/vendor/scim/v2`
177+
- Authentication Method: Bearer Token
178+
- Bearer Token: Your Replicated Vendor API token
179+
- SCIM Version: 2.0
180+
181+
#### Required Attributes
182+
183+
Minimum required attributes (only email is strictly required):
184+
185+
```json
186+
{
187+
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
188+
"userName": "[email protected]"
189+
}
190+
```
191+
192+
Recommended full attribute set:
193+
194+
```json
195+
{
196+
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
197+
"userName": "[email protected]",
198+
"emails": [
199+
{
200+
"value": "[email protected]",
201+
"type": "work",
202+
"primary": true
203+
}
204+
],
205+
"name": {
206+
"givenName": "John",
207+
"familyName": "Doe"
208+
},
209+
"active": true
210+
}
211+
```
212+
213+
## Supported Features
214+
215+
### Supported Operations
216+
217+
- User creation
218+
- User deactivation
219+
- User deletion
220+
- User filtering
221+
- Pagination
222+
- Email migration (automatic handling of email conflicts across teams)
223+
224+
### Unsupported Operations
225+
226+
- User reactivation
227+
- Password management
228+
- Group management (read-only, returns empty results)
229+
- Bulk operations
230+
- Updating user attributes other than deactivation
231+
232+
## Troubleshooting
233+
234+
### Common Issues
235+
236+
#### Authentication errors (401)
237+
238+
- Verify that your API token is valid and has appropriate permissions.
239+
- Ensure that the token is sent as `Authorization: Bearer YOUR_TOKEN`.
240+
- Check that your team has the SAML entitlement enabled.
241+
242+
#### User not found errors (404)
243+
244+
- Verify that the email address is correct. SCIM uses the email as `userId`.
245+
- Ensure that the user belongs to the correct team.
246+
- Check that SAML domain authorization is configured properly.
247+
248+
#### Email conflicts
249+
250+
The system automatically handles email conflicts when a user exists in any other team if your email domain is authorized for SAML.
251+
252+
If the email domain is authorized for SAML:
253+
254+
- The original user's email is migrated with a `+moved{date}` suffix.
255+
- A new user is created with the original email in the target team.
256+
- An email notification is sent to inform the user their account was moved.
257+
- Migration proceeds automatically.
258+
259+
If the email domain is not authorized for SAML:
260+
261+
- Migration is blocked for security.
262+
- The API returns the error: "Email is already associated with another team".
263+
- Manual intervention is required. Contact support or use a different email.
264+
265+
#### Provisioning failures
266+
267+
1. Check SCIM endpoint connectivity.
268+
2. Verify that all required attributes are being sent.
269+
3. Ensure that SAML is configured and working.
270+
4. Review identity provider logs for specific error messages.
271+
272+
### Testing SCIM Integration
273+
274+
#### Manual testing
275+
276+
Use curl to test SCIM endpoints:
277+
278+
```bash
279+
# Test service provider configuration
280+
curl -H "Authorization: Bearer YOUR_TOKEN" \
281+
https://api.replicated.com/vendor/scim/v2/ServiceProviderConfig
282+
283+
# List users
284+
curl -H "Authorization: Bearer YOUR_TOKEN" \
285+
https://api.replicated.com/vendor/scim/v2/Users
286+
287+
# Create user
288+
curl -X POST \
289+
-H "Authorization: Bearer YOUR_TOKEN" \
290+
-H "Content-Type: application/scim+json" \
291+
-d '{
292+
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
293+
"userName": "[email protected]",
294+
"emails": [{"value": "[email protected]", "primary": true}],
295+
"name": {"givenName": "Test", "familyName": "User"},
296+
"active": true
297+
}' \
298+
https://api.replicated.com/vendor/scim/v2/Users
299+
```
300+
301+
#### Identity provider testing
302+
303+
1. Test the connection using your identity provider's test feature.
304+
2. Provision a test user and verify creation.
305+
3. Deprovision the test user and verify deactivation.
306+
4. Review both identity provider and Replicated audit logs.
307+
308+

‎docs/vendor/team-management.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@ The [Team](https://vendor.replicated.com/team/members) page provides a list of a
1414

1515
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.
1616

17+
### SCIM
18+
19+
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).
20+
1721
## Invite Members
1822
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.
1923

@@ -95,7 +99,7 @@ As a Vendor Portal team admin, you can remove team members, except for the accou
9599

96100
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).
97101

98-
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).
102+
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.
99103

100104
To remove a member:
101105

‎sidebars.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,7 @@ const sidebars = {
136136
'vendor/team-management-two-factor-auth',
137137
'vendor/team-management-google-auth',
138138
'vendor/team-management-saml-auth',
139+
'vendor/team-management-scim-provisioning',
139140
],
140141
},
141142
'vendor/team-management-slack-config',

0 commit comments

Comments
 (0)