Skip to content

feat: guides for SCIM with Okta and MS Entra #2130

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

feat: guides for SCIM with Okta and MS Entra #2130

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0221583
formatting
hperl Apr 24, 2025
8e655bb
feat: guides for setting up SCIM with MS Entra and Okta
hperl Apr 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 40 additions & 33 deletions docs/kratos/manage-identities/50_scim.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
id: scim
title: SCIM
sidebar_label: SCIM
---

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

The following endpoints are available:
Please refer to these guides for setting up SCIM with specific identity providers:

```mdx-code-block
import DocCardList from '@theme/DocCardList';

<DocCardList />
```

For generic SCIM clients, the following endpoints are available:

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

| Name | Type | Remarks |
| ----------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | UUID | Read-only, this is the identity ID. |
| externalId | string | Optional, an ID set by the SCIM client. |
| userName | string | Required, unique identifier for the user. Typically used as the login identifier. |
| name | object | Contains sub-attributes `formatted`, `familyName`, `givenName`, `middleName`, `honorificPrefix`, and `honorificSuffix`. |
| displayName | string | |
| nickName | string | |
| profileUrl | string | |
| title | string | |
| userType | string | |
| preferredLanguage | string | |
| locale | string | |
| timeZone | string | If set, must be a valid time zone. |
| active | bool | If unset or false, the user will not be able to log in. |
| password | string | If set, the user will be able to log in with this password. The password is never returned in any SCIM response. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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). |
| 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. |
| 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. |
| 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. |
| 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. |
| Name | Type | Remarks |
| ------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | UUID | Read-only, this is the identity ID. |
| `externalId` | string | Optional, an ID set by the SCIM client. |
| `userName` | string | Required, unique identifier for the user. Typically used as the login identifier. |
| `name` | object | Contains sub-attributes `formatted`, `familyName`, `givenName`, `middleName`, `honorificPrefix`, and `honorificSuffix`. |
| `displayName` | string | |
| `nickName` | string | |
| `profileUrl` | string | |
| `title` | string | |
| `userType` | string | |
| `preferredLanguage` | string | |
| `locale` | string | |
| `timeZone` | string | If set, must be a valid time zone. |
| `active` | bool | If unset or false, the user will not be able to log in. |
| `password` | string | If set, the user will be able to log in with this password. The password is never returned in any SCIM response. |
| `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. |
| `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. |
| `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. |
| `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. |
| `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). |
| `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. |
| `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. |
| `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. |
| `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. |

### SCIM group resource schema

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

| Name | Type | Remarks |
| ----------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | UUID | Read-only, this is the group ID. |
| externalId | string | Optional, an ID set by the SCIM client. If set, this ID must be unique in the context of the organization. |
| displayName | string | Required, the name of the group. |
| 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"`). |
| Name | Type | Remarks |
| ------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | UUID | Read-only, this is the group ID. |
| `externalId` | string | Optional, an ID set by the SCIM client. If set, this ID must be unique in the context of the organization. |
| `displayName` | string | Required, the name of the group. |
| `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"`). |

### Group memberships

Expand Down
Binary file added docs/kratos/manage-identities/scim/entra-screenshots/app-provisioning.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/kratos/manage-identities/scim/entra-screenshots/app.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/kratos/manage-identities/scim/entra-screenshots/config.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/kratos/manage-identities/scim/entra-screenshots/create-app.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/kratos/manage-identities/scim/entra-screenshots/provision-user.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
52 changes: 52 additions & 0 deletions docs/kratos/manage-identities/scim/ms-entra.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
---
id: ms-entra
title: Provision from MS Entra
---

# Set up SCIM provisioning from Microsoft Entra

This page guides you through setting up SCIM provisioning from Microsoft Entra to Ory Network.

## Create a SCIM App in MS Entra

From the Azure admin dashboard, navigate to **Microsoft Entra ID** > **Enterprise applications** and create a new application by
clicking on **Create your own application**.

![Create enterprise application](entra-screenshots/create-app.png)

In the app screen, select **Provisioning**.

![Create enterprise application](entra-screenshots/app.png)

Next, select **Create configuration**.

![Create enterprise application](entra-screenshots/app-provisioning.png)

## Set up provisioning

In the provision configuration screen, enter the SCIM server URL from your Ory Network SCIM server, and for the **API token**,
excluding the `Bearer` prefix, enter the SCIM token you created in the Ory Network.

For example, if in Ory Network you've set the token to `Bearer secret`, enter `secret` in the **API token** field.

Click on **Test Connection** to verify the connection. If successful, you should see a success message.

![Create enterprise application](entra-screenshots/config.png)

## Configure assignments

Next, provision users through SCIM by clicking on **Provision on demand**, and enter a user name into the search box. Click on the
user to start the provisioning process. If successful, you should see a success message.

![Create enterprise application](entra-screenshots/provision-user.png)

## Verify provisioning

After completing the assignment, navigate to the Ory Network SCIM server and verify that the users have been provisioned:

![Okta assignment](okta-screenshots/user-assignment.png)

## Troubleshooting

When the provisioning fails, the error will be logged. In Ory Network, navigate to **Activity** > **Logs & Events** and look for
`SCIM provisioning error` events.
Binary file added docs/kratos/manage-identities/scim/okta-screenshots/app-catalog.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/kratos/manage-identities/scim/okta-screenshots/app-provisioning.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/kratos/manage-identities/scim/okta-screenshots/assignment.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/kratos/manage-identities/scim/okta-screenshots/ory-network-assignment.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/kratos/manage-identities/scim/okta-screenshots/provisioning-error.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/kratos/manage-identities/scim/okta-screenshots/user-assignment.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
58 changes: 58 additions & 0 deletions docs/kratos/manage-identities/scim/okta.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
---
id: okta
title: Provision from Okta
---

# Set up SCIM provisioning from Okta

This page guides you through setting up SCIM provisioning from Okta to Ory Network. Also refer to the
[Okta SCIM documentation](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_scim.htm) for more
information.

## Create a SCIM App in Okta

From the Okta admin dashboard, navigate to **Applications** > **Add Application** and search for **SCIM 2.0 Test App (Header
Auth)**.

![Okta app catalog](okta-screenshots/app-catalog.png)

Click on the tile to open the app details page, then click **Add Integration** to add the app to your Okta organization.

Choose a name for the app and click **Next**.

Complete the wizard by clicking on **Done**.

## Set up provisioning

Next, navigate to the **Provisioning** tab and click on **Enable API Integration**. For the **Base URL**, enter the SCIM server
URL from your Ory Network SCIM server, and for th **API token**, enter the SCIM token you created in the Ory Network.

Click **Test API Credentials** to verify the connection. If successful, you should see a success message.

![Okta app provisioning](okta-screenshots/app-provisioning.png)

Click on **Edit** in the **Provisioning** tab and check the boxes for **Create Users**, **Update User Attributes**, and
**Deactivate Users**. Click **Save** to save the changes.

## Configure assignments

To assign users to the app, navigate to the **Assignments** tab and click on **Assign**. You can assign users or groups to the
app. Click **Assign to People** to assign individual users or **Assign to Groups** to assign groups.

![Okta assignment](okta-screenshots/assignment.png)

## Verify provisioning

After completing the assignment, navigate to the Ory Network SCIM server and verify that the users have been provisioned:

![Okta assignment](okta-screenshots/user-assignment.png)

## Troubleshooting

When the provisioning fails, both in Ory Network and Okta you will see an error message. In Ory Network, navigate to
**Activity** > **Logs & Events** and look for `SCIM provisioning error` events.

In Okta, navigate to the **Assignments** tab and click on the red exclamation mark next to the user. This will show you the error
response from Ory Network.

![Okta assignment](okta-screenshots/provisioning-error.png)
Loading
Loading