How to use SCIM in Soffid
Introduction
Soffid has implemented a version of the SCIM protocol 2.0, only the basic features have been included. Some optional recommendations have also been included to improve the usage of this specification within the Soffid context.
This functionality is available only by installing the SCIM add-on. This add-on is available in the download section of the Soffid website. Please, see the following link: How to use SCIM in Soffid
Service provider config
&&TODO&&&
- GET /ServiceProviderConfig
Specification compliance, authentication schemes, data models.
- GET /ResourceTypes
An endpoint used to discover the types of resources available.
- GET /Schemas
Introspect resources and attribute extensions.
Soffid provides a REST web service that shows all the Soffid capacities
https://<your-domain>/soffid/webservice/scim2/v1/ServiceProviderConfig
Resources -> Ahora hay 20 resources
&&TODO&&&
List resources types
The SCIM protocol is focused on resource management, such as a users, groups, accounts, etc. To know all the resources that Soffid provides there is a REST web service:
https://<your-domain>/soffid/webservice/scim2/v1/ResourceTypes
Query resource type
http://<your-domain>/soffid/webservice/scim2/v1/ResourceTypes/<Resource>
Soffid provides the following resources:
Resource |
Description |
---|---|
User |
Management of the users included in the Soffid solution. A user is an identity that represents only one person. |
Group |
Management of the groups included in the Soffid solution. A group could be part of a hierarchical group tree. Users are assigned to a primary group but optionally could be in some secondary groups. |
Account |
Management of the accounts included in the Soffid solution. An account is a representation of an application access. A user may have a lot of accounts and may have some accounts for the same applications with different roles and restrictions. |
Application (addon version 1.2.0+) |
Management of the applications included in the Soffid solution. An application is a concept on gather and joins different roles and agents in a same conceptual place. Every agent (of an external system) manages these roles through one or more applications. By default, an application with the same name of an agent is created. |
Role (addon version 1.2.0+) |
Management of the role included in the Soffid solution. Every role is created in one application, so an application has a list of roles. The roles are granted to users through account. |
The resources are published as a REST web service, one may access them using the following URLs:
https://<your-domain>/soffid/webservice/scim/User
https://<your-domain>/soffid/webservice/scim/Group
https://<your-domain>/soffid/webservice/scim/Account
https://<your-domain>/soffid/webservice/scim/Application
https://<your-domain>/soffid/webservice/scim/Role
To use these URLs, please replace "<your-domain>" by the domain of your Soffid solution.
In SCIM all resources must be in uppercase (/User), the lowercase implementation is not provided.
Operations
For every resource the following operations are available:
Operation |
HTTP method |
URL example |
Description |
---|---|---|---|
List all |
GET |
.../soffid/webservice/scim/<resource> |
List all resources |
Search by id |
GET |
.../soffid/webservice/scim/<resource>/<id> |
Search the resource with the <id> specified |
Search by filter |
GET |
.../soffid/webservice/scim/<resource>?filter=<filter-language> |
Search all resources that fulfil the <filter-language> filter (please see filtering language here 5. SCIM filter language) |
Create |
POST |
.../soffid/webservice/scim/<resource> |
Create a resource |
Update all |
PUT |
.../soffid/webservice/scim/<resource>/<id> + <JSON in the body> |
Update all attributes specified in the JSON stream (the attributes not included will be cleared) |
Update partial |
PATCH |
.../soffid/webservice/scim/<resource>/<id> + <JSON in the body> |
Update only the attributes specified in the JSON stream (the other attributes will not be updated) |
Delete |
DELETE |
.../soffid/webservice/scim/<resource>/<id> |
Delete a resource |
HTTP request
In every HTTP request the following HTTP header parameters are required:
Parameter
|
Value
|
Description
|
---|---|---|
URL | https://<your-domain>/soffid/webservice/scim/<resource> | URL with the <resource> to be managed |
Method | [ GET | POST | PUT | PATCH | DELETE ] | Method allowed in SCIM REST protocol |
Content-Type | application/scim+json | SCIM specification |
Accept | application/scim+json | SCIM specification |
Authorization | Basic YWRtaW46Y2hhbmdlaXQ= | Only BASIC authentication is implemented in this version. A Soffid user (+password) with SCIM access is required to generate this parameter |
Accept-Language | [ EN | ES | CA | NL ] | This parameter is OPTIONAL. The default language is EN |
HTTP codes
The following HTTP codes are managed in the HTTP response:
Code |
Status |
User case |
---|---|---|
200 |
Ok |
After: list all, search by id, search by filter, update all, update partial |
201 |
Created |
After: create |
204 |
No content |
After: delete |
404 |
Not found |
After: resource not found |
500 |
Error |
After: internal error, PATCH DELETE |