diff --git a/main/docs.json b/main/docs.json index 9037d5b8df..99e635e344 100644 --- a/main/docs.json +++ b/main/docs.json @@ -951,6 +951,7 @@ "pages": [ "docs/authenticate/protocols/scim", "docs/authenticate/protocols/scim/configure-inbound-scim", + "docs/authenticate/protocols/scim/configure-scim-groups", "docs/authenticate/protocols/scim/inbound-scim-for-azure-ad-saml-connections", "docs/authenticate/protocols/scim/inbound-scim-for-older-azure-ad-connections", "docs/authenticate/protocols/scim/inbound-scim-for-new-azure-ad-connections", @@ -4643,6 +4644,7 @@ "pages": [ "docs/fr-ca/authenticate/protocols/scim", "docs/fr-ca/authenticate/protocols/scim/configure-inbound-scim", + "docs/fr-ca/authenticate/protocols/scim/configure-scim-groups", "docs/fr-ca/authenticate/protocols/scim/inbound-scim-for-azure-ad-saml-connections", "docs/fr-ca/authenticate/protocols/scim/inbound-scim-for-older-azure-ad-connections", "docs/fr-ca/authenticate/protocols/scim/inbound-scim-for-new-azure-ad-connections", @@ -7929,6 +7931,7 @@ "pages": [ "docs/ja-jp/authenticate/protocols/scim", "docs/ja-jp/authenticate/protocols/scim/configure-inbound-scim", + "docs/ja-jp/authenticate/protocols/scim/configure-scim-groups", "docs/ja-jp/authenticate/protocols/scim/inbound-scim-for-azure-ad-saml-connections", "docs/ja-jp/authenticate/protocols/scim/inbound-scim-for-older-azure-ad-connections", "docs/ja-jp/authenticate/protocols/scim/inbound-scim-for-new-azure-ad-connections", diff --git a/main/docs/authenticate/protocols/scim/configure-scim-groups.mdx b/main/docs/authenticate/protocols/scim/configure-scim-groups.mdx new file mode 100644 index 0000000000..a1e7b5afc3 --- /dev/null +++ b/main/docs/authenticate/protocols/scim/configure-scim-groups.mdx @@ -0,0 +1,391 @@ +--- +title: Configure SCIM Groups for Enterprise Connections +description: Configure and manage SCIM group provisioning for Auth0 inbound SCIM Enterprise connections, including Okta Workforce and Microsoft Entra ID. +sidebarTitle: SCIM Groups +--- + + +Groups for Inbound SCIM Enterprise Connections is currently available in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta's [Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0's release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To participate in the early access, contact [Auth0 Support](https://support.auth0.com/) or your technical account team. + + +Auth0 supports [System for Cross-domain Identity Management (SCIM)](/docs/authenticate/protocols/scim), a protocol and schema providing a standardized way to provision, de-provision, and manage users and groups across systems. Group provisioning allows management and provisioning of groups from Enterprise identity providers, such as Okta Workforce and Microsoft Entra ID, directly into Auth0 via SCIM 2.0. + +## Benefits +| Feature | Description | +| --- | --- | +| SCIM `/groups` endpoint per connection | Each Enterprise customer gets dedicated `/users` and `/groups` SCIM endpoints and credentials scoped to only their user accounts and groups in Auth0. | +| View groups in the Auth0 Dashboard | All groups provisioned using SCIM are visible in the Auth0 Dashboard under the new **Enterprise Groups** tab, and per user under **User Management > Users**. | +| Use groups in Post-Login Actions | Access group information from Enterprise identity providers in post-login actions to make access control and authorization decisions. | +| Sync groups to external systems | Groups provisioned into Auth0 can be synchronized outbound to external systems using Auth0's event stream capability. | + +## Prerequisites + +Before getting started, you need: + +* An Auth0 tenant with the SCIM Groups Early Access feature enabled +* One of the following Enterprise connection types configured: + * SAML + * OpenID Connect + * Okta Workforce + * Microsoft Entra ID (Azure AD) +* [Postman](https://www.postman.com/downloads/) installed locally for testing + +## Enable SCIM for an Enterprise connection + +1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/enterprise). +2. Create a new connection: + * For a new connection, select the connection type: + * SAML + * OpenID Connect + * Okta Workforce + * Azure AD + * Or, choose an existing connection by selecting **Browse** by your identity provider (IdP). +3. Under the **Provisioning** tab: + * Toggle off **Sync user profile attributes at each login**. + * Toggle on **Sync user profiles using SCIM**. +4. Make sure **Sync user profiles using SCIM** it toggled on. + * Under **Mapping**: Configure attribute mapping between SCIM 2.0 user attributes and Auth0 user attributes. A default map is provided that covers most common SCIM attributes. + * Under **Setup**: Configure authentication tokens and retrieve the SCIM endpoint URL. +5. From the **Setup** tabe, copy the SCIM endpoint URL and token. You need the URL in later steps. + +## Test with Postman + +Use the updated Postman collection to test provisioning and deprovisioning of users and groups. The collection includes these SCIM 2.0 group commands: + +| Command | Description | +| --- | --- | +| `Groups - POST` | Creates a group with no members. | +| `Groups - POST (with members)` | Creates a group with a member, using a user created with `Users - POST`. | +| `Groups - GET` | Retrieves a group by its `group_id`. | +| `Groups - PUT` | Replaces a group, including all members. | +| `Groups - PATCH` | Updates group properties and adds or removes members. | +| `Groups - SEARCH (with query)` | Searches for groups using a SCIM filter as described in [RFC7644 Section 3.4.2](https://tools.ietf.org/html/rfc7644#section-3.4.2). | +| `Groups - DELETE` | Deletes a group by its `group_id`. | + +1. Launch Postman, select **File > Import**, and drag the file `SCIM 2.0 Auth0 Tests.postman_collection.json` into the import dialog. +2. Select the **SCIM 2.0 Tests** collection, then select the **Variables** tab. Copy the **SCIM Endpoint URL** from the Auth0 Dashboard **Setup** tab and paste it into the **Current Value** field next to `SCIM-ENDPOINT-URL`. +3. In the Auth0 Dashboard, select **Generate New Token > Generate Token > Copy and Close**. In Postman, select the **Authorization** tab, paste the token into the **Token** field, then select **Save**. +4. Run the `Users - POST` command to create a user that will be referenced in the group operations. +5. Run the group commands in this sequence: + 1. `Groups - POST` + 2. `Groups - GET` + 3. `Groups - PATCH` + 4. `Groups - PUT` + 5. `Groups - SEARCH (with query)` + 6. `Groups - DELETE` + + After each command, you can view the results in Postman and the corresponding log entry under [**Monitoring > Logs**](https://manage.auth0.com/#/logs) in the Auth0 Dashboard. + +## Test with external identity providers + + + + +There are two ways to configure SCIM group provisioning in Okta. Choose the method that matches your connection type and group size requirements: + +| Method | Description | Considerations | +| --- | --- | --- | +| **SCIM template application** | Uses a SCIM 2.0 template app in Okta that supports the SCIM `PATCH` method with groups. Required for groups over 10,000 members. | Works alongside existing SAML or OIDC SSO integrations. Supports groups with more than 10,000 members. | +| **SAML application** | Uses the existing **Provisioning** tab for SAML applications in Okta. Does not support SCIM `PATCH`, limiting the maximum group members to what can be sent in a single `POST` or `PUT` request. | SAML integrations only. Does not support groups with more than 10,000 members. | + +### Okta SCIM template application + + +Connect your Auth0 tenant to Okta for SSO using one of these methods: +* [Configure Okta as an OpenID Connect Identity Provider](/docs/authenticate/identity-providers/enterprise-identity-providers/okta) +* [Configure Okta as a SAML Identity Provider](/docs/authenticate/identity-providers/enterprise-identity-providers/saml) + + +1. In the Okta portal, select **Applications > Browse App Catalog**, search for **(OAuth Bearer Token) Governance with SCIM 2.0**, and select **Add Integration**. Set an **Application label**, check **Do not display application icon to users**, uncheck **Browser plugin auto-submit**, then select **Next** and **Done**. +2. From the integration's settings page, select the **Provisioning** tab, then **Configure API Integration**. Check **Enable API Integration**. Copy the **SCIM Endpoint URL** from the Auth0 Dashboard **Setup** tab and paste it into the **SCIM 2.0 Base URL** field, removing any trailing forward slash. In the Auth0 Dashboard, select **Generate New Token > Generate Token > Copy and Close**, then paste the token into the **OAuth Bearer Token** field in Okta. Optionally select **Test API Credentials**, then select **Save**. +3. Next to **Provisioning To App**, select **Edit**. Enable only: **Create Users**, **Update User Attributes**, and **Deactivate Users**. Uncheck **Set password when creating new users**, then select **Save**. +4. Under **Attribute Mappings**, use the **X** button to delete these lines, which can cause issues during `PUT` operations: + + | Attribute | Value | + | --- | --- | + | Primary email type | `(user.email != null && user.email != '') ? 'work' : ''` | + | Primary phone type | `(user.primaryPhone != null && user.primaryPhone != '') ? 'work' : ''` | + | Address type | `(user.streetAddress != null && user.streetAddress != '') ? 'work' : ''` | + + Optionally configure additional SCIM attributes to send from Okta to your SCIM endpoint. +5. Use the **Assignments** tab to assign groups to your application. Assigning a group provisions its users into your Auth0 tenant. + + + The same groups and users must be assigned to both the SSO app instance and the SCIM app instance in Okta. + + +6. Select the **Push Groups** tab, find and select the group to push, then select **Save**. This provisions the full group object to Auth0. For more information on the relationship between Group Push and assignments, read [Okta's App assignments and Group Push documentation](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-group-push-main.htm). + +### Okta SAML application + +Configure a SAML integration for SSO: [Configure Okta as a SAML Identity Provider](/docs/authenticate/identity-providers/enterprise-identity-providers/saml) + +1. Select your integration in Okta, then select the **General** tab and choose **Edit**. In the **Provisioning** section, select **SCIM**, then **Save**. +2. Select the **Provisioning** tab, then the **Integration** tab, and choose **Edit**. Copy the **SCIM Endpoint URL** from the Auth0 Dashboard and paste it into the **SCIM connector base URL** field. Set **Unique identifier field for users** to `userName`. Under **Supported provisioning actions**, select **Push New Users**, **Push Profile Updates**, and **Push Groups**. Set **Authentication Mode** to **HTTP Header**. In the Auth0 Dashboard, select **Generate New Token > Generate Token > Copy and Close**, then paste the token into the **Authorization** field in Okta. Optionally select **Test Connection Configuration**, then select **Save**. +3. Go to **Provisioning > Settings > To App**, select **Edit**, enable only **Create Users**, **Update User Attributes**, and **Deactivate Users**, then select **Save**. +4. Under **Attribute Mappings**, use the **X** button to delete these lines: + + | Attribute | Value | + | --- | --- | + | Primary email type | `(user.email != null && user.email != '') ? 'work' : ''` | + | Primary phone type | `(user.primaryPhone != null && user.primaryPhone != '') ? 'work' : ''` | + | Address type | `(user.streetAddress != null && user.streetAddress != '') ? 'work' : ''` | + + Optionally configure additional SCIM attributes to send to your SCIM endpoint. +5. Use the **Assignments** tab to assign groups to your application. Assigning a group provisions its users into your Auth0 tenant. +6. Select the **Push Groups** tab, find and select the group to push, then select **Save**. For more information, read [Okta's App assignments and Group Push documentation](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-group-push-main.htm). + + + + +First, complete SCIM user provisioning setup using one of these guides: +* [Inbound SCIM for New Azure AD Connections](/docs/authenticate/protocols/scim/inbound-scim-for-new-azure-ad-connections) +* [Inbound SCIM for Azure AD SAML Connections](/docs/authenticate/protocols/scim/inbound-scim-for-azure-ad-saml-connections) + +Once users can be provisioned, follow the steps below to add group support. + +### Generate a token with group scopes + +To enable group support, go to **Authentication > Enterprise > [Connection type] > [Connection] > Provisioning > Sync user profiles using SCIM > Setup** and generate a new token with these permissions: + +* `get:users`, `post:users`, `patch:users`, `delete:users` +* `get:groups`, `post:groups`, `patch:groups`, `delete:groups` + +Copy the token and update the **Secret Token** field in your Microsoft Azure portal SCIM integration. + +### Enable group provisioning in Azure AD + +1. In the Microsoft Azure portal, go to **Microsoft Entra ID > Enterprise Applications > [Your Application] > Provisioning**. Under **Mappings**, confirm that **Provision Entra ID Groups** is set to **Enabled**. +2. Select **Users and Groups** on the left, then select **Add User/Group** to assign a group to your Auth0 connection. +3. Select **Provision on demand** on the left, enter the name of the group you assigned, then select **Provision** to test provisioning that group to Auth0. + + + + +## View groups in the Auth0 Dashboard + +Groups created and updated using SCIM are visible in two locations in the Auth0 Dashboard: + +* **User Management > Enterprise Groups** — Browse all groups created using SCIM across all connections. +* **User Management > Users > [User] > Enterprise Groups** — View all groups a specific user belongs to. + +## Use groups in Post-Login Actions + +Use groups pushed from Enterprise identity providers in a Post-Login Action to pass group information in tokens issued by Auth0, or to make access control decisions at login. Two new API functions are available: + +### `api.groups.getUserGroups(options)` + +Returns a paginated list of groups the current user belongs to. + +| Parameter | Description | +| --- | --- | +| `options` | Optional. JSON object with pagination properties: `take` (integer, 1–100; defaults to 50) and `from` (pagination cursor from the `next` property of a previous response). | + +```javascript +exports.onExecutePostLogin = async (event, api) => { + // Get all group memberships + const get_groups = await api.groups.getUserGroups(); + const groups = get_groups.groups; + console.log("All group memberships:", groups); + + // Get first 10 group names + const get_groups2 = await api.groups.getUserGroups({ take: 10 }); + const groups2 = get_groups2.groups.map(group => group.name); + console.log("First 10 group memberships (names only):", groups2); + + // Get next 10 group names using pagination cursor + const get_groups3 = await api.groups.getUserGroups({ from: get_groups2.next, take: 10 }); + const groups3 = get_groups3.groups.map(group => group.name); + console.log("Next 10 group memberships (names only):", groups3); +}; +``` + +To add group data to tokens, read [`api.idToken.setCustomClaim`](https://auth0.com/docs/customize/actions/flows-and-triggers/login-flow/api-object#api-idtoken-setcustomclaim) and [`api.accessToken.setCustomClaim`](https://auth0.com/docs/customize/actions/flows-and-triggers/login-flow/api-object#api-accesstoken-setcustomclaim). + +### `api.groups.hasGroupMembership(groups)` + +Checks whether the current user belongs to any of the specified groups, and returns details about matching groups. + +| Parameter | Description | +| --- | --- | +| `groups` | An array of group identifiers (IDs or names) to check membership against. | + +```javascript +exports.onExecutePostLogin = async (event, api) => { + // Check if user is a member of the "Admins" group + const check_groups = await api.groups.hasGroupMembership(["Admins"]); + + const is_admin = check_groups.memberships["Admins"] + && check_groups.memberships["Admins"].is_member; + console.log("Is member of Admins group?", is_admin); + + const matched_groups = check_groups.memberships["Admins"] + && check_groups.memberships["Admins"].matches; + console.log("Details of matched groups:", matched_groups); +}; +``` + +Use the result to allow or deny application access with [`api.access.deny`](https://auth0.com/docs/customize/actions/flows-and-triggers/login-flow/api-object#api-access-deny). You can also use the Actions **Real-time logs** view in Auth0 to view console output when testing. + +## Sync groups to external systems + +Use [Auth0 Event Streams](/docs/customize/log-streams) to send real-time notifications about group changes to a custom webhook or AWS EventBridge. + +1. Follow [Create an Event Stream](/docs/customize/log-streams) to set up a custom webhook or AWS EventBridge stream in the Auth0 Dashboard. +2. On the **Settings** page for your webhook, enable all available events under **Groups** and **Users**. +3. Use the Postman collection or an external identity provider to create, update, or delete groups and verify that events are delivered to your endpoint. + +### Group event types + + + + Published when a group is created in an Auth0 Enterprise connection using SCIM. + + ```json + { + "id": "grp_2YefPa1L6vj99WEw7Urdep", + "name": "Group Name", + "type": "connection", + "external_id": "028930", + "connection_id": "con_Fg265UdlvvK3KG1z", + "created_at": "2025-10-29T21:36:52.878Z" + } + ``` + + + Published when a group is updated in an Auth0 Enterprise connection using SCIM. + + ```json + { + "id": "grp_2YefPa1L6vj99WEw7Urdep", + "name": "Group Name", + "type": "connection", + "external_id": "028930", + "connection_id": "con_Fg265UdlvvK3KG1z", + "created_at": "2025-10-29T21:36:52.878Z", + "updated_at": "2025-10-31T21:21:10.354Z" + } + ``` + + + Published when a group is deleted in an Auth0 Enterprise connection using SCIM. + + ```json + { + "id": "grp_2YefPa1L6vj99WEw7Urdep", + "name": "Group Name", + "type": "connection", + "external_id": "028930", + "connection_id": "con_Fg265UdlvvK3KG1z", + "created_at": "2025-10-29T21:36:52.878Z", + "updated_at": "2025-10-31T21:21:10.354Z" + } + ``` + + + Published when a member is added to a group in an Auth0 Enterprise connection using SCIM. + + ```json + { + "group": { + "id": "grp_2YefPa1L6vj99WEw7Urdep", + "type": "connection", + "connection_id": "con_Fg265UdlvvK3KG1z", + "external_id": "028930" + }, + "member": { + "member_type": "user", + "id": "samlp|saml-idp|bjensen", + "type": "connection", + "connection_id": "con_Fg265UdlvvK3KG1z" + } + } + ``` + + + Published when a member is removed from a group in an Auth0 Enterprise connection using SCIM. + + ```json + { + "group": { + "id": "grp_2YefPa1L6vj99WEw7Urdep", + "type": "connection", + "connection_id": "con_Fg265UdlvvK3KG1z", + "external_id": "028930" + }, + "member": { + "member_type": "user", + "id": "samlp|saml-idp|bjensen", + "type": "connection", + "connection_id": "con_Fg265UdlvvK3KG1z" + } + } + ``` + + + +## Monitor and troubleshoot + +View the full details of all SCIM requests in [**Monitoring > Logs**](https://manage.auth0.com/#/logs) in the Auth0 Dashboard. Selecting a SCIM operation log entry reveals the details of the request, including the SCIM attribute names and values sent by the SCIM client. + + +`POST` or `PUT` operations for a group with more than 1,000 members will not include the `members` attribute in the logs due to log size limitations. + + +## Self-Service SSO + +To enable SCIM Groups for a Self-Service SSO connection, follow the Self-Service SSO setup documentation. Configure provisioning as part of the access ticket: + +1. **Create a self-service profile** following the Self-Service SSO instructions. +2. **Create a self-service access ticket**. Under **Provisioning**, optionally enable **Sync Users and Groups through Provisioning**, which exposes these settings: + * **Bearer Token Expiration** — Define an expiration date for the SCIM bearer token. Tokens do not expire by default. + * **Bearer Token Permissions (Scopes)** — Choose which operations the token can perform. All provisioning scopes are enabled by default: + * Users: `get:users`, `post:users`, `put:users`, `patch:users`, `delete:users` + * Groups: `get:groups`, `post:groups`, `put:groups`, `patch:groups`, `delete:groups` +3. **Customer initiates SSO configuration** — Your enterprise customer configures their identity provider through your application. +4. **SCIM configuration** — During SSO setup, if the identity provider supports SCIM, your customer receives a SCIM Endpoint URL and an authentication token from Auth0. The token is generated automatically with the scopes defined in the access ticket — no manual token creation is required. + +## Limits + +### Entity limits + +| Entity | Operation | Limit | +| --- | --- | --- | +| Maximum groups per connection | Any | 10,000 | +| Maximum members per group | Any | 200,000 | +| Maximum members in `POST` operations | `POST` | 10,000 | +| Maximum members in `PUT` operations | `PUT` | 10,000 | +| Maximum members in `PATCH` operations | `PATCH` | 1,000 | + + +`POST`, `PUT`, and `PATCH` commands containing the SCIM `members` attribute are processed asynchronously. If an asynchronous member operation fails after the initial response, the error is reported in Auth0 tenant logs. + +SCIM clients that do not support `PATCH` cannot provision more members per group than the `POST` or `PUT` limits allow. + + +### Rate limits + +For more information, read [Rate Limit Policy](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy). + +| Limit type | Endpoint path | Operation | Limit | +| --- | --- | --- | --- | +| Single SCIM connection endpoint | `/scim/v2/connections/{connection-id}` | Any | 25 requests/second | +| Global tenant limit (all connections) | `/scim/v2/connections/*` | Any | 100 requests/second | + +## Management API + +All groups created in your Auth0 tenant via SCIM can be retrieved using the [Auth0 Management API](https://auth0.com/docs/api/management/v2). The following endpoints are available: + +* `GET /api/v2/groups` +* `GET /api/v2/groups/{id}` +* `GET /api/v2/groups/{id}/members` +* `GET /api/v2/users/{id}/groups` + +## Learn more + +* [Configure Inbound SCIM](/docs/authenticate/protocols/scim/configure-inbound-scim) +* [Inbound SCIM for Okta Workforce Connections](/docs/authenticate/protocols/scim/inbound-scim-for-okta-workforce-connections) +* [Inbound SCIM for Okta Workforce SAML Connections](/docs/authenticate/protocols/scim/inbound-scim-for-okta-workforce-saml-connections) +* [Inbound SCIM for New Azure AD Connections](/docs/authenticate/protocols/scim/inbound-scim-for-new-azure-ad-connections) +* [Inbound SCIM for Azure AD SAML Connections](/docs/authenticate/protocols/scim/inbound-scim-for-azure-ad-saml-connections) +* [Manage an Inbound SCIM Deployment with the Management API](/docs/authenticate/protocols/scim/manage-an-inbound-scim-deployment-with-the-management-api)