Is it possible to assign Users to Groups on creation in SCIM?

Question

I currently have an application where users belong organizations within the app. When a user wants to add someone else to their team, they need to define a role (admin, developer, etc.) for the new user. It is also possible for some organizations to have child orgs, and in those cases it is possible to add multiple roles to a user per child org. It is important to note that in our current setup roles must be defined on user creation (you can't create a user with no roles). We are now developing a SCIM API for SSO support. My question is, is it possible to include that information on User create? Something like:

POST /Users

{
  "schemas": [...],
  "id": 123...,
  "groups": [
    {
      "value": org_id_1,
      "role": "admin",
    },
    {
      "value": org_id_2,
      "role": "support",
    },
    ...,
  ],
}

And then this would add the roles appropriately.

Answer 1

I would base a solution on the SCIM 2.0 Core Schema from RFC 6743. By default a user request payload where the user is assigned roles might look like this:

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "janedoe",
    "name": {
        "givenName": "Jane",
        "familyName": "Doe"
    },
    "emails": [
        {
            "value": "[email protected]",
            "primary": true
        }
    ],
    "roles": [
        {
            "value": "users"
        },
        {
            "value": "superusers",
            "primary": true
        }
    ]
}

The Full User Representation Example provides a more complex groups example.

A good general approach is to follow the spec where you can, but the schema is meant to be extensible. So introduce your own field names or data shapes when the standard schema does not meet your needs. Perhaps give these names like product_groups.

A SCIM 2.0 API should be provided out of the box if using OAuth 2.0 and an authorization server (AS). In your case you are acting as an AS and also dealing with multi-tenancy. In a real AS, calling such an API might require an access token with an accounts scope and a tenant_id claim.

Answer 2

It is possible to create a user and assign groups in a single HTTP request, but not via the /Users endpoint. Instead, you should use (implement) the /Bulk endpoint. According to RFC7643, it is not allowed to include group memberships when creating users via the /Users endpoint.

Since this attribute has a mutability of "readOnly", group membership changes MUST be applied via the "Group" Resource (Section 4.2). This attribute has a mutability of "readOnly".

SCIM Playground provides an example for creating users and immediately assigning group memberships using the /Bulk endpoint. It shows the following request.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:BulkRequest"
    ],
    "Operations": [
        {
            "method": "POST",
            "path": "/Users",
            "bulkId": "sdoe",
            "data": {
                "schemas": [
                    "urn:ietf:params:scim:schemas:core:2.0:User"
                ],
                "externalId": "sdoe",
                "name": {
                    "formatted": "Mrs. Sandra Doe",
                    "familyName": "Doe",
                    "givenName": "Sandra"
                },
                "emails": [
                    {
                        "value": "[email protected]"
                    }
                ],
                "userName": "sdoe"
            }
        },
        {
            "method": "PATCH",
            "path": "/Groups/00000000-0000-0000-0000-000000000008",
            "data": {
                "schemas": [
                    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
                ],
                "Operations": [
                    {
                        "op": "add",
                        "path": "members",
                        "value": [
                            {
                                "value": "bulkId:sdoe"
                            }
                        ]
                    }
                ]
            }
        }
    ]
}