From 40388c9de98bda5fa5579aa096b6b22e26d869d6 Mon Sep 17 00:00:00 2001 From: KaveeshaPiumini Date: Wed, 4 Dec 2024 16:10:54 +0530 Subject: [PATCH 1/5] Docs for SCIM2 Build User Creation Payload --- .../build-scim2-user-creation-payload.md | 1 + en/asgardeo/docs/apis/scim2/index.md | 3 +- en/asgardeo/mkdocs.yml | 2 + .../build-scim2-user-creation-payload.md | 1 + .../7.0.0/docs/apis/scim2/index.md | 3 +- en/identity-server/7.0.0/mkdocs.yml | 2 + .../build-scim2-user-creation-payload.md | 224 ++++++++++++++++++ 7 files changed, 234 insertions(+), 2 deletions(-) create mode 100644 en/asgardeo/docs/apis/scim2/build-scim2-user-creation-payload.md create mode 100644 en/identity-server/7.0.0/docs/apis/scim2/build-scim2-user-creation-payload.md create mode 100644 en/includes/apis/scim2/build-scim2-user-creation-payload.md diff --git a/en/asgardeo/docs/apis/scim2/build-scim2-user-creation-payload.md b/en/asgardeo/docs/apis/scim2/build-scim2-user-creation-payload.md new file mode 100644 index 0000000000..688bc0c6e3 --- /dev/null +++ b/en/asgardeo/docs/apis/scim2/build-scim2-user-creation-payload.md @@ -0,0 +1 @@ +{% include "../../../../includes/apis/scim2/build-scim2-user-creation-payload.md" %} diff --git a/en/asgardeo/docs/apis/scim2/index.md b/en/asgardeo/docs/apis/scim2/index.md index cc255c93a4..77ac8d427b 100644 --- a/en/asgardeo/docs/apis/scim2/index.md +++ b/en/asgardeo/docs/apis/scim2/index.md @@ -6,4 +6,5 @@ The SCIM2 Rest APIs of {{product_name}} implements the SCIM 2.0 protocol accordi - [SCIM2 Groups API]({{base_path}}/apis/scim2/scim2-groups-rest-api/) - [SCIM2 Bulk API]({{base_path}}/apis/scim2/scim2-bulk-rest-api/) - [SCIM2 Resource Types API]({{base_path}}/apis/scim2/scim2-resource-types-rest-api/) -- [SCIM2 Service Provider Configs API]({{base_path}}/apis/scim2/scim2-service-provider-configs-rest-api/) \ No newline at end of file +- [SCIM2 Service Provider Configs API]({{base_path}}/apis/scim2/scim2-service-provider-configs-rest-api/) +- [SCIM2 Build User Creation Payload]({{base_path}}/apis/scim2/build-scim2-user-creation-payload/) diff --git a/en/asgardeo/mkdocs.yml b/en/asgardeo/mkdocs.yml index 08787ad888..c22d96fc29 100644 --- a/en/asgardeo/mkdocs.yml +++ b/en/asgardeo/mkdocs.yml @@ -122,6 +122,7 @@ plugins: 'apis/organization-apis/org-user-mgt.md': 'apis/organization-apis/scim2/scim2-org-user-mgt.md' 'apis/organization-apis/org-group-mgt.md': 'apis/organization-apis/scim2/scim2-org-group-mgt.md' 'apis/organization-apis/scim-bulk.md': 'apis/organization-apis/scim2/scim2-org-bulk.md' + 'apis/build-scim2-user-creation-payload.md': 'apis/scim2/build-scim2-user-creation-payload.md' 'guides/api-authorization.md' : 'guides/authorization/api-authorization/api-authorization.md' 'guides/account-configurations.md': 'guides/user-accounts/index.md' 'references/application-logs.md' : 'guides/asgardeo-logs.md' @@ -418,6 +419,7 @@ nav: - SCIM 2.0 Bulk API: apis/scim2/scim2-bulk-rest-api.md - SCIM 2.0 Resource types API: apis/scim2/scim2-resource-types-rest-api.md - SCIM 2.0 Service provider configs API: apis/scim2/scim2-service-provider-configs-rest-api.md + - SCIM 2.0 Build user creation payload: apis/scim2/build-scim2-user-creation-payload.md - User account associations API: apis/association-management-by-admin.md - Account Recovery API: apis/user-account-recovery.md - Offline user onboard management API: apis/offline-user-onboard.md diff --git a/en/identity-server/7.0.0/docs/apis/scim2/build-scim2-user-creation-payload.md b/en/identity-server/7.0.0/docs/apis/scim2/build-scim2-user-creation-payload.md new file mode 100644 index 0000000000..bd2557391c --- /dev/null +++ b/en/identity-server/7.0.0/docs/apis/scim2/build-scim2-user-creation-payload.md @@ -0,0 +1 @@ +{% include "../../../../../includes/apis/scim2/build-scim2-user-creation-payload.md" %} diff --git a/en/identity-server/7.0.0/docs/apis/scim2/index.md b/en/identity-server/7.0.0/docs/apis/scim2/index.md index 29605ddb2e..70ca95a463 100644 --- a/en/identity-server/7.0.0/docs/apis/scim2/index.md +++ b/en/identity-server/7.0.0/docs/apis/scim2/index.md @@ -8,4 +8,5 @@ The SCIM2 Rest APIs of {{product_name}} implements the SCIM 2.0 protocol accordi - [SCIM 2.0 Bulk API]({{base_path}}/apis/scim2/scim2-bulk-rest-api/) - [SCIM 2.0 Batch operations]({{base_path}}/apis/scim2/scim2-batch-operations/) - [SCIM 2.0 Resource types API]({{base_path}}/apis/scim2/scim2-resource-types/) -- [SCIM 2.0 Service provider configuration API]({{base_path}}/apis/scim2/scim2-sp-config-rest-api/) \ No newline at end of file +- [SCIM 2.0 Service provider configuration API]({{base_path}}/apis/scim2/scim2-sp-config-rest-api/) +- [SCIM 2.0 Build User Creation Payload]({{base_path}}/apis/scim2/build-scim2-user-creation-payload/) diff --git a/en/identity-server/7.0.0/mkdocs.yml b/en/identity-server/7.0.0/mkdocs.yml index 54606696b7..5cdf2c495d 100644 --- a/en/identity-server/7.0.0/mkdocs.yml +++ b/en/identity-server/7.0.0/mkdocs.yml @@ -325,6 +325,7 @@ plugins: 'apis/scim2-bulk-rest-apis.md': 'apis/scim2/scim2-bulk-rest-api.md' 'apis/scim2-batch-operations.md': 'apis/scim2/scim2-batch-operations.md' 'apis/scim2-sp-config-rest-apis.md': 'apis/scim2/scim2-sp-config-rest-api.md' + 'apis/build-scim2-user-creation-payload.md': 'apis/scim2/build-scim2-user-creation-payload.md' 'apis/organization-apis/org-scim2-bulk-mgt.md': 'apis/organization-apis/scim2/scim2-org-bulk.md' 'apis/organization-apis/org-user-mgt.md': 'apis/organization-apis/scim2/scim2-org-user-mgt.md' 'apis/organization-apis/org-group-mgt.md': 'apis/organization-apis/scim2/scim2-org-group-mgt.md' @@ -791,6 +792,7 @@ nav: - SCIM 2.0 Batch operations: apis/scim2/scim2-batch-operations.md - SCIM 2.0 Resource types API: apis/scim2/scim2-resource-types.md - SCIM 2.0 Service provider configuration API: apis/scim2/scim2-sp-config-rest-api.md + - SCIM 2.0 Build user creation payload: apis/scim2/build-scim2-user-creation-payload.md - Account recovery APIs: - Account recovery v0.9 API: apis/use-the-account-recovery-rest-apis.md - Account recovery v1 API (deprecated): apis/user-account-recovery-v1-rest-api.md diff --git a/en/includes/apis/scim2/build-scim2-user-creation-payload.md b/en/includes/apis/scim2/build-scim2-user-creation-payload.md new file mode 100644 index 0000000000..dd02bbdfdd --- /dev/null +++ b/en/includes/apis/scim2/build-scim2-user-creation-payload.md @@ -0,0 +1,224 @@ +# Build SCIM 2.0 User Creation Payloads + + +This guide explains how to build SCIM 2.0 payloads in compliance with the SCIM 2.0 specification. + + +## Step 1 : Identifying SCIM 2.0 Claims for User Attributes + + +To build a SCIM 2.0 payload, the first step is identifying the SCIM schema mapping for your user attribute: + + +Navigate to **User Attributes & Stores** → **Attributes** → **SCIM 2.0** in the {{ product_name }} console. You will see the following schema options: + + - **Core Schema** + - **User Schema** + - **Enterprise Schema** + - **Custom Schema** {% if product_name == "WSO2 Identity Server" %} (if you have mapped any custom user attribute to a SCIM claim). {% endif %} + + +> For further details refer [Manage SCIM 2.0 attribute mappings]({{base_path}}/guides/users/attributes/manage-scim2-attribute-mappings) + + +### Rules for Schema Usage in SCIM 2.0 Payloads + + +- If your user attribute is mapped to **Core Schema** or **User Schema**, the schema name does not need to be qualified in the SCIM payload. +- If your user attribute is mapped to **Enterprise Schema** or **Custom Schema**, each SCIM attribute under these schemas must be placed under the schema’s namespace. + + +#### Example +```json +{ + "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { + "employeeNumber": "1234A" + }, + "urn:scim:wso2:schema": { + "customAttribute": "xyz" + } +} + + +``` + + +## Step 2 : Attribute Types in SCIM 2.0 Payloads + + +Each SCIM attribute falls into one of the following attribute types, which determine the format of the attribute in the payload. + + + + +### Singular Attributes + +1. **Simple Attributes** + + Example: + ```json + { + "userName": "kim" + } + ``` + + +2. **Complex Attributes** + + Example: + ```json + { + "name": { + "givenName": "Kim", + "familyName": "Berry" + } + } + ``` + + +### Multi-Valued Attributes +1. **Simple Attributes** + + Extended attribute example: + ```json + { + "urn:scim:wso2:schema:userDevices": { + "devices": ["d1", "d2"] + } + } + ``` + + > No multivalued simple attributes are defined in the Core Schema, User Schema, or Enterprise Schema. + + +2. **Complex Attributes** + + Example for `emails` attribute: + ```json + { + "emails": [ + { + "type": "home", + "value": "kim@gmail.com", + "primary": true + }, + { + "type": "work", + "value": "kim@wso2.com" + } + ] + } + ``` + +!!! note + The following references provide comprehensive information about SCIM attribute types and their respective definitions. These details can help identify the type of attributes used in SCIM 2.0 payloads: + + - For attributes under **Core Schema**, **User Schema** and Specification-defined Enterprise Schema, refer to [RFC 7643 Section 8.7.1](https://datatracker.ietf.org/doc/html/rfc7643#section-8.7.1). + + {% if product_name == "WSO2 Identity Server" %} + - For WSO2 IS-defined Enterprise Schema attributes, refer to the `scim2-schema-extension.config` file located in the `/repository/conf/` directory. + {% endif %} + + - For Custom Schema attributes, check the type meta attribute of the mapped local attribute. + +## Step 3: Determining the Type of SCIM 2.0 Attributes + +The patterns described below are used for SCIM attributes to map local user attributes. SCIM claim mappings should follow these patterns for different types of SCIM attributes. + +Based on the pattern: + + 1. Identify the type of the attribute. + 2. Construct the payload as outlined in Step 2. + + +### Singular Simple Attributes + + +- **Format:** `:` +- By default, these attributes are treated as singular simple attributes. + + +### Multivalued Simple Attributes + + +- **Format:** `:` +- These attributes are treated as multivalued simple attributes when the `type` property is specified. + + + > By default, Core Schema, User Schema, and Enterprise Schema do not have multivalued simple attributes. + + +### Complex Attributes with Sub-Attributes + + +- **Format:** `:.` +- This format is used for sub-attributes of complex attributes. + + +### Multivalued Complex Attributes + + +- **Format:** `:` and `:.` +- By default, multivalued complex attributes support only the `type` and `value` sub-attributes. +- Examples include attributes like `emails` and `addresses`. + + +## Example Payload +```json +{ + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User", + "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User", + "urn:scim:wso2:schema" + ], + "userName": "kim", + "password": "MyPa33w@rd", + "name": { + "givenName": "Kim", + "familyName": "Berry" + }, + "emails": [ + { + "type": "home", + "value": "kim@gmail.com", + "primary": true + }, + { + "type": "work", + "value": "kim@wso2.com" + } + ], + "addresses": [ + { + "type": "home", + "value": "123 Main St, City, Country" + }, + { + "type": "work", + "value": "456 Office Rd, City, Country" + } + ], + "phoneNumbers": [ + { + "type": "mobile", + "value": "+1234567890" + }, + { + "type": "work", + "value": "+0987654321" + } + ], + "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { + "employeeNumber": "1234A", + "division": "R&D", + "manager": { + "value": "Taylor", + "displayName": "Taylor Smith" + } + }, + "urn:scim:wso2:schema": { + "customAttribute": "customValue", + "devices": ["d1", "d2"] + } +} +``` From 9748500c60874b89476c43c9b2304827ff89fd32 Mon Sep 17 00:00:00 2001 From: KaveeshaPiumini Date: Wed, 4 Dec 2024 16:10:54 +0530 Subject: [PATCH 2/5] Docs for SCIM2 Build User Creation Payload --- en/includes/apis/scim2/build-scim2-user-creation-payload.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/en/includes/apis/scim2/build-scim2-user-creation-payload.md b/en/includes/apis/scim2/build-scim2-user-creation-payload.md index dd02bbdfdd..4d8b3f2293 100644 --- a/en/includes/apis/scim2/build-scim2-user-creation-payload.md +++ b/en/includes/apis/scim2/build-scim2-user-creation-payload.md @@ -49,8 +49,6 @@ Navigate to **User Attributes & Stores** → **Attributes** → **SCIM 2.0** in Each SCIM attribute falls into one of the following attribute types, which determine the format of the attribute in the payload. - - ### Singular Attributes 1. **Simple Attributes** From f6909b753c624ff96efc500253e3acaa63c1c6c6 Mon Sep 17 00:00:00 2001 From: KaveeshaPiumini Date: Wed, 4 Dec 2024 22:39:22 +0530 Subject: [PATCH 3/5] comments addressed --- .../7.0.0/docs/apis/scim2/index.md | 2 +- en/identity-server/7.0.0/mkdocs.yml | 4 +-- .../build-scim2-user-creation-payload.md | 26 +++++-------------- 3 files changed, 10 insertions(+), 22 deletions(-) diff --git a/en/identity-server/7.0.0/docs/apis/scim2/index.md b/en/identity-server/7.0.0/docs/apis/scim2/index.md index 70ca95a463..316309c980 100644 --- a/en/identity-server/7.0.0/docs/apis/scim2/index.md +++ b/en/identity-server/7.0.0/docs/apis/scim2/index.md @@ -4,9 +4,9 @@ The SCIM2 Rest APIs of {{product_name}} implements the SCIM 2.0 protocol accordi - [SCIM 2.0 Users API]({{base_path}}/apis/scim2/scim2-users-rest-api/) - [SCIM 2.0 Groups API]({{base_path}}/apis/scim2/scim2-groups-rest-api/) +- [SCIM 2.0 Build User Creation Payload]({{base_path}}/apis/scim2/build-scim2-user-creation-payload/) - [SCIM 2.0 Patch operations]({{base_path}}/apis/scim2/scim2-patch-operations/) - [SCIM 2.0 Bulk API]({{base_path}}/apis/scim2/scim2-bulk-rest-api/) - [SCIM 2.0 Batch operations]({{base_path}}/apis/scim2/scim2-batch-operations/) - [SCIM 2.0 Resource types API]({{base_path}}/apis/scim2/scim2-resource-types/) - [SCIM 2.0 Service provider configuration API]({{base_path}}/apis/scim2/scim2-sp-config-rest-api/) -- [SCIM 2.0 Build User Creation Payload]({{base_path}}/apis/scim2/build-scim2-user-creation-payload/) diff --git a/en/identity-server/7.0.0/mkdocs.yml b/en/identity-server/7.0.0/mkdocs.yml index 5cdf2c495d..e80ee4e938 100644 --- a/en/identity-server/7.0.0/mkdocs.yml +++ b/en/identity-server/7.0.0/mkdocs.yml @@ -321,11 +321,11 @@ plugins: 'guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md': 'guides/authentication/app-native-authentication/index.md' 'apis/scim2-users-rest-apis.md': 'apis/scim2/scim2-users-rest-api.md' 'apis/scim2-groups-rest-apis.md': 'apis/scim2/scim2-groups-rest-api.md' + 'apis/build-scim2-user-creation-payload.md': 'apis/scim2/build-scim2-user-creation-payload.md' 'apis/scim2-patch-operations.md': 'apis/scim2/scim2-patch-operations.md' 'apis/scim2-bulk-rest-apis.md': 'apis/scim2/scim2-bulk-rest-api.md' 'apis/scim2-batch-operations.md': 'apis/scim2/scim2-batch-operations.md' 'apis/scim2-sp-config-rest-apis.md': 'apis/scim2/scim2-sp-config-rest-api.md' - 'apis/build-scim2-user-creation-payload.md': 'apis/scim2/build-scim2-user-creation-payload.md' 'apis/organization-apis/org-scim2-bulk-mgt.md': 'apis/organization-apis/scim2/scim2-org-bulk.md' 'apis/organization-apis/org-user-mgt.md': 'apis/organization-apis/scim2/scim2-org-user-mgt.md' 'apis/organization-apis/org-group-mgt.md': 'apis/organization-apis/scim2/scim2-org-group-mgt.md' @@ -787,12 +787,12 @@ nav: - SCIM 2.0 API: apis/scim2/index.md - SCIM 2.0 Users API: apis/scim2/scim2-users-rest-api.md - SCIM 2.0 Groups API: apis/scim2/scim2-groups-rest-api.md + - SCIM 2.0 Build user creation payload: apis/scim2/build-scim2-user-creation-payload.md - SCIM 2.0 Patch operations: apis/scim2/scim2-patch-operations.md - SCIM 2.0 Bulk API: apis/scim2/scim2-bulk-rest-api.md - SCIM 2.0 Batch operations: apis/scim2/scim2-batch-operations.md - SCIM 2.0 Resource types API: apis/scim2/scim2-resource-types.md - SCIM 2.0 Service provider configuration API: apis/scim2/scim2-sp-config-rest-api.md - - SCIM 2.0 Build user creation payload: apis/scim2/build-scim2-user-creation-payload.md - Account recovery APIs: - Account recovery v0.9 API: apis/use-the-account-recovery-rest-apis.md - Account recovery v1 API (deprecated): apis/user-account-recovery-v1-rest-api.md diff --git a/en/includes/apis/scim2/build-scim2-user-creation-payload.md b/en/includes/apis/scim2/build-scim2-user-creation-payload.md index 4d8b3f2293..df9e3db540 100644 --- a/en/includes/apis/scim2/build-scim2-user-creation-payload.md +++ b/en/includes/apis/scim2/build-scim2-user-creation-payload.md @@ -1,10 +1,10 @@ # Build SCIM 2.0 User Creation Payloads -This guide explains how to build SCIM 2.0 payloads in compliance with the SCIM 2.0 specification. +This guide explains how to build SCIM 2.0 user creation payloads in compliance with the SCIM 2.0 specification. -## Step 1 : Identifying SCIM 2.0 Claims for User Attributes +## Step 1 : Identifying SCIM 2.0 Attributes for User Attributes To build a SCIM 2.0 payload, the first step is identifying the SCIM schema mapping for your user attribute: @@ -15,7 +15,7 @@ Navigate to **User Attributes & Stores** → **Attributes** → **SCIM 2.0** in - **Core Schema** - **User Schema** - **Enterprise Schema** - - **Custom Schema** {% if product_name == "WSO2 Identity Server" %} (if you have mapped any custom user attribute to a SCIM claim). {% endif %} + - **Custom Schema** {% if product_name == "WSO2 Identity Server" %} (if you have mapped any custom user attribute to a SCIM attribute in the custom schema). {% endif %} > For further details refer [Manage SCIM 2.0 attribute mappings]({{base_path}}/guides/users/attributes/manage-scim2-attribute-mappings) @@ -24,7 +24,7 @@ Navigate to **User Attributes & Stores** → **Attributes** → **SCIM 2.0** in ### Rules for Schema Usage in SCIM 2.0 Payloads -- If your user attribute is mapped to **Core Schema** or **User Schema**, the schema name does not need to be qualified in the SCIM payload. +- If your user attribute is mapped to **Core Schema** or **User Schema**, the schema URI does not need to be qualified in the SCIM payload. - If your user attribute is mapped to **Enterprise Schema** or **Custom Schema**, each SCIM attribute under these schemas must be placed under the schema’s namespace. @@ -39,11 +39,10 @@ Navigate to **User Attributes & Stores** → **Attributes** → **SCIM 2.0** in } } - ``` -## Step 2 : Attribute Types in SCIM 2.0 Payloads +## Step 2 : Identify the Attribute Types and their SCIM 2.0 Payload Format Each SCIM attribute falls into one of the following attribute types, which determine the format of the attribute in the payload. @@ -80,7 +79,7 @@ Each SCIM attribute falls into one of the following attribute types, which deter Extended attribute example: ```json { - "urn:scim:wso2:schema:userDevices": { + "urn:scim:wso2:schema:user": { "devices": ["d1", "d2"] } } @@ -121,7 +120,7 @@ Each SCIM attribute falls into one of the following attribute types, which deter ## Step 3: Determining the Type of SCIM 2.0 Attributes -The patterns described below are used for SCIM attributes to map local user attributes. SCIM claim mappings should follow these patterns for different types of SCIM attributes. +The patterns described below are used for SCIM attributes to map local user attributes. SCIM attribute mappings should follow these patterns for different types of SCIM attributes. Based on the pattern: @@ -177,7 +176,6 @@ Based on the pattern: }, "emails": [ { - "type": "home", "value": "kim@gmail.com", "primary": true }, @@ -186,16 +184,6 @@ Based on the pattern: "value": "kim@wso2.com" } ], - "addresses": [ - { - "type": "home", - "value": "123 Main St, City, Country" - }, - { - "type": "work", - "value": "456 Office Rd, City, Country" - } - ], "phoneNumbers": [ { "type": "mobile", From 463cfa9094b58dda41c1a6b100940e4c59aab461 Mon Sep 17 00:00:00 2001 From: himeshsiriwardana Date: Thu, 5 Dec 2024 16:59:35 +0530 Subject: [PATCH 4/5] reformatted the scim2 payload doc --- en/asgardeo/mkdocs.yml | 7 +- .../7.0.0/docs/apis/scim2/index.md | 3 +- en/identity-server/7.0.0/mkdocs.yml | 3 +- .../build-scim2-user-creation-payload.md | 218 ++++++++++-------- 4 files changed, 136 insertions(+), 95 deletions(-) diff --git a/en/asgardeo/mkdocs.yml b/en/asgardeo/mkdocs.yml index c22d96fc29..c05ad8f240 100644 --- a/en/asgardeo/mkdocs.yml +++ b/en/asgardeo/mkdocs.yml @@ -98,7 +98,12 @@ hooks: - hooks.py plugins: - - search + - search: + indexing: "full" + separator: "[^\\w._]+" + lang: ['en'] + prebuild_index: true + ngram_length: 30 - markdownextradata: {} - include-markdown - redirects: diff --git a/en/identity-server/7.0.0/docs/apis/scim2/index.md b/en/identity-server/7.0.0/docs/apis/scim2/index.md index 316309c980..403856df47 100644 --- a/en/identity-server/7.0.0/docs/apis/scim2/index.md +++ b/en/identity-server/7.0.0/docs/apis/scim2/index.md @@ -4,9 +4,10 @@ The SCIM2 Rest APIs of {{product_name}} implements the SCIM 2.0 protocol accordi - [SCIM 2.0 Users API]({{base_path}}/apis/scim2/scim2-users-rest-api/) - [SCIM 2.0 Groups API]({{base_path}}/apis/scim2/scim2-groups-rest-api/) -- [SCIM 2.0 Build User Creation Payload]({{base_path}}/apis/scim2/build-scim2-user-creation-payload/) - [SCIM 2.0 Patch operations]({{base_path}}/apis/scim2/scim2-patch-operations/) - [SCIM 2.0 Bulk API]({{base_path}}/apis/scim2/scim2-bulk-rest-api/) - [SCIM 2.0 Batch operations]({{base_path}}/apis/scim2/scim2-batch-operations/) - [SCIM 2.0 Resource types API]({{base_path}}/apis/scim2/scim2-resource-types/) - [SCIM 2.0 Service provider configuration API]({{base_path}}/apis/scim2/scim2-sp-config-rest-api/) + +Additionally, learn how to [build SCIM 2.0 user creation payloads]({{base_path}}/apis/scim2/build-scim2-user-creation-payload/). diff --git a/en/identity-server/7.0.0/mkdocs.yml b/en/identity-server/7.0.0/mkdocs.yml index e80ee4e938..ab952d8d7d 100644 --- a/en/identity-server/7.0.0/mkdocs.yml +++ b/en/identity-server/7.0.0/mkdocs.yml @@ -787,12 +787,13 @@ nav: - SCIM 2.0 API: apis/scim2/index.md - SCIM 2.0 Users API: apis/scim2/scim2-users-rest-api.md - SCIM 2.0 Groups API: apis/scim2/scim2-groups-rest-api.md - - SCIM 2.0 Build user creation payload: apis/scim2/build-scim2-user-creation-payload.md - SCIM 2.0 Patch operations: apis/scim2/scim2-patch-operations.md - SCIM 2.0 Bulk API: apis/scim2/scim2-bulk-rest-api.md - SCIM 2.0 Batch operations: apis/scim2/scim2-batch-operations.md - SCIM 2.0 Resource types API: apis/scim2/scim2-resource-types.md - SCIM 2.0 Service provider configuration API: apis/scim2/scim2-sp-config-rest-api.md + - Additional resources: + - Build SCIM 2.0 user creation payload: apis/scim2/build-scim2-user-creation-payload.md - Account recovery APIs: - Account recovery v0.9 API: apis/use-the-account-recovery-rest-apis.md - Account recovery v1 API (deprecated): apis/user-account-recovery-v1-rest-api.md diff --git a/en/includes/apis/scim2/build-scim2-user-creation-payload.md b/en/includes/apis/scim2/build-scim2-user-creation-payload.md index df9e3db540..85e57572c4 100644 --- a/en/includes/apis/scim2/build-scim2-user-creation-payload.md +++ b/en/includes/apis/scim2/build-scim2-user-creation-payload.md @@ -1,58 +1,125 @@ -# Build SCIM 2.0 User Creation Payloads +# Build SCIM 2.0 user creation payloads +This guide provides information on building user creation payloads that align with the SCIM 2.0 specification. Follow the steps below to ensure your user creation payload meets the standard requirements. -This guide explains how to build SCIM 2.0 user creation payloads in compliance with the SCIM 2.0 specification. +## Step 1 : Determine the associated schema +{{product_name}} maps user attributes to the following SCIM 2.0 schemas: -## Step 1 : Identifying SCIM 2.0 Attributes for User Attributes +- Core Schema +- User Schema +- Enterprise Schema +- Custom Schema +The first step of building a SCIM 2.0 payload is to identify the schema mapping for your user attribute. -To build a SCIM 2.0 payload, the first step is identifying the SCIM schema mapping for your user attribute: +!!! note + - You may find these schemas on the {{product_name}} Console by navigating to **User Attributes & Stores** > **Attributes** > **SCIM 2.0**. Learn how to [Manage SCIM 2.0 attribute mappings]({{base_path}}/guides/users/attributes/manage-scim2-attribute-mappings). -Navigate to **User Attributes & Stores** → **Attributes** → **SCIM 2.0** in the {{ product_name }} console. You will see the following schema options: +For a user attribute, - - **Core Schema** - - **User Schema** - - **Enterprise Schema** - - **Custom Schema** {% if product_name == "WSO2 Identity Server" %} (if you have mapped any custom user attribute to a SCIM attribute in the custom schema). {% endif %} +- if it is mapped to the **Core Schema** or the **User Schema**, the schema URI does not need to be included in the SCIM payload. + ```json + { + "name": { + "givenName": "Kim", + "familyName": "Berry" + }, + "username": "kimberry" + } + ``` -> For further details refer [Manage SCIM 2.0 attribute mappings]({{base_path}}/guides/users/attributes/manage-scim2-attribute-mappings) +- If it is mapped to **Enterprise Schema** or **Custom Schema**, it needs to be placed under the namespace of the corresponding schema. -### Rules for Schema Usage in SCIM 2.0 Payloads + ```json + { + "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { + "employeeNumber": "1234A" + }, + "urn:scim:wso2:schema": { + "customAttribute": "xyz" + } + } + ``` +## Step 2 : Identify the attribute type -- If your user attribute is mapped to **Core Schema** or **User Schema**, the schema URI does not need to be qualified in the SCIM payload. -- If your user attribute is mapped to **Enterprise Schema** or **Custom Schema**, each SCIM attribute under these schemas must be placed under the schema’s namespace. +Each SCIM attribute belongs to one of the following types, which determine how the attribute is formatted in the payload. -#### Example -```json -{ - "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { - "employeeNumber": "1234A" - }, - "urn:scim:wso2:schema": { - "customAttribute": "xyz" - } -} +- **Single-valued Attributes** contain a single value. -``` + - **Simple Attributes** contain a single attribute. + ```json + { + "userName": "kim" + } + ``` -## Step 2 : Identify the Attribute Types and their SCIM 2.0 Payload Format + - **Complex Attributes** contain multiple sub-attributes. -Each SCIM attribute falls into one of the following attribute types, which determine the format of the attribute in the payload. + ```json + { + "name": { + "givenName": "Kim", + "familyName": "Berry" + } + } + ``` +- **Multi-Valued Attributes** hold multiple values -### Singular Attributes + - **Simple Attributes** contain a single attribute. -1. **Simple Attributes** + ```json + { + "devices": ["d1", "d2"] + } + ``` + + - **Complex Attributes** contain multiple sub-attributes. + + ```json + { + "emails": [ + { + "value": "kim@gmail.com", + "primary": true + }, + { + "type": "work", + "value": "kim@wso2.com" + } + ] + } + ``` + +!!! info + The following references provide comprehensive information about SCIM attribute types and their respective definitions. These details can help identify the type of attributes used in SCIM 2.0 payloads: + + - For attributes under core schema, user schema and SCIM2 specification-defined enterprise schema, refer to [RFC 7643 Section 8.7.1](https://datatracker.ietf.org/doc/html/rfc7643#section-8.7.1). + + {% if product_name == "WSO2 Identity Server" %} + - For {{product_name}}-defined enterprise schema attributes, refer to the `scim2-schema-extension.config` file located in the `/repository/conf/` directory. + {% endif %} + + - For custom schema attributes, check the `type` meta attribute of the mapped local attribute. + +## Step 3: Build the payload + +Let's combine the two steps above and build the payload for each attribute type. + +### For Core and User schemas + +The schema URI does not need to be included in the user creation payload. Therefore, you can simply add the attributes and their values to the payload as shown below. + +- Single-valued simple attributes - Example: ```json { "userName": "kim" @@ -60,9 +127,8 @@ Each SCIM attribute falls into one of the following attribute types, which deter ``` -2. **Complex Attributes** + - Single-valued complex attributes. - Example: ```json { "name": { @@ -72,30 +138,16 @@ Each SCIM attribute falls into one of the following attribute types, which deter } ``` +- Multi-Valued complex attributes -### Multi-Valued Attributes -1. **Simple Attributes** + !!! note - Extended attribute example: - ```json - { - "urn:scim:wso2:schema:user": { - "devices": ["d1", "d2"] - } - } - ``` - - > No multivalued simple attributes are defined in the Core Schema, User Schema, or Enterprise Schema. - - -2. **Complex Attributes** + By default, core schema, user schema, and enterprise schema do not have multi-valued simple attributes. - Example for `emails` attribute: ```json { "emails": [ { - "type": "home", "value": "kim@gmail.com", "primary": true }, @@ -107,58 +159,40 @@ Each SCIM attribute falls into one of the following attribute types, which deter } ``` -!!! note - The following references provide comprehensive information about SCIM attribute types and their respective definitions. These details can help identify the type of attributes used in SCIM 2.0 payloads: - - - For attributes under **Core Schema**, **User Schema** and Specification-defined Enterprise Schema, refer to [RFC 7643 Section 8.7.1](https://datatracker.ietf.org/doc/html/rfc7643#section-8.7.1). - - {% if product_name == "WSO2 Identity Server" %} - - For WSO2 IS-defined Enterprise Schema attributes, refer to the `scim2-schema-extension.config` file located in the `/repository/conf/` directory. - {% endif %} - - - For Custom Schema attributes, check the type meta attribute of the mapped local attribute. - -## Step 3: Determining the Type of SCIM 2.0 Attributes - -The patterns described below are used for SCIM attributes to map local user attributes. SCIM attribute mappings should follow these patterns for different types of SCIM attributes. - -Based on the pattern: - - 1. Identify the type of the attribute. - 2. Construct the payload as outlined in Step 2. - - -### Singular Simple Attributes - - -- **Format:** `:` -- By default, these attributes are treated as singular simple attributes. +### For other schemas +The schema URI needs to be included in the user creation payload. Therefore, when you are adding such an attribute be sure to do so under the relevant schema. -### Multivalued Simple Attributes +- Single-valued simple attributes + ```json + { + "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": + "employeeNumber": "1234A" + } + ``` -- **Format:** `:` -- These attributes are treated as multivalued simple attributes when the `type` property is specified. - - - > By default, Core Schema, User Schema, and Enterprise Schema do not have multivalued simple attributes. - - -### Complex Attributes with Sub-Attributes - - -- **Format:** `:.` -- This format is used for sub-attributes of complex attributes. - +- Single-valued complex attributes. -### Multivalued Complex Attributes + ```json + { + "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": + "manager": { + "value": "Taylor", + "displayName": "Taylor Smith" + } + } + ``` +- Multi-valued simple attributes -- **Format:** `:` and `:.` -- By default, multivalued complex attributes support only the `type` and `value` sub-attributes. -- Examples include attributes like `emails` and `addresses`. + ```json + { + "urn:scim:wso2:schema": + "devices": ["d1", "d2"] + } + ``` ## Example Payload ```json From e6c5bd6c452b1af34e0ed9a65931223f0acdcbc6 Mon Sep 17 00:00:00 2001 From: Himesh Siriwardana Date: Fri, 6 Dec 2024 14:49:38 +0530 Subject: [PATCH 5/5] Update en/includes/apis/scim2/build-scim2-user-creation-payload.md Co-authored-by: Anuradha Karunarathna --- en/includes/apis/scim2/build-scim2-user-creation-payload.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/includes/apis/scim2/build-scim2-user-creation-payload.md b/en/includes/apis/scim2/build-scim2-user-creation-payload.md index 85e57572c4..30ba43dce7 100644 --- a/en/includes/apis/scim2/build-scim2-user-creation-payload.md +++ b/en/includes/apis/scim2/build-scim2-user-creation-payload.md @@ -108,7 +108,7 @@ Each SCIM attribute belongs to one of the following types, which determine how t - For {{product_name}}-defined enterprise schema attributes, refer to the `scim2-schema-extension.config` file located in the `/repository/conf/` directory. {% endif %} - - For custom schema attributes, check the `type` meta attribute of the mapped local attribute. + - For custom schema attributes, check the `dataType` meta attribute of the mapped local attribute. ## Step 3: Build the payload