Docs for SCIM2 Build User Creation Payload

en/asgardeo/docs/apis/scim2/build-scim2-user-creation-payload.md

@@ -0,0 +1 @@
+{% include "../../../../includes/apis/scim2/build-scim2-user-creation-payload.md" %}

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/)
+- [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/)

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

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" %}

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/)
+- [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/).

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

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": "[email protected]",
+              "primary": true
+            },
+            {
+              "type": "work",
+              "value": "[email protected]"
+            }
+          ]
+        }
+        ```
+
+!!! 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 `<IS_HOME>/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": "[email protected]",
+          "primary": true
+        },
+        {
+          "type": "work",
+          "value": "[email protected]"
+        }
+      ]
+    }
+    ```
+
+### 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": "[email protected]",
+     "primary": true
+   },
+   {
+     "type": "work",
+     "value": "[email protected]"
+   }
+ ],
+ "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"]
+ }
+}
+```