Identity Management
Identity Management in OneWelcome is supported in various ways. Most commonly used is the SCIM protocol.
SCIM has three supported versions: v1, v1.1 and v2 api versions.
The main difference between v1, v1.1 and v2 is that v2 introduced Attribute Value Metadata (urn:scim:schemas:extension:iwelcomeattributevaluemetadata:1.0) in the request and response.
Also, the v1 and v2 on getting multiple users List/Query Resources, it supports filtering by attributes unlike v1.1 which does not support. The v1 and v2 supports filter with body filter (we can send the filter attributes on body as post).
Example of filtering attributes on body:
{ "filter":"id co \"-\" and name.familyName co \"a\" or name.givenName eq \"givenNameExample\"", "count":10, "startIndex":1, "sortOrder":"ascending", "attributes":"emails,phoneNumbers"}Access to OneWelcome's SCIM API can be protected by using one of the following mechanisms:
- Basic authentication using username and password is should be avoided.
- OAuth2 bearer token (default).
- OAuth2 Fine-Grained bearer token with operation scope and SCIM schema specific scope.
The main difference between OAuth bearer token authorisation and basic authentication is that the basic authentication is not protected by any scope, it needs only username and password for accessing the API's.
When Basic Authentication is used, the client is authorised to use all the methods on the SCIM user endpoint.
When OAuth2 bearer tokens are used, the authorisations for the client can be limited and controlled by the OAuth scopes associated with the OAuth access token. The following scope values are used by the SCIM API:
SCIM:user:getAllows to retrieve user attributesSCIM:user:postAllows to create userSCIM:user:deleteAllows to delete userSCIM:user:putAllows to update user’s attributesSCIM:user:patchAllows to partially update user with the specified properties onlySCIM:user:queryAllow to get multiple users attributes`
When OAuth2 Fine-Grained is used for the request, we will be able to provide parts of SCIM schema based on provided scope. In order to view or change user attributes, you must have the OAuth2 scopes needed for the operation and scopes needed for that specific attribute’s schema.
Some examples:
eg1: To be able to see or change the emails (urn:scim:schema:core:1.0:emails) attribute, the access token must contain the urn:scim:schema:core:1.0scope.
eg2: To be able to see or change the gender (urn:scim:schemas:extension:iwelcome:1.0:gender) attribute, the access token must contain urn:scim:schemas:extension:iwelcome:1.0 scope.
In the following table there are the supported API versions, types of protection for every version, the path for accessing the resources and the link where can be found the api description for each type of authentication and authorisation.
| API Version | Protection | Description | Path | API description URL |
|---|---|---|---|---|
| V1.1 | Basic Authentication | The API will grant access only when it receives valid credentials. It is valid for all paths. | /scim/v1.1/Users | link |
| OAuth2 Scopes | The API will grant access only when it receives a valid access token which contains the needed scope to perform a specific operation (e.g SCIM:user:get, SCIM:user:POSTetc). | /scim/v1.1/Users | link | |
| OAuth2 Fine-Grained Scopes | The API will grant access only when it receives a valid access token containing the necessary scopes for doing certain actions on certain attributes (e.g SCIM:user:get, SCIM:user:POST, etc). The difference between OAuth2 Scopes and OAuth2 Fined-Grained Scopes protection is that the Fine-Grained Scopes offers the possibility to see parts of SCIM schema based on provided scope (e.g:urn:scim:schemas:extension:iwelcome:1.0, etc.). | /scim/v1.1/Users | link | |
| V1/V2 | Basic Authentication | The API will grant access only when it receives valid credentials. It is valid for all paths. | scim/(v1/v2)/Users | link |
| OAuth2 Scopes | The API will grant access only when it receives a valid access token which contains the needed scope to perform a specific operation (e.g SCIM:user:get, SCIM:user:POSTetc). | /scim/(v1/v2)/Users | link | |
| OAuth2 Fine-Grained Scopes | The API will grant access only when it receives a valid access token containing the necessary scopes for doing certain actions on certain attributes (e.g SCIM:user:get, SCIM:user:POST, etc). The difference between OAuth2 Scopes and OAuth2 Fined-Grained Scopes protection is that the Fine-Grained Scopes offers the possibility to see parts of SCIM schema based on provided scope (e.g:urn:scim:schemas:extension:iwelcome:1.0, etc.). | /scim/(v1|v2)/Users | link |
Notes:
The scope for filtering the requests based on segment is : "iwelcome:segment" + segmentName