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 ac8c850bf9..bf68f317a5 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: @@ -122,6 +127,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 +424,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..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 @@ -8,4 +8,6 @@ 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/) + +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 77d8954748..f41a87cded 100644 --- a/en/identity-server/7.0.0/mkdocs.yml +++ b/en/identity-server/7.0.0/mkdocs.yml @@ -321,6 +321,7 @@ 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' @@ -791,6 +792,8 @@ 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 + - 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 new file mode 100644 index 0000000000..30ba43dce7 --- /dev/null +++ b/en/includes/apis/scim2/build-scim2-user-creation-payload.md @@ -0,0 +1,244 @@ +# 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. + +## Step 1 : Determine the associated schema + +{{product_name}} maps user attributes to the following SCIM 2.0 schemas: + +- 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. + +!!! 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). + +For a user attribute, + +- 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" + } + ``` + +- If it is mapped to **Enterprise Schema** or **Custom Schema**, it needs to be placed under the namespace of the corresponding schema. + + + ```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 + +Each SCIM attribute belongs to one of the following types, which determine how the attribute is formatted in the payload. + + +- **Single-valued Attributes** contain a single value. + + - **Simple Attributes** contain a single attribute. + + ```json + { + "userName": "kim" + } + ``` + + + - **Complex Attributes** contain multiple sub-attributes. + + ```json + { + "name": { + "givenName": "Kim", + "familyName": "Berry" + } + } + ``` + +- **Multi-Valued Attributes** hold multiple values + + - **Simple Attributes** contain a single attribute. + + ```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 `dataType` 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 + + ```json + { + "userName": "kim" + } + ``` + + + - Single-valued complex attributes. + + ```json + { + "name": { + "givenName": "Kim", + "familyName": "Berry" + } + } + ``` + +- Multi-Valued complex attributes + + !!! note + + By default, core schema, user schema, and enterprise schema do not have multi-valued simple attributes. + + ```json + { + "emails": [ + { + "value": "kim@gmail.com", + "primary": true + }, + { + "type": "work", + "value": "kim@wso2.com" + } + ] + } + ``` + +### 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. + +- Single-valued simple attributes + + ```json + { + "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": + "employeeNumber": "1234A" + } + ``` + +- Single-valued complex attributes. + + ```json + { + "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": + "manager": { + "value": "Taylor", + "displayName": "Taylor Smith" + } + } + ``` + +- Multi-valued simple attributes + + + ```json + { + "urn:scim:wso2:schema": + "devices": ["d1", "d2"] + } + ``` + +## 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": [ + { + "value": "kim@gmail.com", + "primary": true + }, + { + "type": "work", + "value": "kim@wso2.com" + } + ], + "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"] + } +} +```