SCIM API#

Gluu Server Community Edition supports System for Cross-domain Identity Management (SCIM) Version 1.0 and 2.0 out of the box, operated using HTTP GET and POST commands. SCIM uses a REST API for operations which are disabled by default.

To enable support for SCIM open the oxTrust administration interface and navigate to Organization Configuration > System Configuration.

Find SCIM Support and select Enabled.

enable

SCIM Endpoints#

SCIM uses REST API for the operations which are covered in short in this section. There are two versions of the SCIM API each with its own specification. This usage of SCIM requires advanced level knowledge of HTTP GET and POST commands and not recommended for entry level users.

The SCIM 1.1 is governed by the SCIM:Protocol 1.1 document and SCIM 2.0 is governed by the SCIM:Core Schema & SCIM:Protocol. As it is mentioned before, the specifications define an API, the operations are performed through endpoints. There are three endpoints that are available in Gluu Server SCIM:

User Endpoint
Group Endpoint
Bulk Operation Endpoint

The supported operations are given later in this document.

SCIM 1.1#

The endpoints URLS are incomplete without the hostname. Please use the hostname of Gluu Server Community Edition before using URLs to make any request using SCIM.

Resource	Endpoint	Operations	Description
User	/seam/resource/restv1/Users	GET, POST	Retrieve/Add/Modify Users
Group	/seam/resource/restv1/Groups	GET, POST	Retrieve/Add/Modify Groups
Bulk	/seam/resource/restv1/scim/v1/Bulk	GET, POST	Bulk modify Resources

The endpoints are described in detail in the following sections. Please remember to go through the specifications before using SCIM.

Endpoint: User & Group#

The userinfo endpoint is shown above in Section SCIM 1.1. The following is an example of a userinfo endpoint for a Gluu Server with hostname idp.gluu.org:

https://idp.gluu.org/host/seam/resource/restv1/scim/v1/Users/{rsid}

The groups endpoint is also shown in Section SCIM 1.1. The following is an example of a groupinfo endpoint for a Gluu Server with hostname idp.gluu.org:

https://idp.gluu.org/host/seam/resource/restv1/scim/v1/Groups/{rsid}

The following table details the request parameters to the endpoints:

Parameter	Data Type	Location	Required	Description
rsid	string	path	TRUE	Resource set description ID
Authorization	string	header	FALSE

The response contains a JSON body with a status code 200 if the request was successfully processed.

Please see the Response Code Section for more details.

Example#

The following is an example to add a new user with SCIM 1.1 in idp.gluu.org using a JSON Request.

POST https://idp.gluu.org/oxTrust/seam/resource/restv1/Users/ 
Accept: application/json 
Authorization: Basic bWlrZTpzZWNyZXQ=

{
  "schemas": ["urn:scim:schemas:core:1.0"],
  "externalId": "mike",
  "userName": "mike",
  "name": {"givenName": "Michael", "familyName": "Schwartz", "middleName": "N/A", "honorificPrefix": "N/A", "honorificSuffix": "N/A"},
  "displayName": "Michael Schwartz",
  "nickName": "Sensei",
  "profileUrl": "http://www.gluu.org/",
  "emails": [
    {"value": "mike1@gluu.org","type": "work","primary": "true"},
    {"value": "mike2@gluu.org","type": "home","primary": "false"}
  ],
  "addresses": [{"type": "work", "streetAddress": "621 East 6th Street Suite 200", "locality": "Austin", "region": "TX", "postalCode": "78701","country": "US","formatted": "621 East 6th Street Suite 200  Austin, TX 78701 US", "primary": "true"}],
  "phoneNumbers": [{"value": "646-345-2346", "type": "work"}],
  "ims": [{"value": "nonomike", "type": "Skype"}],
  "photos": [{"value": "http://www.gluu.org/wp-content/themes/SaaS-II/images/logo.png", : "gluu photo"}],
  "userType": "CEO",
  "title": "CEO",
  "preferredLanguage": "en-us",
  "locale": "en_US",
  "timezone": "America/Chicago",
  "active": "true",
  "password": "secret",
  "groups": [
    {"display": "Gluu Manager Group", "value": "@!1111!0003!B2C6"},
    {"display": "Gluu Owner Group", "value": "@!1111!0003!D9B4"}
  ],
  "roles": [{"value": "Owner"}],
  "entitlements": [{"value": "full access"}],
  "x509Certificates": [{"value": "MIIDQzCCA ... shortened fo convenience ... tGcrs2i97ZkJMo="}],
  "meta": {
    "created": "2010-01-23T04:56:22Z",
    "lastModified": "2011-05-13T04:42:34Z",
    "version": "W\\\"b431af54f0671a2\"",
    "location": "http://localhost:8080/oxTrust/seam/resource/restv1/Users/@!1111!0000!D4E7"
  }
}

The response is in JSON as well. The following is the expected response

201 CREATED
Server:  Apache-Coyote/1.1
Location:  https://idp.gluu.org/oxTrust/seam/resource/restv1/Users/@!1111!0000!D4E7
Content-Type:  application/json

{
  "schemas": ["urn:scim:schemas:core:1.0"],
  "id": "@!1111!0000!D4E7",
  "externalId": "mike",
  "userName": "mike",
  "name": {"givenName": "Michael", "familyName": "Schwartz", "middleName": "N/A", "honorificPrefix": "N/A", "honorificSuffix": "N/A"},
  "displayName": "Micheal Schwartz",
  "nickName": "Sensei",
  "profileUrl": "http://www.gluu.org/",
  "emails": [
    {"value": "mike@gluu.org", "type": "work", "primary": "true"},
    {"value": "mike2@gluu.org", "type": "home", "primary": "false"}
  ],
  "addresses": [{"type": "work", "streetAddress": "621 East 6th Street Suite 200", "locality": "Austin", "region": "TX", "postalCode": "78701", "country": "US", "formatted": "621 East 6th Street Suite 200  Austin, TX 78701 US", "primary": "true" }],
  "phoneNumbers": [{"value": "646-345-2346", "type": "work"}],
  "ims": [{"value": "nonomike","type": "Skype"}],
  "photos": [{"value": "http://www.gluu.org/wp-content/themes/SaaS-II/images/logo.png", "type": "gluu photo"}],
  "userType": "CEO",
  "title": "CEO",
  "preferredLanguage": "en-us",
  "locale": "en_US",
  "timezone": "America/Chicago",
  "active": "true",
  "password": "Hiden for Privacy Reasons",
  "groups": [
    {"display": "Gluu Manager Group", "value": "@!1111!0003!B2C6"},
    {"display": "Gluu Owner Group", "value": "@!1111!0003!D9B4"}
  ],
  "roles": [{"value": "Owner"}],
  "entitlements": [{"value": "full access"}],
  "x509Certificates": [{"value": "MIIDQzCCA ... shortened fo convenience ... tGcrs2i97ZkJMo="}],
  "meta": {
    "created": "2010-01-23T04:56:22Z",
    "lastModified": "2011-05-13T04:42:34Z",
    "version": "W\\\"b431af54f0671a2\"",
    "location": "http://localhost:8080/oxTrust/seam/resource/restv1/Users/@!1111!0000!D4E7"
  }
}

Endpoint: Bulk#

Bulk endpoint allows the administrator to work with a large collection of Resources with a single request. A body of a bulk operation may contain a set of HTTP Resource operations using one of the API supported HTTP methods; i.e., POST, PUT, PATCH or DELETE. Please see the SCIM Specs for more details.

The example below shows the bulk operation endpoint for a Gluu Server with hostname idp.gluu.org:

https://idp.gluu.org/seam/resource/restv1/scim/v1/Bulk

The following table details the request parameters:

Parameter	Data Type	Location
Authorization	string	header
body	BulkRequest	body

Definitions#

The definitions relevant for a bulk operation are shown in the table below. All parameters are optional.

BulkOperation		BulkRequest		BulkResponse
Parameter	Data Type	Parameter	Data Type		Parameter
bulkid	string	schemes	array[string]	schemes	array[string]
version	string	operations	array[BulkOperation]	operations	array[BulkOperation]
method	string	failOnErrors	integer(int32)
path	string
location	string
status	string
data	object
response	object

Response Codes#

This sections defines the response codes for the requests sent to the SCIM endpoints.

Status Code	Reason	Description
200	OK	Successful Operation
201	Created	Successfully created resource

Status Code	Reason	Description
400	Bad Request	Request cannot be parsed, is syntactically incorrect, or violates schema
401	Unauthorized	Authorization header is invalid or missing
403	Forbidden	Operation is not permitted based on the supplied authorization
404	Not Found	Specified resource does not exist

SCIM 2.0#

The detailed SCIM 2.0 Specifications are available at:

Definitions#

Address

name	type	required	description
operation	string	optional	-
primary	boolean	optional	-
formatted	string	optional	-
streetAddress	string	optional	-
locality	string	optional	-
region	string	optional	-
postalCode	string	optional	-
country	string	optional	-
type	Type	optional	-
$ref	string	optional	-

BulkOperation

name	type	required	description
bulkId	string	optional	-
version	string	optional	-
method	string	optional	-
path	string	optional	-
location	string	optional	-
data	object	optional	-
status	string	optional	-
response	object	optional	-

BulkRequest

name	type	required	description
schemas	array[string]	optional	-
failOnErrors	integer (int32)	optional	-
operations	array[BulkOperation]	optional	-

BulkResponse

name	type	required	description	example
schemas	array[string]	optional	-
operations	array[BulkOperation]	optional	-

Email

name	type	required	description
operation	string	optional	-
value	string	optional	-
display	string	optional	-
primary	boolean	optional	-
type	Type	optional	-
$ref	string	optional	-

Entitlement

name	type	required	description
operation	string	optional	-
value	string	optional	-
display	string	optional	-
primary	boolean	optional	-
type	Type	optional	-
$ref	string	optional	-

Group

name	type	required	description
id	string	optional	-
externalId	string	optional	-
meta	Meta	optional	-
schemas	array[string]	required	-
displayName	string	optional	-
members	array[MemberRef]	optional	-

GroupRef

name	type	required	description
value	string	optional	-
display	string	optional	-
type	Type	optional	-
$ref	string	optional	-

Im

name	type	required	description
operation	string	optional	-
value	string	optional	-
display	string	optional	-
primary	boolean	optional	-
type	Type	optional	-
$ref	string	optional	-

ListResponse

name	type	required	description
totalResults	integer (int32)	optional	-
startIndex	integer (int32)	optional	-
itemsPerPage	integer (int32)	optional	-
schemas	array[string]	optional	-
resources	array[Resource]	optional	-

MemberRef

name	type	required	description
operation	string	optional	-
value	string	optional	-
display	string	optional	-
type	Type	optional	-
$ref	string	optional	-

User Endpoint#

URL#

<domain root>/identity/seam/resource/restv1/scim/v2/Users

GET#

Search Users - searches users based on filter criteria

Security#

UMA (default)
OAuth2 Access Token (Test Mode)

Request#

Content-Type: application/scim+json, application/json

Parameters#

Name	Located in	Required	Default	Schema
Authorization	header	yes (default)	-	string
access_token	query	yes (if "Test Mode" is enabled)	-	string
filter	query	no	-	string
startIndex	query	no	-	string
count	query	no	-	string
sortBy	query	no	-	string
sortOrder	query	no	-	string
attributes	query	no	-	string array

Response#

Content-Type: application/scim+json, application/json

Status Code	Reason	Response Model
200	successful operation	ListResponse

POST#

Create User - creates a user

Security#

UMA (default)
OAuth2 Access Token (Test Mode)

Request#

Content-Type: application/scim+json, application/json

Parameters#

Name	Located in	Required	Description	Default	Schema
Authorization	header	yes (default)		-	string
access_token	query	yes (if "Test Mode" is enabled)		-	string
body	body	yes	User	-	User
attributes	query	no		-	string array

Response#

Content-Type: application/scim+json, application/json

Status Code	Reason	Response Model
201	successful operation	User

URL#

<domain root>/identity/seam/resource/restv1/scim/v2/Users/{id}

GET#

Find User By ID - returns a user by id as path parameter

Security#

UMA (default)
OAuth2 Access Token (Test Mode)

Request#

Content-Type: application/scim+json, application/json

Parameters#

Name	Located in	Required	Description	Default	Schema
Authorization	header	yes (default)		-	string
access_token	query	yes (if "Test Mode" is enabled)		-	string
id	path	yes	LDAP 'inum' of user	-	string
attributes	query	no		-	string array

Response#

Content-Type: application/scim+json, application/scim

Status Code	Reason	Response Model
200	successful operation	User

PUT#

Update User - updates a user

Security#

UMA (default)
OAuth2 Access Token (Test Mode)

Request#

Content-Type: application/scim+json, application/json

Parameters#

Name	Located in	Required	Description	Default	Schema
Authorization	header	yes (default)		-	string
access_token	query	yes (if "Test Mode" is enabled)		-	string
id	path	yes	LDAP 'inum' of user	-	string
body	body	yes	User	-	User
attributes	query	no		-	string array

Response#

Content-Type: application/scim+json, application/json

Status Code	Reason	Response Model
200	successful operation	User

DELETE#

Delete User - deletes a user

Security#

UMA (default)
OAuth2 Access Token (Test Mode)

Request#

Parameters#

Name	Located in	Required	Description	Default	Schema
Authorization	header	yes (default)		-	string
access_token	query	yes (if "Test Mode" is enabled)		-	string
id	path	yes	LDAP 'inum' of user	-	string

Response#

Content-Type: application/scim+json, application/json

Status Code	Reason	Response Model
default	successful operation	-

URL#

<domain root>/identity/seam/resource/restv1/scim/v2/Users/Search

POST#

Search Users (Deprecated) - searches users by HTTP POST

Security#

UMA (default)
OAuth2 Access Token (Test Mode)

Request#

Content-Type: application/scim+json, application/json

Parameters#

Name	Located in	Required	Default	Schema
Authorization	header	yes (default)	-	string
access_token	query	yes (if "Test Mode" is enabled)	-	string
body	body	yes	-	ScimPersonSearch

Response#

Content-Type: application/scim+json, application/json

Status Code	Reason	Response Model
200	successful operation	ListResponse

Group Endpoint#

URL#

<domain root>/identity/seam/resource/restv1/scim/v2/Groups

GET#

Search Groups - searches groups based on filter criteria

Security#

UMA (default)
OAuth2 Access Token (Test Mode)

Request#

Content-Type: application/scim+json, application/json

Parameters#

Name	Located in	Required	Default	Schema
Authorization	header	yes (default)	-	string
access_token	query	yes (if "Test Mode" is enabled)	-	string
filter	query	no	-	string
startIndex	query	no	-	string
count	query	no	-	string
sortBy	query	no	-	string
sortOrder	query	no	-	string
attributes	query	no	-	string array

Response#

Content-Type: application/scim+json, application/json

Status Code	Reason	Response Model
200	successful operation	ListResponse

POST#

Create Group - creates a group

Security#

UMA (default)
OAuth2 Access Token (Test Mode)

Request#

Content-Type: application/scim+json, application/json

Parameters#

Name	Located in	Required	Description	Default	Schema
Authorization	header	yes (default)		-	string
access_token	query	yes (if "Test Mode" is enabled)		-	string
body	body	yes	Group	-	Group
attributes	query	no		-	string array

Response#

Content-Type: application/scim+json, application/json

Status Code	Reason	Response Model
201	successful operation	Group

URL#

<domain root>/identity/seam/resource/restv1/scim/v2/Groups/{id}

GET#

Find Group By ID - returns a group by id as path parameter

Security#

UMA (default)
OAuth2 Access Token (Test Mode)

Request#

Content-Type: application/scim+json, application/json

Parameters#

Name	Located in	Required	Description	Default	Schema
Authorization	header	yes (default)		-	string
access_token	query	yes (if "Test Mode" is enabled)		-	string
id	path	yes	LDAP 'inum' of group	-	string
attributes	query	no		-	string array

Response#

Content-Type: application/scim+json, application/json

Status Code	Reason	Response Model
200	successful operation	Group

PUT#

Update Group - updates a group

Security#

UMA (default)
OAuth2 Access Token (Test Mode)

Request#

Content-Type: application/scim+json, application/json

Parameters#

Name	Located in	Required	Description	Default	Schema
Authorization	header	yes (default)		-	string
access_token	query	yes (if "Test Mode" is enabled)		-	string
id	path	yes	LDAP 'inum' of group	-	string
body	body	yes	Group	-	Group
attributes	query	no		-	string array

Response#

Content-Type: application/scim+json, application/json

Status Code	Reason	Response Model
200	successful operation	Group

DELETE#

Delete Group - deletes a group

Security#

UMA (default)
OAuth2 Access Token (Test Mode)

Request#

Parameters#

Name	Located in	Required	Description	Default	Schema
Authorization	header	yes (default)		-	string
access_token	query	yes (if "Test Mode" is enabled)		-	string
id	path	yes	LDAP 'inum' of the group	-	string

Response#

Content-Type: application/scim+json, application/json

Status Code	Reason	Response Model
default	successful operation	-

Bulk Operation Endpoint#

URL#

<domain root>/identity/seam/resource/restv1/scim/v2/Bulk

POST#

Bulk Operations - bulk operations

Security#

UMA (default)
OAuth2 Access Token (Test Mode)

Request#

Content-Type: application/scim+json, application/json

Parameters#

Name	Located in	Required	Description	Default	Schema
Authorization	header	yes (default)		-	string
access_token	query	yes (if "Test Mode" is enabled)		-	string
body	body	yes	BulkRequest	-	BulkRequest

Response#

Content-Type: application/scim+json, application/json

Status Code	Reason	Response Model
200	successful operation	BulkResponse

name	type	required	description
created	string (date-time)	optional	-
lastModified	string (date-time)	optional	-
location	string	optional	-
version	string	optional	-
attributes	array[string]	optional	-
resourceType	string	optional	-

name	type	required	description	example
attribute	string	required	User Attribute Name	Username
value	string	required	User Attribute Value	Mike