Skip to content

Commit c7974ab

Browse files
laliconfigcatz4kn4feinzoltan-david
authored
SCIM documentation (#536)
* scim * prg * scim * prg * prg * scim * iamges * renamings * rewrite, grammarly * progress * sidebar * Almost finish Okta SCIM docs * overviewfix * provisioning * Progress * progress * screenshots * remove auth0, google * limits * limits * next steps * tech limit * limits * index * beta * beta * onelogin docs * onelogin * Add SCIM API docs * todo * Apply suggestions from code review Co-authored-by: Zoltan David <54935463+zoltan-david@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Zoltan David <54935463+zoltan-david@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Zoltan David <54935463+zoltan-david@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Zoltan David <54935463+zoltan-david@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Zoltan David <54935463+zoltan-david@users.noreply.github.com> * links * fix * v1 * news --------- Co-authored-by: Peter Csajtai <peter.csajtai@outlook.com> Co-authored-by: Zoltan David <54935463+zoltan-david@users.noreply.github.com>
1 parent 7f9f54d commit c7974ab

File tree

82 files changed

+1455
-914
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

82 files changed

+1455
-914
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,4 @@ website/i18n/*
1919
.dccache
2020

2121
website/api/reference/*
22+
website/api/scim/*

‎website/api/sidebars.ts

Lines changed: 37 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,48 @@
11
import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
22

3-
const infoId = 'reference/configcat-public-management-api';
3+
const papiInfoId = 'reference/configcat-public-management-api';
4+
const scimInfoId = 'scim/configcat-user-provisioning-scim-api';
45

5-
const generated = require('./reference/sidebar.ts')
6-
.map(item => {
7-
return {
8-
...item,
9-
items: item.items.filter(sub => sub.id !== infoId),
10-
}
11-
});
6+
const papiSidebar = require('./reference/sidebar.ts').map((item) => {
7+
return {
8+
...item,
9+
items: item.items.filter((sub) => sub.id !== papiInfoId),
10+
};
11+
});
12+
13+
const scimSidebar = require('./scim/sidebar.ts').filter((item) => item.id !== scimInfoId);
1214

1315
const sidebars: SidebarsConfig = {
1416
api: [
1517
{
16-
label: 'Introduction',
17-
type: "doc",
18-
id: infoId,
18+
type: 'category',
19+
label: 'Public Management API',
20+
collapsible: true,
21+
collapsed: true,
22+
items: [
23+
{
24+
label: 'Introduction',
25+
type: 'doc',
26+
id: papiInfoId,
27+
},
28+
...papiSidebar,
29+
],
30+
},
31+
{
32+
type: 'category',
33+
label: 'User Provisioning (SCIM) API',
34+
collapsible: true,
35+
collapsed: true,
36+
items: [
37+
{
38+
label: 'Introduction',
39+
type: 'doc',
40+
id: scimInfoId,
41+
},
42+
...scimSidebar,
43+
],
1944
},
20-
...generated,
2145
],
2246
};
2347

24-
export default sidebars;
48+
export default sidebars;

‎website/docs/advanced/team-management/saml/identity-providers/azure-ad.mdx

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -135,4 +135,5 @@ To let users authenticate via SAML, you need to assign individual users or group
135135

136136
## 6. Next Steps
137137

138-
- Configure the [auto-assignment of users](../../auto-assign-users.mdx).
138+
- Configure [User provisioning (SCIM)](../../scim/overview.mdx)
139+
- or configure the [auto-assignment of users](../../auto-assign-users.mdx) if you don't want to provision your users with your Identity Provider.

‎website/docs/advanced/team-management/saml/identity-providers/okta.mdx

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -140,4 +140,5 @@ To let users authenticate via SAML, you need to assign individual users or group
140140

141141
## 6. Next Steps
142142

143-
- Configure the [auto-assignment of users](../../auto-assign-users.mdx).
143+
- Configure [User provisioning (SCIM)](../../scim/overview.mdx)
144+
- or configure the [auto-assignment of users](../../auto-assign-users.mdx) if you don't want to provision your users with your Identity Provider.

‎website/docs/advanced/team-management/saml/identity-providers/onelogin.mdx

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -164,4 +164,5 @@ To let users authenticate via SAML, you need to assign the newly created applica
164164

165165
## 6. Next Steps
166166

167-
- Configure the [auto-assignment of users](../../auto-assign-users.mdx).
167+
- Configure [User provisioning (SCIM)](../../scim/overview.mdx)
168+
- or configure the [auto-assignment of users](../../auto-assign-users.mdx) if you don't want to provision your users with your Identity Provider.

‎website/docs/advanced/team-management/saml/overview.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ This section describes how you can enable SAML Single Sign-On (SSO) for your org
88

99
SAML SSO allows your team members to sign up and log in to ConfigCat via their company accounts using your own Identity Provider (IdP).
1010

11-
Go to the [Authentication Preferences](https://app.configcat.com/organization/authentication/) page to set up SAML SSO. You need to be an
11+
Go to the [Authentication & Provisioning](https://app.configcat.com/organization/authentication/) page to set up SAML SSO. You need to be an
1212
organization admin to do this.
1313

1414
## Prerequisites

‎website/docs/advanced/team-management/scim/identity-providers/entra-id.mdx

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
id: entra-id
3+
title: (Beta) User Provisioning (SCIM) with Entra ID (Azure AD)
4+
description: This is a step-by-step guide on how to set up and configure Entra ID (Azure AD) as a User provisioning (SCIM) provider for your organization.
5+
---
6+
7+
import Tabs from '@theme/Tabs';
8+
import TabItem from '@theme/TabItem';
9+
10+
:::info
11+
**Beta Feature**: SCIM provisioning is in public beta. It has been thoroughly tested with various Identity Providers.
12+
We're now collecting feedback from real-world usage to fine-tune the experience. Share your feedback [here](https://configcat.com/support).
13+
:::
14+
15+
## Introduction
16+
17+
Each Identity Provider requires specific information to configure a SCIM integration. The following guide will walk you through how you can connect ConfigCat with Entra ID via SCIM.
18+
19+
## 1. Create an Entra ID Enterprise Application
20+
21+
:::info
22+
If you already configured your organization to use Entra ID as a SAML provider, you can use the existing Entra ID Enterprise application and skip to the [next step](#2-configure-provisioning-scim-for-the-azure-enterprise-application).
23+
:::
24+
25+
- Log in to the <a href="https://portal.azure.com/" target="_blank">Azure Portal</a>, go to the `Entra ID` resource, select `Enterprise applications`, and click on `New application`.
26+
27+
<img className="bordered-img" src="/docs/assets/scim/entra_id/new_application.png" alt="Entra ID enterprise applications" decoding="async" loading="lazy"/>
28+
29+
- Click on `Create your own application`.
30+
31+
<img className="bordered-img" src="/docs/assets/scim/entra_id/create_application.png" alt="Entra ID create own application" decoding="async" loading="lazy"/>
32+
33+
- Enter a descriptive `App name`, select the `Integrate any other application you don't find in the gallery (Non-gallery)` option, then click `Create`.
34+
35+
<img className="bordered-img" src="/docs/assets/scim/entra_id/app_name.png" alt="Entra ID app name" decoding="async" loading="lazy"/>
36+
37+
The next step will guide you on how to setup Entra ID to synchronize your Identity Provider users and Identity Provider groups to ConfigCat.
38+
39+
## 2. Configure Provisioning (SCIM) for the Azure Enterprise Application
40+
41+
- On the `Manage` section of the application, select `Provisioning`, then click on `New Configuration`.
42+
43+
<img className="bordered-img" src="/docs/assets/scim/entra_id/new_config.png" width="1293" alt="Entra ID new SCIM configuration" decoding="async" loading="lazy"/>
44+
45+
- Gather the `SCIM URL` and the `Token` from the <a href="https://app.configcat.com/organization/authentication/" target="_blank" rel="noopener noreferrer">Authentication & Provisioning</a> page in ConfigCat.
46+
47+
<img className="bordered-img" src="/docs/assets/scim/dashboard/token_generate_url.png" alt="SCIM URL and token" decoding="async" loading="lazy"/>
48+
49+
<img className="bordered-img" src="/docs/assets/scim/dashboard/token.png" alt="SCIM token" decoding="async" loading="lazy"/>
50+
51+
- Add the `SCIM URL` as the `Tenant URL` and the `Token` as the `Secret token` on the New provisioning configuration page in Azure. Click on the `Create` button.
52+
53+
<img className="bordered-img" src="/docs/assets/scim/entra_id/scim_meta.png" alt="Entra ID SCIM URL and token" decoding="async" loading="lazy"/>
54+
55+
- Select the `Provisioning` menu and in the Mappings, configure the mapping for Users and Groups.
56+
57+
<img className="bordered-img" src="/docs/assets/scim/entra_id/mappings.png" alt="Entra ID SCIM mappings" decoding="async" loading="lazy"/>
58+
59+
- Mapping for Users:
60+
Configure only the following mappings and remove all other mappings if there are any.
61+
62+
| Provisioning Attribute | Microsoft Entra ID Attribute |
63+
| ----------------------- | ----------------------------------------------------------- |
64+
| externalId | objectId |
65+
| userName | userPrincipalName |
66+
| displayName | displayName |
67+
| active | Switch([IsSoftDeleted], , "False", "True", "True", "False") |
68+
69+
<img className="bordered-img" src="/docs/assets/scim/entra_id/user_mappings.png" alt="Entra ID SCIM User mappings" decoding="async" loading="lazy"/>
70+
71+
- Mapping for Groups:
72+
Configure only the following mappings and remove all other mappings if there are any.
73+
74+
| Provisioning Attribute | Microsoft Entra ID Attribute |
75+
| ----------------------- | ---------------------------- |
76+
| externalId | objectId |
77+
| displayName | displayName |
78+
| members | members |
79+
80+
<img className="bordered-img" src="/docs/assets/scim/entra_id/group_mappings.png" alt="Entra ID SCIM Group mappings" decoding="async" loading="lazy"/>
81+
82+
## 3. Assign Users/Groups to the Enterprise Application
83+
84+
To start user provisioning with Entra ID, you need to assign groups to the Enterprise application.
85+
86+
- Select `Users and groups` on the `Manage` section of the menu, and click `Add user/group`. Then, you can select the groups you want to assign.
87+
88+
<img className="bordered-img" src="/docs/assets/scim/entra_id/add_user.png" alt="Entra ID users and groups" decoding="async" loading="lazy"/>
89+
90+
:::caution
91+
In ConfigCat, you can assign permissions only to groups that are synchronized from your Identity Provider,
92+
therefore it's important to select groups for synchronization rather than individual users.
93+
:::
94+
95+
## 4. Start provisioning
96+
97+
- Go to the `Overview` page of the provisioning configuration and click on `Start provisioning`.
98+
99+
<img className="bordered-img" src="/docs/assets/scim/entra_id/start_provisioning.png" alt="Entra ID start provisioning" decoding="async" loading="lazy" />
100+
101+
- Wait until the first provisioning is finished, and you should see each synced group and user on ConfigCat's <a href="https://app.configcat.com/organization/authentication/" target="_blank" rel="noopener noreferrer">Authentication & Provisioning</a> page.
102+
103+
## 5. Next Steps
104+
105+
- Continue with [assigning ConfigCat permissions to the synced groups](../overview.mdx#groups).

‎website/docs/advanced/team-management/scim/identity-providers/okta.mdx

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
id: okta
3+
title: (Beta) User Provisioning (SCIM) with Okta
4+
description: This is a step-by-step guide on how to set up and configure Okta as a User provisioning (SCIM) provider for your organization.
5+
---
6+
7+
import Tabs from '@theme/Tabs';
8+
import TabItem from '@theme/TabItem';
9+
10+
:::info
11+
**Beta Feature**: SCIM provisioning is in public beta. It has been thoroughly tested with various Identity Providers.
12+
We're now collecting feedback from real-world usage to fine-tune the experience. Share your feedback [here](https://configcat.com/support).
13+
:::
14+
15+
## Introduction
16+
17+
Each Identity Provider requires specific information to configure a SCIM integration. The following guide will walk you through how you can connect ConfigCat with Okta via SCIM.
18+
19+
## 1. Create an Application in Okta
20+
21+
- Log in to <a href="https://login.okta.com/" target="_blank">Okta</a>, go to the admin Dashboard, select `Applications`, and click on `Create App Integration`.
22+
23+
<img className="bordered-img" src="/docs/assets/scim/okta/create_app.png" alt="Okta applications" decoding="async" loading="lazy" />
24+
25+
- Select `SAML 2.0` as the Sign-in method.
26+
27+
<img className="bordered-img" src="/docs/assets/scim/okta/app_type.png" alt="Okta select SAML" decoding="async" loading="lazy"/>
28+
29+
- Enter a descriptive `App name`, then click `Next`.
30+
31+
<img className="bordered-img" src="/docs/assets/scim/okta/app_name.png" alt="Okta app name" decoding="async" loading="lazy"/>
32+
33+
The next step will guide you on how to collect the information required for the appearing `Configure SAML` section.
34+
35+
## 2. Configure SAML authentication for the Okta Application
36+
37+
- Follow our [SAML configuration guide for Okta](../../../saml/identity-providers/okta/#2-configure-saml-for-the-okta-application).
38+
39+
## 3. Configure Provisioning (SCIM) for the Okta Application
40+
41+
- Click on `Edit` at the `App Settings`.
42+
43+
<img className="bordered-img" src="/docs/assets/scim/okta/edit_settings.png" alt="Okta edit app settings" decoding="async" loading="lazy"/>
44+
45+
- Check the `Enable SCIM provisioning` checkbox, and hit `Save`.
46+
47+
<img className="bordered-img" src="/docs/assets/scim/okta/enable_provisioning.png" alt="Okta enable provisioning" decoding="async" loading="lazy"/>
48+
49+
- Gather the `SCIM URL` and the `Token` from the <a href="https://app.configcat.com/organization/authentication/" target="_blank" rel="noopener noreferrer">Authentication & Provisioning</a> page in ConfigCat.
50+
51+
<img className="bordered-img" src="/docs/assets/scim/dashboard/token_generate_url.png" alt="SCIM URL and token" decoding="async" loading="lazy"/>
52+
53+
<img className="bordered-img" src="/docs/assets/scim/dashboard/token.png" alt="SCIM token" decoding="async" loading="lazy"/>
54+
55+
- Select the `Provisioning` tab and click on the `Edit` button.
56+
57+
<img className="bordered-img" src="/docs/assets/scim/okta/edit_provisioning.png" alt="Okta edit provisioning" decoding="async" loading="lazy"/>
58+
59+
- On the `SCIM Connection` section configure the following:
60+
- Add the `SCIM URL` from the ConfigCat Dashboard as the `SCIM connector base URL`.
61+
- Set the `Unique identifier field for users` field to `email`.
62+
- Check the following `Supported provisioning actions`:
63+
- `Push New Users`
64+
- `Push Profile Updates`
65+
- `Push Groups`
66+
- Select the `HTTP Header` as the `Authentication Mode`.
67+
- Set the `Token` from the ConfigCat Dashboard as the `HTTP Header Authorization`.
68+
- Click on `Save`.<br/><br/>
69+
70+
<img className="bordered-img" src="/docs/assets/scim/okta/scim_connection.png" alt="Okta SCIM connection" decoding="async" loading="lazy"/>
71+
72+
- Select the `To App` menu item and click on `Edit`.
73+
74+
<img className="bordered-img" src="/docs/assets/scim/okta/to_app_edit.png" alt="Okta To App edit" decoding="async" loading="lazy"/>
75+
76+
- Check the `Create Users`, `Update User Attributes`, and `Deactivate Users` checkboxes, and hit `Save`.
77+
78+
<img className="bordered-img" src="/docs/assets/scim/okta/to_app_save.png" alt="Okta To App save" decoding="async" loading="lazy"/>
79+
80+
## 4. Assign Users/Groups to Okta Application
81+
82+
To select users for synchronization into ConfigCat, you have to assign their Okta group to the Application.
83+
84+
- Select the `Assignments` tab, click on the `Assign` dropdown, and select `Assign to Groups`.
85+
86+
<img className="bordered-img" src="/docs/assets/scim/okta/assign_groups.png" alt="Okta assign groups" decoding="async" loading="lazy"/>
87+
88+
- Click the `Assign` button on those groups whose members you want to sync to ConfigCat.
89+
90+
<img className="bordered-img" src="/docs/assets/scim/okta/assign_group.png" alt="Okta assign group" decoding="async" loading="lazy"/>
91+
92+
The above action starts the synchronization of the selected users but not their groups.
93+
94+
:::caution
95+
Okta does not support using the same Okta group for assignments and for syncing group-member relations.
96+
You need to create a separate group that is used exclusively for syncing group-member relations.
97+
These groups are called `Push Groups` in Okta.
98+
99+
To learn more, see <a href="https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-about-group-push.htm" target="_blank" rel="noopener noreferrer">Okta's documentation about Push Groups</a>.
100+
:::
101+
102+
To enable group syncing, create separate groups for the users that you want to sync and add these new groups to the application as `Push Groups`.
103+
104+
- Go to the `Push Groups` tab, click on the `Push Groups` dropdown, and select `Find groups by name`.
105+
106+
<img className="bordered-img" src="/docs/assets/scim/okta/push_groups.png" alt="Okta push groups" decoding="async" loading="lazy"/>
107+
108+
- Select the group that you want to push, and click on the `Save` button.
109+
110+
<img className="bordered-img" src="/docs/assets/scim/okta/add_push_group.png" alt="Okta add push group" decoding="async" loading="lazy"/>
111+
112+
- Make sure that the created push group's status is active.
113+
114+
<img className="bordered-img" src="/docs/assets/scim/okta/push_group_active.png" alt="Okta push group active" decoding="async" loading="lazy"/>
115+
116+
- You should see each synced group and user on ConfigCat's <a href="https://app.configcat.com/organization/authentication/" target="_blank" rel="noopener noreferrer">Authentication & Provisioning</a> page.
117+
118+
## 5. Next Steps
119+
120+
- Continue with [assigning ConfigCat permissions to the synced groups](../overview.mdx#groups).

0 commit comments

Comments
 (0)