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 a 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 to 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 join 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.
GroupType
UserType
GroupUser
RoleAccount
Host
MailDomain
MailList
DomainValue
VaultFolder
System
CustomObject
TaskInstance
ProcessInstance
ProcessDefinition

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: