Skip to content

Commit 0ec7022

Browse files
hperlvinckr
hperl
and
vinckr
authored
feat: guides for SCIM with Okta and MS Entra (#2130)
* formatting * feat: guides for setting up SCIM with MS Entra and Okta * chore: apply suggestions from code review --------- Co-authored-by: Vincent <[email protected]>
1 parent 3e5ce1c commit 0ec7022

15 files changed

+163
-34
lines changed

‎docs/kratos/manage-identities/50_scim.mdx

Lines changed: 40 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
---
22
id: scim
33
title: SCIM
4-
sidebar_label: SCIM
54
---
65

76
# System for Cross-domain Identity Management
@@ -83,7 +82,15 @@ The script should return a JSON object as defined in the [Jsonnet reference](../
8382
Once you have configured a SCIM client, you can use it to provision identities. The Ory Network SCIM server provides a set of
8483
endpoints that allow the creation and management of user identities and groups.
8584

86-
The following endpoints are available:
85+
Please refer to these guides for setting up SCIM with specific identity providers:
86+
87+
```mdx-code-block
88+
import DocCardList from '@theme/DocCardList';
89+
90+
<DocCardList />
91+
```
92+
93+
For generic SCIM clients, the following endpoints are available:
8794

8895
- **User endpoints**
8996
- `GET /Users`: Retrieve a list of users.
@@ -110,43 +117,43 @@ available schemas.
110117
Ory Network fully supports the standard SCIM user resource schema as defined in the
111118
[SCIM RFC](https://datatracker.ietf.org/doc/html/rfc7643#section-4.1). In detail, the following attributes are supported:
112119

113-
| Name | Type | Remarks |
114-
| ----------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
115-
| id | UUID | Read-only, this is the identity ID. |
116-
| externalId | string | Optional, an ID set by the SCIM client. |
117-
| userName | string | Required, unique identifier for the user. Typically used as the login identifier. |
118-
| name | object | Contains sub-attributes `formatted`, `familyName`, `givenName`, `middleName`, `honorificPrefix`, and `honorificSuffix`. |
119-
| displayName | string | |
120-
| nickName | string | |
121-
| profileUrl | string | |
122-
| title | string | |
123-
| userType | string | |
124-
| preferredLanguage | string | |
125-
| locale | string | |
126-
| timeZone | string | If set, must be a valid time zone. |
127-
| active | bool | If unset or false, the user will not be able to log in. |
128-
| password | string | If set, the user will be able to log in with this password. The password is never returned in any SCIM response. |
129-
| emails | array | List of email addresses. Each email can have a `value` (string), `display` (string), `primary` (boolean), and `type` (string). At most one `primary=true` email can be set. |
130-
| phoneNumbers | array | List of phone numbers. Each number can have a `value` (string), `display` (string), `primary` (boolean), and `type` (string). At most one `primary=true` number can be set. |
131-
| ims | array | List of instant messaging accounts. Each account can have a `value` (string), `display` (string), `primary` (boolean), and `type` (string). At most one `primary=true` account can be set. |
132-
| photos | array | List of photos. Each photo can have a `value` (string), `display` (string), `primary` (boolean), and `type` (string). At most one `primary=true` photo can be set. |
133-
| addresses | array | List of addresses. Each address can have a `formatted` (string), `streetAddress` (string), `locality` (string), `region` (string), `postalCode` (string), `country` (string), and `type` (string). |
134-
| groups | array | Read-only, a list of groups the user is a member of. Each group can have a `value` (string), `display` (string), and `type` (string). To modify, set the `members` property on the `groups` resource. |
135-
| entitlements | array | List of entitlements. Each entitlement can have a `value` (string), `display` (string), `primary` (boolean), and `type` (string). At most one `primary=true` entitlement can be set. |
136-
| roles | array | List of roles. Each role can have a `value` (string), `display` (string), `primary` (boolean), and `type` (string). At most one `primary=true` role can be set. |
137-
| x509Certificates | array | List of X.509 certificates. Each certificate can have a `value` (string), `display` (string), `primary` (boolean), and `type` (string). At most one `primary=true` certificate can be set. |
120+
| Name | Type | Remarks |
121+
| ------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
122+
| `id` | UUID | Read-only, this is the identity ID. |
123+
| `externalId` | string | Optional, an ID set by the SCIM client. |
124+
| `userName` | string | Required, unique identifier for the user. Typically used as the login identifier. |
125+
| `name` | object | Contains sub-attributes `formatted`, `familyName`, `givenName`, `middleName`, `honorificPrefix`, and `honorificSuffix`. |
126+
| `displayName` | string | |
127+
| `nickName` | string | |
128+
| `profileUrl` | string | |
129+
| `title` | string | |
130+
| `userType` | string | |
131+
| `preferredLanguage` | string | |
132+
| `locale` | string | |
133+
| `timeZone` | string | If set, must be a valid time zone. |
134+
| `active` | bool | If unset or false, the user will not be able to log in. |
135+
| `password` | string | If set, the user will be able to log in with this password. The password is never returned in any SCIM response. |
136+
| `emails` | array | List of email addresses. Each email can have a `value` (string), `display` (string), `primary` (boolean), and `type` (string). At most one `primary=true` email can be set. |
137+
| `phoneNumbers` | array | List of phone numbers. Each number can have a `value` (string), `display` (string), `primary` (boolean), and `type` (string). At most one `primary=true` number can be set. |
138+
| `ims` | array | List of instant messaging accounts. Each account can have a `value` (string), `display` (string), `primary` (boolean), and `type` (string). At most one `primary=true` account can be set. |
139+
| `photos` | array | List of photos. Each photo can have a `value` (string), `display` (string), `primary` (boolean), and `type` (string). At most one `primary=true` photo can be set. |
140+
| `addresses` | array | List of addresses. Each address can have a `formatted` (string), `streetAddress` (string), `locality` (string), `region` (string), `postalCode` (string), `country` (string), and `type` (string). |
141+
| `groups` | array | Read-only, a list of groups the user is a member of. Each group can have a `value` (string), `display` (string), and `type` (string). To modify, set the `members` property on the `groups` resource. |
142+
| `entitlements` | array | List of entitlements. Each entitlement can have a `value` (string), `display` (string), `primary` (boolean), and `type` (string). At most one `primary=true` entitlement can be set. |
143+
| `roles` | array | List of roles. Each role can have a `value` (string), `display` (string), `primary` (boolean), and `type` (string). At most one `primary=true` role can be set. |
144+
| `x509Certificates` | array | List of X.509 certificates. Each certificate can have a `value` (string), `display` (string), `primary` (boolean), and `type` (string). At most one `primary=true` certificate can be set. |
138145

139146
### SCIM group resource schema
140147

141148
Ory Network fully supports the standard SCIM group resource schema as defined in the
142149
[SCIM RFC](https://datatracker.ietf.org/doc/html/rfc7643#section-4.2). In detail, the following attributes are supported:
143150

144-
| Name | Type | Remarks |
145-
| ----------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
146-
| id | UUID | Read-only, this is the group ID. |
147-
| externalId | string | Optional, an ID set by the SCIM client. If set, this ID must be unique in the context of the organization. |
148-
| displayName | string | Required, the name of the group. |
149-
| members | array | List of members. Each member can have a `value` (string), `display` (string), and `type` (string). `value` is either an identity ID (when `type` equals `"User"`) or a group ID (when `type` equals `"Group"`). |
151+
| Name | Type | Remarks |
152+
| ------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
153+
| `id` | UUID | Read-only, this is the group ID. |
154+
| `externalId` | string | Optional, an ID set by the SCIM client. If set, this ID must be unique in the context of the organization. |
155+
| `displayName` | string | Required, the name of the group. |
156+
| `members` | array | List of members. Each member can have a `value` (string), `display` (string), and `type` (string). `value` is either an identity ID (when `type` equals `"User"`) or a group ID (when `type` equals `"Group"`). |
150157

151158
### Group memberships
152159

‎docs/kratos/manage-identities/scim/entra-screenshots/app-provisioning.png

1.23 MB
Loading

‎docs/kratos/manage-identities/scim/entra-screenshots/app.png

1.09 MB
Loading

‎docs/kratos/manage-identities/scim/entra-screenshots/config.png

784 KB
Loading

‎docs/kratos/manage-identities/scim/entra-screenshots/create-app.png

1.04 MB
Loading

‎docs/kratos/manage-identities/scim/entra-screenshots/provision-user.png

904 KB
Loading

‎docs/kratos/manage-identities/scim/ms-entra.mdx

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
id: ms-entra
3+
title: Provision from MS Entra
4+
---
5+
6+
# Set up SCIM provisioning from Microsoft Entra
7+
8+
This page guides you through setting up SCIM provisioning from Microsoft Entra to Ory Network.
9+
10+
## Create a SCIM App in MS Entra
11+
12+
From the Azure admin dashboard, navigate to **Microsoft Entra ID** > **Enterprise applications** and create a new application by
13+
clicking on **Create your own application**.
14+
15+
![Create enterprise application](entra-screenshots/create-app.png)
16+
17+
In the app screen, select **Provisioning**.
18+
19+
![Create enterprise application](entra-screenshots/app.png)
20+
21+
Next, select **Create configuration**.
22+
23+
![Create enterprise application](entra-screenshots/app-provisioning.png)
24+
25+
## Set up provisioning
26+
27+
In the provision configuration screen, enter the SCIM server URL from your Ory Network SCIM server, and for the **API token**,
28+
excluding the `Bearer` prefix, enter the SCIM token you created in the Ory Network.
29+
30+
For example, if in Ory Network you've set the token to `Bearer secret`, enter `secret` in the **API token** field.
31+
32+
Click on **Test Connection** to verify the connection. If successful, you should see a success message.
33+
34+
![Create enterprise application](entra-screenshots/config.png)
35+
36+
## Configure assignments
37+
38+
Next, provision users through SCIM by clicking on **Provision on demand**, and enter a user name into the search box. Click on the
39+
user to start the provisioning process. If successful, you should see a success message.
40+
41+
![Create enterprise application](entra-screenshots/provision-user.png)
42+
43+
## Verify provisioning
44+
45+
After completing the assignment, navigate to the Ory Network SCIM server and verify that the users have been provisioned.
46+
47+
![Okta assignment](okta-screenshots/ory-network-assignment.png)
48+
49+
## Troubleshooting
50+
51+
When the provisioning fails, the error will be logged. In Ory Network, navigate to **Activity** > **Logs & Events** and look for
52+
`SCIM provisioning error` events.

‎docs/kratos/manage-identities/scim/okta-screenshots/app-catalog.png

498 KB
Loading

‎docs/kratos/manage-identities/scim/okta-screenshots/app-provisioning.png

883 KB
Loading

‎docs/kratos/manage-identities/scim/okta-screenshots/assignment.png

968 KB
Loading

‎docs/kratos/manage-identities/scim/okta-screenshots/ory-network-assignment.png

751 KB
Loading

‎docs/kratos/manage-identities/scim/okta-screenshots/provisioning-error.png

1020 KB
Loading

‎docs/kratos/manage-identities/scim/okta-screenshots/user-assignment.png

893 KB
Loading

‎docs/kratos/manage-identities/scim/okta.mdx

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
id: okta
3+
title: Provision from Okta
4+
---
5+
6+
# Set up SCIM provisioning from Okta
7+
8+
This page guides you through setting up SCIM provisioning from Okta to Ory Network. Also refer to the
9+
[Okta SCIM documentation](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_scim.htm) for more
10+
information.
11+
12+
## Create a SCIM App in Okta
13+
14+
From the Okta admin dashboard, navigate to **Applications** > **Add Application** and search for **SCIM 2.0 Test App (Header
15+
Auth)**.
16+
17+
![Okta app catalog](okta-screenshots/app-catalog.png)
18+
19+
Click on the tile to open the app details page, then click **Add Integration** to add the app to your Okta organization.
20+
21+
Choose a name for the app and click **Next**.
22+
23+
Complete the wizard by clicking on **Done**.
24+
25+
## Set up provisioning
26+
27+
Next, navigate to the **Provisioning** tab and click on **Enable API Integration**. For the **Base URL**, enter the SCIM server
28+
URL from your Ory Network SCIM server, and for th **API token**, enter the SCIM token you created in the Ory Network.
29+
30+
Click **Test API Credentials** to verify the connection. If successful, you should see a success message.
31+
32+
![Okta app provisioning](okta-screenshots/app-provisioning.png)
33+
34+
Click on **Edit** in the **Provisioning** tab and check the boxes for **Create Users**, **Update User Attributes**, and
35+
**Deactivate Users**. Click **Save** to save the changes.
36+
37+
## Configure assignments
38+
39+
To assign users to the app, navigate to the **Assignments** tab and click on **Assign**. You can assign users or groups to the
40+
app. Click **Assign to People** to assign individual users or **Assign to Groups** to assign groups.
41+
42+
![Okta assignment](okta-screenshots/assignment.png)
43+
44+
## Verify provisioning
45+
46+
After completing the assignment, navigate to the Ory Network SCIM server and verify that the users have been provisioned.
47+
48+
![Okta assignment](okta-screenshots/user-assignment.png)
49+
50+
## Troubleshooting
51+
52+
When the provisioning fails, both in Ory Network and Okta you will see an error message. In Ory Network, navigate to
53+
**Activity** > **Logs & Events** and look for `SCIM provisioning error` events.
54+
55+
In Okta, navigate to the **Assignments** tab and click on the red exclamation mark next to the user. This will show you the error
56+
response from Ory Network.
57+
58+
![Okta assignment](okta-screenshots/provisioning-error.png)

0 commit comments

Comments
 (0)