How to use SCIM in Soffid

Introduction

Soffid has implemented a version of the SCIM protocol 2.0. 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. 

Discovery

Soffid provides some endpoints to discover supported features and specific attribute details:

Service provider config

This endpoint provides additional information about the Soffid SCIM implementation.

Request

GET https://<your-domain>/soffid/webservice/scim2/v1/ServiceProviderConfig

Response 200 OK

{
    "patch": {
        "supported": true
    },
    "filter": {
        "maxResults": 1000,
        "supported": true
    },
    "documentationUri": "https://bookstack.soffid.com/books/scim",
    "authenticationSchemes": [
        {
            "documentationUri": "https://bookstack.soffid.com/book/scim",
            "name": "HTTP Basic",
            "description": "Authentication scheme using the HTTP Basic Standard",
            "specUri": "http://www.rfc-editor.org/info/rfc2617",
            "type": "httpbasic"
        }
    ],
    "meta": {
        "location": "http://soffid.pat.lab:8080/webservice/scim2/v1/ServiceProvider",
        "resourceType": "ServiceProviderConfig"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
    ],
    "etag": {
        "supported": false
    },
    "sort": {
        "supported": true
    },
    "bulk": {
        "supported": false
    },
    "changePassword": {
        "supported": true
    }
}

Resources Types

An endpoint used to discover the types of resources available.

List resources types

The SCIM protocol is focused on resource management, such as users, groups, accounts, etc. To know all the resources  that Soffid provides you can use this REST web service: 

Request

GET https://<your-domain>/soffid/webservice/scim2/v1/ResourceTypes

Response 200 OK

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 20,
    "startIndex": 1,
    "Resources": [
        {
            "schema": "urn:soffid:com.soffid.iam.api.Account",
            "endpoint": "http://soffid.pat.lab:8080/webservice/scim2/v1/Account",
            "meta": {
                "location": "http://soffid.pat.lab:8080/webservice/scim2/v1/ResourceTypes/Account",
                "resourceType": "ResourceType"
            },
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
            ],
            "name": "Account",
            "description": "Account object",
            "id": "Account"
        },
        {
            "schema": "urn:soffid:com.soffid.iam.api.Group",
            "endpoint": "http://soffid.pat.lab:8080/webservice/scim2/v1/Group",
            "meta": {
                "location": "http://soffid.pat.lab:8080/webservice/scim2/v1/ResourceTypes/Group",
                "resourceType": "ResourceType"
            },
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
            ],
            "name": "Group",
            "description": "Group object",
            "id": "Group"
        },
      ...............
      ]
}

Query resource type

To query a specific resource type, you can use this REST web service:

Request

GET http://<your-domain>/soffid/webservice/scim2/v1/ResourceTypes/{Resource}

Example

GET http://<your-domain>/webservice/scim2/v1/ResourceTypes/User

Response 200 OK

{
    "schema": "urn:soffid:com.soffid.iam.api.User",
    "endpoint": "http://soffid.pat.lab:8080/webservice/scim2/v1/User",
    "meta": {
        "location": "http://soffid.pat.lab:8080/webservice/scim2/v1/ResourceTypes/User",
        "resourceType": "ResourceType"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
    ],
    "name": "User",
    "description": "User object",
    "id": "User"
}

Response 404

404 Not Found

Schemas

Schema definition for a specific resource.

Request

GET http://<your-domain>/soffid/webservice/scim2/v1/Schemas/{Schema_URL}

Example

GET http://<your-domain>/soffid/webservice/scim2/v1/Schemas/urn:soffid:com.soffid.iam.api.Role

Response 200 OK

{
    "meta": {
        "location": "http://soffid.pat.lab:8080/webservice/scim2/v1/Schemas/urn:soffid:com.soffid.iam.api.Role",
        "resourceType": "Schema"
    },
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Schema"
    ],
    "name": "Role",
    "description": "Role object",
    "attributes": [
        {
            "uniqueness": "none",
            "name": "name",
            "mutability": "readWrite",
            "type": "string",
            "caseExact": true,
            "returned": "default",
            "multiValued": false,
            "required": true
        },
        {
            "uniqueness": "none",
            "name": "description",
            "mutability": "readWrite",
            "type": "string",
            "caseExact": true,
            "returned": "default",
            "multiValued": false,
            "required": true
        },
        {
            "uniqueness": "none",
            "name": "system",
            "mutability": "readWrite",
            "type": "string",
            "caseExact": true,
            "returned": "default",
            "multiValued": false,
            "required": true
        },
        {
            "uniqueness": "none",
            "name": "category",
            "mutability": "readWrite",
            "type": "string",
            "caseExact": true,
            "returned": "default",
            "multiValued": false,
            "required": false
        },
        {
            "uniqueness": "none",
            "name": "informationSystemName",
            "mutability": "readWrite",
            "type": "string",
            "caseExact": true,
            "returned": "default",
            "multiValued": false,
            "required": true
        },
        {
            "uniqueness": "none",
            "name": "domain",
            "mutability": "readWrite",
            "type": "string",
            "caseExact": true,
            "returned": "default",
            "multiValued": false,
            "required": false
        },
        {
            "uniqueness": "none",
            "name": "bpmEnabled",
            "mutability": "readWrite",
            "type": "boolean",
            "caseExact": true,
            "returned": "default",
            "multiValued": false,
            "required": false
        },
        {
            "uniqueness": "none",
            "name": "approvalStart",
            "mutability": "readOnly",
            "type": "dateTime",
            "caseExact": true,
            "returned": "default",
            "multiValued": false,
            "required": false
        },
        {
            "uniqueness": "none",
            "name": "approvalEnd",
            "mutability": "readOnly",
            "type": "dateTime",
            "caseExact": true,
            "returned": "default",
            "multiValued": false,
            "required": false
        }
    ],
    "id": "urn:soffid:com.soffid.iam.api.Role"
}

Response 404

404 Not Found

Soffid Resources

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 and optionally could be in some secondary groups.
Account	Management of the accounts included in the Soffid solution. An account is a representation of one 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 (Information Systems) included in the Soffid solution. An application is a way of gather and joins different roles and agents in the 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 as an agent is created.
Role (addon version 1.2.0+)	Management of the roles included in the Soffid solution.  Every role is created in one application, so an application has a list of roles.
GroupType	Management of the GroupTypes included in the Soffid solution.
UserType	Management of the GroupTypes included in the Soffid solution.
GroupUser	Management of the GroupUsers included in the Soffid solution.
RoleAccount	Management of the RoleAccounts included in the Soffid solution.
Host	Management of the Hosts included in the Soffid solution.
MailDomain	Management of the MailDomains included in the Soffid solution.
MailList	Management of the MailLists included in the Soffid solution.
DomainValue	Management of the DomainValues included in the Soffid solution.
VaultFolder	Management of the VaultFolders included in the Soffid solution.
System	Management of the Systems included in the Soffid solution.  Agent
CustomObject	Management of the CustomObjects included in the Soffid solution.
TaskInstance	Management of the TaskInstances included in the Soffid solution.
ProcessInstance	Management of the ProcessInstances included in the Soffid solution.
ProcessDefinition	Management of the ProcessDefinition included in the Soffid solution.

You can view all resource data models and schemas on Resource data model & schema chapter

Soffid Operations

For every resource the following operations are available:

HTTP request

In every HTTP request the following HTTP header parameters are required:

HTTP codes

The following HTTP codes are managed in the HTTP response: