SCIM User Guide

Overview

The OptimalCloud offers administrators a complete user management system that includes a robust Delegated Administrative Identity Management system. In addition to the web-based user interface, the OptimalCloud offers a RESTful frontend which can be leveraged by custom applications and scripts. JSON is used as the standard data interchange format for SCIM.

Below are some helpful documents explaining the technology associated with SCIM:


Industry Terminology

Term Description
SCIM System for Cross-domain Identity management
REST REpresentational State Transfer web service
JSON JavaScript Object Notation (JSON)


OptimalCloud Terminology

Term Description
Organization Type An Organization Type is used to categorize Organizations with in the OptimalCloud. Organization Types allow Organizations with similar business needs to be group together for management purposes. An example of an Organization Type would be “licensee” or “grocer”.
Global Administrator Global Administrator is a role assigned to an administrator who has elevated global rights to the OptimalCloud. This role maps to the OptimalCloud role of GLOBAL_ADMIN.
Tenant Administrator Tenat Administrator is a role assigned to an administrator who has elevated rights to the OptimalCloud tenant. This role maps to the OptimalCloud role of TENANT_ADMIN.
Organization Administrator Organization Administrator is a role given to a user who is designated to have management rights over a collection of Organizations. This role maps to the OptimalCloud role of DEL_ADMIN.
Application Administrator Application Administrator is a role given to a user who is designated to have management rights over a collection of Applications. This role maps to the OptimalCloud role of ENTITLEMENT_ADMIN.


The OptimalCloud SCIM Overview

The goal of the OptimalCloud SCIM service is to adhere as closely as possible to the currently proposed SCIM standard, which can be found at SCIM RFC 7644 . The SCIM standard provides straightforward methods to create, read, update and delete common organizational objects, via both single and batch transactions.

The OptimalCloud has extended the standard SCIM Schema to include business objects related to OptimalCloud deployments (e.g. Organizations, Entitlements, etc.). Additionally the OptimalCloud’s implementation of SCIM allows the SCIM Schema to be extended further to meet clients’ business requirements.

Please Note:

All of the examples below are using the sample URL: https://ofis.theoptimalcloud.com/scim/api/v2.0/. This will not be the URL for your particular deployment. Please get your deployment details from your deployment team.


Configuration

The OptimalCloud SCIM service relies with the configuration of the OptimalCloud.

Attribute ACL

Through the use of the OptimalCloud Attribute ACLs and administrator can determine what attributes on the OptimalCloud objects are visible through the SCIM service and which OptimalCloud Role has access (Read or Write) to the attribute.

Since the SCIM Schema is based on the OptimalCloud Attribute ACLs, each OptimalCloud Role may be assigned a unique SCIM Schema.

SCIM Attributes

The SCIM attribute associated with each OptimalCloud attribute is configured via the OptimalCloud’s Identity Provider configuration for the OptimalCloud SCIM service. There are default attributes assigned to standard SCIM values. For example, the SCIM attribute “urn:ietf:params:scim:schemas:core:2.0:User:name.givenName” is assigned to OptimalCloud user attribute “giveName” by default. These default assignments can be overwritten through an explicit assignment in the OptimalCloud’s Identity Provider configuration.

Please Note:

In order for an attribute to be available through the OptimalCloud SCIM service, it MUST be defined in the Attribute ACLs as well as defined as a claim in the SCIM Identity Provider configuration.


SCIM Authentication and Authorization

The OptimalCloud SCIM service leverages the standard authentication and authorization mechanisms provided by the OptimalCloud.

Authentication

The OptimalCloud SCIM service supports the OAuth Resource Owner Password grant provided by the OptimalCloud. Once the client receives the access token, he must then present it as a bearer token in the Authorization header of each SCIM RESTful request.

GET /scim/api/v2.0/ HTTP/1.1
Host: ofis.theoptimalcloud.com
Authorization: Bearer uDgJm4i9yb22WBqYs7Vw3nZ2QUf7UcrScDgoBwjrcx9uuK0cvwn8Ni

There are multiple ways to obtain a Bearer Token for use with the SCIM service. Those options are listed below:

  1. Make an active call to the token endpoint (listed in the OIDC Discovery data) using the Resource Owner Password Grant, passing a user or service account credentials. The OAuth2 access token is returned which can be used as a bearer token in SCIM.

  2. Perform one of the federation grants (Access Code Grant, Implicit Grant, or Hybrid Grant) and use the return OAuth2 access token as a SCIM bearer token.

  3. Use either method one or two be get back an OAuth2 Refresh Token. The Refresh token can be used by a SCIM client to get a new OAuth Access Token when needed.

  4. An API Key may be used as a Bearer Token.

    To create an API key go to the API Key Manager on the Administration tab. Create a new API Key and select the SCIM API option. For more information on how to create an API Key see the API Key Manager section of the help documentation.

Authorization

Authorization rules can be adjusted to meet client needs. Through OptimalCloud configuration, the client can control what accounts have front door access to the Optimal SCIM service. Furthermore, access can also be controlled at a more granular, or attribute, level through the use of OptimalCloud Roles and their associated access control lists (ACL).


SCIM Endpoints

The OptimalCloud SCIM service provides several endpoints which allow developers to view and modify data residing in the OptimalCloud.


Service Provider Config Endpoint

The Service Provider Config endpoint allows clients to examine the capabilities of the OptimalCloud SCIM service.

GET /scim/api/v2.0/ServiceProviderConfig/ HTTP/1.1

Host: ofis.theoptimalcloud.com

Response Body:

{
    "patch": {
        "supported": true
    },
    "bulk": {
        "maxOperations": 1000,
        "maxPayloadSize": 1000000,
        "supported": false
    },
    "filter": {
        "maxResults": 100,
        "supported": true
    },
    "changePassword": {
        "supported": true
    },
    "sort": {
        "supported": false
    },
    "etag": {
        "supported": false
    },
    "authenticationSchemes": [
        {
            "type": "oauth2",
            "name": "OAuth2",
            "description": "Authentication scheme using the OAuth2 Standard",
            "specUri": "http://www.rfc-editor.org/info/rfc6749"
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
    ]
}


Resource Types Endpoint

The Resource Types endpoint allows clients to examine the list of business objects types which can be managed through the OptimalCloud SCIM service.

GET /scim/api/v2.0/ResourceTypes/ HTTP/1.1

Host: ofis.theoptimalcloud.com

Response Body:

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 4,
    "Resources": [
        {
            "name": "User",
            "description": "User Account",
            "endpoint": "/Users",
            "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
            ],
            "schemaExtensions": [
                {
                    "schema": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
                    "required": false
                },
                {
                    "schema": "urn:ietf:params:scim:schemas:extension:optimalcloud:2.0:User",
                    "required": false
                }
            ],
            "id": "User",
            "meta": {
                "resourceType": "ResourceType",
                "location": "https://ofis.theoptimalcloud.com/scim/api/v2.0/ResourceTypes/User"
            }
        },
        {
            "name": "Group",
            "description": "Group Object",
            "endpoint": "/Groups",
            "schema": "urn:ietf:params:scim:schemas:core:2.0:Group",
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
            ],
            "schemaExtensions": [
                {
                    "schema": "urn:ietf:params:scim:schemas:extension:optimalcloud:2.0:Group",
                    "required": false
                }
            ],
            "id": "Group",
            "meta": {
                "resourceType": "ResourceType",
                "location": "https://ofis.theoptimalcloud.com/scim/api/v2.0/ResourceTypes/Group"
            }
        },
        {
            "name": "Organization",
            "description": "OptimalCloud Organization Object",
            "endpoint": "/Organizations",
            "schema": "urn:ietf:params:scim:schemas:extension:optimalcloud:2.0:Organization",
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
            ],
            "id": "Organization",
            "meta": {
                "resourceType": "ResourceType",
                "location": "https://ofis.theoptimalcloud.com/scim/api/v2.0/ResourceTypes/Organization"
            }
        },
        {
            "name": "Entitlement",
            "description": "OptimalCloud Entitlement Object",
            "endpoint": "/Entitlements",
            "schema": "urn:ietf:params:scim:schemas:extension:optimalcloud:2.0:Entitlement",
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:ResourceType"
            ],
            "id": "Entitlement",
            "meta": {
                "resourceType": "ResourceType",
                "location": "https://ofis.theoptimalcloud.com/scim/api/v2.0/ResourceTypes/Entitlement"
            }
        }
    ]
}


Schemas Endpoint

The Schemas endpoint allows clients to examine the currently configured schema of the OptimalCloud SCIM service. It should be noted that the schema may appear differently based on the Role of the user requesting the schema and its associated ACLs. The Response will return an Attribute definition for each Attribute in the Schema.

GET /scim/api/v2.0/Schemas/ HTTP/1.1

Host: ofis.theoptimalcloud.com

Response Body:

{
    "name": "Optimal Cloud Entitlement",
    "description": "Optimal Cloud Entitlement Attribtues",
    "attributes": [
        {
            "name": "displayName",
            "type": "string",
            "description": "A human-readable name for the Entitlement.",
            "multiValued": false,
            "required": true,
            "caseExact": false,
            "mutability": "readWrite",
            "returned": "default",
            "uniqueness": "server"
        },
        {
            "name": "description",
            "type": "string",
            "description": "A description of the Entitlement.",
            "multiValued": false,
            "required": true,
            "caseExact": false,
            "mutability": "readWrite",
            "returned": "default",
            "uniqueness": "server"
        },
        {
            "name": "minimumAuthLevel",
            "type": "string",
            "description": "The minimum authentical level required to access Entitlement.",
            "multiValued": false,
            "required": true,
            "caseExact": false,
            "mutability": "readWrite",
            "returned": "default",
            "uniqueness": "server"
        },
    ],
    "id": "urn:ietf:params:scim:schemas:extension:optimalcloud:2.0:Entitlement",
    "meta": {
        "resourceType": "Schema",
        "location": "https://ofis.theoptimalcloud.com/scim/api/v2.0/Schemas/urn:ietf:params:scim:schemas:extension:optimalcloud:2.0:Entitlement"
    }
}


Users Endpoint

The Users endpoint is used to manage OptimalCloud Users.

GET /scim/api/v2.0/Users/ HTTP/1.1

Host: ofis.theoptimalcloud.com

Response Body:

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1,
    "Resources": [
        {
            "userName": "awilliams@smart.com",
            "name": {
                "familyName": "Williams",
                "givenName": "Ash"
            },
            "displayName": "Ash Williams",
            "active": true,
            "emails": [
                {
                    "type": "work",
                    "primary": true,
                    "value": "awilliams@smart.com"
                }
            ],
            "id": "03C6CAF2-8543-46C5-B15F-1140A0F6FB60",
            "meta": {
                "resourceType": "User",
                "created": "2016-05-17T16:02:17.000Z",
                "lastModified": "2016-05-17T16:02:17.000Z",
                "location": "https://ofis.theoptimalcloud.com/scim/api/v2.0/Users/03C6CAF2-8543-46C5-B15F-1140A0F6FB60"
            },
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ]
        }
   ]
}


Groups Endpoint

The Groups endpoint is used to manage OptimalCloud Groups.

GET /scim/api/v2.0/Groups/ HTTP/1.1

Host: ofis.theoptimalcloud.com

Response Body:

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1,
    "Resources": [
        {
            "displayName": "S-Mart Employee",
            "members": [
                {
                    "display": "Ash Williams",
                    "value": "BE324F48-E643-4E37-BDDE-91D40AD23C3A",
                    "$ref": "https://ofis.theoptimalcloud.com/scim/api/v2.0/Users/BE324F48-E643-4E37-BDDE-91D40AD23C3A"
                },
                {
                    "display": "Pablo Simon Bolivar",
                    "value": "3BA6DF2D-39DE-4535-B96A-A74053D77264",
                    "$ref": "https://ofis.theoptimalcloud.com/scim/api/v2.0/Users/3BA6DF2D-39DE-4535-B96A-A74053D77264"
                },
                {
                    "display": "Kelly Maxwell",
                    "value": "F7DBA961-0025-48DC-9E64-4090F76918B3",
                    "$ref": "https://ofis.theoptimalcloud.com/scim/api/v2.0/Users/F7DBA961-0025-48DC-9E64-4090F76918B3"
                }
             ]
          }
      ]
}


Organizations Endpoint

The Organizations endpoint is used to manage OptimalCloud Organizations.

GET /scim/api/v2.0/Organizations/ HTTP/1.1

Host: ofis.theoptimalcloud.com

Response Body:

{
    "schemas": “urn:ietf:params:scim:api:messages:2.0:ListResponse”,
    "totalResults": 1,
    "Resources": [
        {
            "id": "90A56861-6BE7-4401-A5A5-1AD1E1DCB579",
            "meta": {
                "resourceType": "Organization",
                "created": "2016-01-12T14:03:43.000Z",
                "lastModified": "2017-11-27T19:39:25.000Z",
                "location": "https://ofis.theoptimalcloud.com/scim/api/v2.0/Organizations/90A56861-6BE7-4401-A5A5-1AD1E1DCB579"
            },
            "displayName": "S-Mart",
            "addresses": [
                {
                    "country": "US",
                    "primary": true
                }
            ],
            "members": [
                {
                    "display": "Ash Williams",
                    "value": "BE324F48-E643-4E37-BDDE-91D40AD23C3A",
                    "$ref": "https://ofis.theoptimalcloud.com/scim/api/v2.0/Users/BE324F48-E643-4E37-BDDE-91D40AD23C3A"
                },
                {
                    "display": "Pablo Simon Bolivar",
                    "value": "3BA6DF2D-39DE-4535-B96A-A74053D77264",
                    "$ref": "https://ofis.theoptimalcloud.com/scim/api/v2.0/Users/3BA6DF2D-39DE-4535-B96A-A74053D77264"
                },
                {
                    "display": "Kelly Maxwell",
                    "value": "F7DBA961-0025-48DC-9E64-4090F76918B3",
                    "$ref": "https://ofis.theoptimalcloud.com/scim/api/v2.0/Users/F7DBA961-0025-48DC-9E64-4090F76918B3"
                }
            ],
            "organizationTypes": [
                {
                    "value": "Retail"
                }
            ]
        }
   ]
}


Entitlements Endpoint

The Entitlements endpoint is used to manage OptimalCloud Entitlements (or Applications).

GET /scim/api/v2.0/Entitlements/ HTTP/1.1

Host: ofis.theoptimalcloud.com

Response Body:

{
    "schemas": “urn:ietf:params:scim:api:messages:2.0:ListResponse”,
    "totalResults": 1,
    "Resources": [
        {
            "id": "FB01EF6A-777C-41FB-BFC8-1BB9B8F98324",
            "meta": {
                "resourceType": "Entitlement",
                "created": "2017-09-22T15:50:33.000Z",
                "lastModified": "2018-01-16T19:05:56.000Z",
                "location": "https://ofis.theoptimalcloud.com/scim/api/v2.0/Entitlements/FB01EF6A-777C-41FB-BFC8-1BB9B8F98324"
            },
            "minimumAuthLevel": "BASIC",
            "displayName": "POS App"
        }
     ]
}


Bulk Endpoint

The Bulk endpoint is used to send a potentially large collection of resource operations in a single request.

POST /scim/api/v2.0/Bulk/ HTTP/1.1

Host: ofis.theoptimalcloud.com


SCIM Operations

The goal of the OptimalCloud SCIM service is to adhere as closely as possible to the currently proposed SCIM standard regarding Create (POST), Read (GET), Update (PATCH), Replace (PUT) and Delete (DELETE).

It is highly recommended that the SCIM RFC7644 be used as a reference for details regarding each operation.

Create Object

The Create Object method of the OptimalCloud SCIM service adheres to the SCIM RFC7644 Create standard. To create new resources, clients send HTTP POST requests to the resource endpoint, such as "/Users" or "/Groups".

POST /scim/api/v2.0/Users/ HTTP/1.1

Host: ofis.theoptimalcloud.com

POST Body:

{
    "name": {
        "formatted": "Test User",
        "familyName": "User",
        "givenName": "Test"
    },
    "displayName": "Test User",
    "userName": "test.user@optimalidm.com",
    "password": "Password1",
    "emails": [
        {
            "type": "work",
            "primary": true,
            "value": "test.user@optimalidm.com"
        }
    ]
}


Read Object

The Read/Search Object method of the OptimalCloud SCIM service adheres to the SCIM RFC 7644 Retrieve standard. To retrieve a known resource, clients send GET requests to the resource endpoint, e.g., "/Users/{id}", "/Groups/{id}".

If you receive a “Forbidden” message from the service, it means that the “id” presented in the URL contains a dangerous character (for example, “+”). In these cases, you can simply URL Encode the value and specify it on a “id” query parameter, e.g., "/Users/?id=xxxxxxxxxx".

POST /scim/api/v2.0/Users/03C6CAF2-8543-46C5-B15F-1140A0F6FB60 HTTP/1.1

Host: ofis.theoptimalcloud.com

Response Body:

{
           "userName": "awilliams@smart.com",
            "name": {
                "familyName": "Williams",
                "givenName": "Ash"
            },
            "displayName": "Ash Williams",
            "active": true,
            "emails": [
                {
                    "type": "work",
                    "primary": true,
                    "value": "awilliams@smart.com"
                }
            ],
            "id": "03C6CAF2-8543-46C5-B15F-1140A0F6FB60",
            "meta": {
                "resourceType": "User",
                "created": "2016-05-17T16:02:17.000Z",
                "lastModified": "2016-05-17T16:02:17.000Z",
                "location": "https://ofis.theoptimalcloud.com/scim/api/v2.0/Users/03C6CAF2-8543-46C5-B15F-1140A0F6FB60"
            },
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ]
}

Note: If you are attempting to filter Users based on the Group, Organization, or Entitlement assignments, the filter only supports the equal (“eq”) condition.

For example, to return all users in the ACME Organization, the query string would be similar to:

/Users/?filter=(organizations.value eq "ACME")


The OptimalCloud SCIM service supports pagination of results, but does not support accessing a specific page out of sequence.

To indicate you wish to start a new search, set the startIndex parameter to “1”. Any startIndex value greater than “1” simply instructs the OptimalCloud SCIM service to return the next page. You will know you have reached the end of the pages when the number of resources retuned is less than the itemsPerPage parameter returned, or the search returns zero results, which means the previous result was the last page. The totalResults parameter is incremented as each page of resources are returned. This parameter will only contain the actual total number of resources on the last page of results.


Update Object

The Update Object method of the OptimalCloud SCIM service adheres to the SCIM RFC 7644 Modify standard. The Update Object method enables clients to update one or more attributes of a SCIM resource using a sequence of operations to "add", "remove", or "replace" values.

PATCH /scim/api/v2.0/Users/03C6CAF2-8543-46C5-B15F-1140A0F6FB60 HTTP/1.1

Host: ofis.theoptimalcloud.com

PATCH Body:

{
     "schemas":
       ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
     "Operations": [
       {
         "op":"remove",
         "path":"name.givenName"
       },
       {
         "op":"replace",
         "path":"entitlements",
         "value":[
         {
           "value": "FB01EF6A-777C-41FB-BFC8-1BB9B8F98324"
         }]
       }
     ]
 }


Replace Object

The Replace Object method of the OptimalCloud SCIM service adheres to the SCIM RFC 7644 Replace standard. The Replace Object method is used to replace a resource's attributes.

PUT /scim/api/v2.0/Users/03C6CAF2-8543-46C5-B15F-1140A0F6FB60 HTTP/1.1

Host: ofis.theoptimalcloud.com

PUT Body

{
    "name": {
        "formatted": "Test User UPDATED"
    },
    "displayName": "Test User UPDATED",
    "userName": "test.user.updated@optimalidm.com",
    "active": true,
    "password": "Password1",
    "emails": [
        {
            "value": "test.user.updated@optimalidm.com"
        }
    ],
    "phoneNumbers": [
        {
            "type": "work",
            "primary": true,
            "value": " 8134256351 "
        }
    ],    
    "addresses": [
        {
            "streetAddress": "3959 Van Dyke Rd.  Suite #190",
            "locality": "Lutz",
            "region": "FL",
            "postalCode": "33558",
            "country": "US",
            "primary": true
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
        "urn:ietf:params:scim:schemas:extension:optimalcloud:2.0:User"
    ]
}


Delete Object

The Delete Object method of the OptimalCloud SCIM service adheres to the SCIM RFC 7644 Delete standard. The Delete Object method is used to permanently delete a resource.

DELETE /scim/api/v2.0/Users/03C6CAF2-8543-46C5-B15F-1140A0F6FB60 HTTP/1.1

Host: ofis.theoptimalcloud.com


Bulk Operations

The Bulk Operations method of the OptimalCloud SCIM service adheres to the SCIM RFC 7644 Bulk Operations standard. The Bulk Operations method enables clients to send a potentially large collection of resource operations in a single request.

The OptimalCloud SCIM implementation extends the features of the standard SCIM Bulk Operation. In addition to the standard Bulk Operation methods, our implementation allows for a “SYNC” method. The “SYNC” method will create the object if it does not exist, returning a status of “201”; or update the object if it does already exist, returning a status of “201”.

POST /scim/api/v2.0/Bulk/ HTTP/1.1

Host: ofis.theoptimalcloud.com

POST Body:

   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
     "Operations": [
           {
             "method": "PATCH",
             "path": "/Users/6BB8B50A-2EF0-4688-AC27-CD3F60A5DC68",
             "data": 
                    [
                       {
                         "op":"remove",
                         "path":"name.givenName"
                       },
                       {
                         "op":"replace",
                         "path":"entitlements",
                         "value":[
                             {
                               "value": "FB01EF6A-777C-41FB-BFC8-1BB9B8F98324"
                             }
                         ]
                        }
                    ]
           },
           {
             "method": "PATCH",
             "path": "/Groups/3DF6BA88-03EF-4A26-BA33-B5D009374697",
             "data": 
                    [
                       {
                         "op":"replace",
                         "path":"displayName",
                         "value":[
                             {
                               "value": "This is a SCIM Test Group PATCH"
                             }
                         ]
                       },
                       {
                         "op":"add",
                         "path":"members",
                         "value":[
                             {
                               "value": "6BB8B50A-2EF0-4688-AC27-CD3F60A5DC68"
                             }
                         ]
                        }
                    ]
           },   
           {
             "method": "PATCH",
             "path": "/Organizations/8169C796-3AEB-458E-B25A-F54FBC2233BB",
             "data": 
                    [
                       {
                         "op":"replace",
                         "path":"displayName",
                         "value":[
                             {
                               "value": "SCIM Test Org PATCH"
                             }
                         ]
                        }
                    ]
           }   ,  
           {
             "method": "PATCH",
             "path": "/Entitlements/2C2B64B5-5347-4C77-973C-5179C3361B02",
             "data": 
                    [
                       {
                         "op":"replace",
                         "path":"displayName",
                         "value":[
                             {
                               "value": "SCIM Test Entitlement PATCH"
                             }
                         ]
                        }
                    ]
           }     
       ]
   }


SCIM Error Handling

The OptimalCloud SCIM service adheres as closely as possible to the currently proposed SCIM standard regarding error handling.

It is recommended that the SCIM RFC 7644 Status and Error Response section be used as a reference for possible errors and their resolutions.