Skip to content

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.

organization-menu

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:

  1. User Endpoint
  2. Group Endpoint
  3. 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 /restv1/Users GET, POST Retrieve/Add/Modify Users
Group /restv1/Groups GET, POST Retrieve/Add/Modify Groups
Bulk /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/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/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/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/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/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/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/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:

SCIM 2.0 Endpoints#

Definitions#

Address

name type required description example
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 example
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 example
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 example
operation string optional -
value string optional -
display string optional -
primary boolean optional -
type Type optional -
$ref string optional -

Entitlement

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

Group

name type required description example
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 example
value string optional -
display string optional -
type Type optional -
$ref string optional -

Im

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

ListResponse

name type required description example
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 example
operation string optional -
value string optional -
display string optional -
type Type optional -
$ref string optional -

Meta

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

Name

name type required description example
formatted string optional -
familyName string optional -
givenName string optional -
middleName string optional -
honorificPrefix string optional -
honorificSuffix string optional -

PhoneNumber

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

Photo

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

Resource

name type required description example
id string optional -
externalId string optional -
meta Meta optional -
schemas array[string] required -

Role

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

Type

name type required description example

User

name type required description example
id string optional -
externalId string optional -
meta Meta optional -
schemas array[string] required -
userName string optional -
name Name optional -
displayName string optional -
nickName string optional -
profileUrl string optional -
title string optional -
userType string optional -
preferredLanguage string optional -
locale string optional -
timezone string optional -
active boolean optional -
password string optional -
emails array[Email] optional -
phoneNumbers array[PhoneNumber] optional -
ims array[Im] optional -
photos array[Photo] optional -
addresses array[Address] optional -
groups array[GroupRef] optional -
entitlements array[Entitlement] optional -
roles array[Role] optional -
x509Certificates array[X509Certificate] optional -

X509Certificate

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

ScimPersonSearch

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

User Endpoint#

URL#

<domain root>/identity/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 Description 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/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/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 Description 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/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 Description 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/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/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