SCIM Connector Key Features

Feature

Changed on:

17 Oct 2023

Overview

Provisioning a user
App Role Convention
Scenarios

Detailed Technical Description

Provisioning a user

New users will be created with roles in Fluent if they are new in Fluent, and all their roles in IDP have respective roles in Fluent.
New users won’t be created in Fluent if they have no roles in IDP or the service finds no respective roles.
Existing users will be updated with roles in Fluent if all their roles in IDP have respective roles in Fluent.
Existing users won’t be updated in Fluent if the service finds no respective roles.
IDP acts as the master source of roles either via direct assignment or via indirect assignment using logical app role.
Along with roles, user information in IDP will also be updated in Fluent.
Deactivating a user in IDP will hide all user roles in Fluent, and the user status will be set to
```
`Inactive`
```
. Reactivating the user will resume the user’s roles in Fluent.
Deleting a user in IDP will deactivate the user in Fluent.
User that has no roles will be set
```
`Inactive`
```
automatically in Fluent.

Provisioning a user in group(s):

User Group is used in IDPs for the following scenarios:

Adding a user to a group will give the user all group roles besides the directly assigned ones.
Removing a user from a group will remove the roles of the group from the user, except for the roles assigned directly to the user. E.g., Role D is assigned directly to user X, and X is the member of a group with role D; when user X is removed from the group, role D is still assigned to X.
In case a group gets updated, such as roles and members, all the changes must reflect on the group members except the roles assigned directly to the user.
If the group has a role added, all members will get this role assigned during the provisioning cycle.
If the group has a member added, that member will get all the roles assigned to the group.
If the group gets a role removed, all members will get the role removed.
If the group gets a member removed, all roles of the group will be removed from the member.
Deleting a group will also remove the roles of the group from all members except those assigned directly to the user.

App Role Convention

To provision a user successfully, besides the user information, the roles set in IDP need to follow the specific convention:

App role setting in IDP convention:

<FLUENT_CONTEXT_TYPE>_<FLUENT_CONTEXT_ID>_<FLUENT_ROLE_ID or IDP_LOGICAL_ROLE_ID> where:

<FLUENT_CONTEXT_TYPE> is a Fluent user context type ( supported types: ACCOUNT, RETAILER, AGENT)
<FLUENT_CONTEXT_ID> is a Fluent user context type identifier (e.g. if the type is RETAILER, then the context Id would be the retailer id; if the type is AGENT then the context id would be the “location id”; if the type is ACCOUNT, then the Context Id would be the Account Id.)
<FLUENT_ROLE_ID or IDP_LOGICAL_ROLE_ID>
- FLUENT_ROLE_ID is the Fluent role value
- IDP_LOGICAL_ROLE_ID is an app role defined in IDP, which is configured to be translated into a list of Fluent roles

Example of App roles assigned to user and group in Azure Active Directory

Dynamic Role Mapping

As written above, there is also a possibility to convert a role defined in IDP to a list of roles in Fluent. For example, role A, defined in IDP App roles, has been configured to map with B, and C roles in Fluent, so if a user is assigned role A in IDP and is provisioned, then the user will be assigned to role B, C in Fluent. The configuration is maintained in Fluent (not in IDP).

Dynamic mapping is always executed before the direct mapping to convert custom roles into Fluent roles and then have the direct mapping take care of the provisioning.

The mapping configuration needs to be stored as Fluent Settings with the key

`fc.connect.scim-connector.provisioning.pipeline.config`

in a JSON type. It consists of a collection of

`rules`

where each rule combines a condition and an action, with the first being optional.

If no configuration is stored at Fluent, then the SCIM connector will assume no dynamic mapping rules and only the direct mapping will be executed.

Disclaimer

SCIM connector developed by the Fluent team is tested only on Azure Active Directory.
SCIM connector does not support group provisioning as there is no group concept (group of users) in the Fluent Commerce platform. So, technically, no group endpoints adhere to the SCIM protocol developed as part of this service.
SCIM Connector supports the essential functions of provisioning users that can adapt to user management and assigning roles to user functions in Fluent Commerce. However, some IDPs have specific functions for the provisioning user; therefore, we don’t guarantee this service works well on all functions served for the provisioning user in an IDP. Such as:
- Provisioning a group in Azure Active Directory on demand does not work with SCIM Service.
- Deactivating or reactivating a group
- Revoke deleted users in Azure Active Directory has not been tested yet.

Scenarios

Background

An IDP role “X” can be configured in IDP to work in two ways:

It can have the same name as the Fluent role, so it is a direct mapping.
It can be a logical name assigned to many Fluent roles whose mapping is managed in Fluent.

Provisioning

No	At IDP	At Fluent (after the provisioning job is run)
1	a new user is created without a role	user is not created in Fluent
2	a new user is assigned to D	user is created in Fluent with role D
3	a new user is assigned to C	user is created in Fluent with roles F, G
4	a new user is assigned to C, D	user is created in Fluent with roles D, F, G
5	a new user is assigned to A, B	user is not created due to not finding respective roles of A and B in Fluent
6	a new user is assigned to A, B, C	user is not created due to not finding respective roles of A and B in Fluent
7	a new user is assigned to A, B, C, D	user is not created due to not finding respective roles of A and B in Fluent
8	a new user is assigned to A, B, C, D, E, And he is added to Group G	user is not created in Fluent due to not finding respective roles of A and B in Fluent
9	the existing user is assigned to A, B	user got no change in Fluent
10	the existing user is assigned to A, B, C, D	user got no changes in Fluent
11	the existing user is assigned to C, D	user is updated in Fluent with roles D, F, G
12	the existing user is assigned to C and D and is added to Group G	user is updated in Fluent with roles D, F, G, M, N
13	the existing user is assigned to C, D, and M and is added to Group G	user is updated in Fluent with roles D, F, G, M, N
14	the existing user is assigned to C, D, M And he is a member of Group G And he is removed from group G	user is updated in Fluent with roles D, F, G, M
15	the existing user is assigned to C, D, M and And he is a member of Group G AND role M is removed from group G	user is updated in Fluent with roles D, F, G, M, N
16	the existing user is assigned to D, M And he is a member of Group G AND role C is added to group G	user is updated in Fluent with roles D, F, G, M, N
17	the existing user is assigned to Group H	user got no change in Fluent

Validation and Error Handling

The error message follows the standard defined in RFC 7644: System for Cross-domain Identity Management: Protocol.

Error Messages can be viewable in IDP UI or in Cloudwatch.

Example:

1{
2    "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
3    "scimType":"mutability",
4    "detail":"Attribute 'id' is readOnly",
5    "status": "400"
6}

Language: json

Name: Code Example

Description:

[Warning: empty required content area]

Error messages:

No	Context	Status	Scimtype	Detail	Example
1	wrong contextId	400	roleInvalidContextId	Invalid context id, unable to find a match [{contextType - contextID}]	`{` `"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],` `"status": "400",` `"scimType": "roleInvalidContextId",` `"detail": "Invalid context id, unable to find a match [RETAILER-1000]"` `}`
2	wrong contextType	400	roleInvalidContextType	Invalid context type, unable to find a match [{contextType}]	`{` `"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],` `"status": "400",` `"scimType": "roleInvalidContextType",` `"detail": "Invalid context type, unable to find a match [CONTEXTWRONG]"` `}`
3	wrong role	400	invalidValue	Unable to find a matching Fluent role [{role}]	`{` `"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],` `"status": "400",` `"scimType": "roleInvalid",` `"detail": "Unable to find a matching Fluent role [WRONGROLE]"` `}`
4	wrong app role convention	400	roleNameConvention	Role does’t match the expected naming convention [{appRole}]	`{` `"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],` `"status": "400",` `"scimType": "roleNameConvention",` `"detail": "Role does’t match the expected naming convention [CONTEXT-WRONG_1_SUPER_ADMIN_USER]"` `}`
5	SCIM endpoint Fluent does not support	501		Not Implemented	`{` `"schemas": [ "urn:ietf:params:scim:api:messages:2.0:Error" ],` `"status": "501", ` `"detail": "Not Implemented" ` `}`