Developer Resources

SCIM Schema

SCIM provides a standard schema that can be used to represent a user or a group. This schema is extensible so additional schema objects can be added to provide custom schema support.

Along with the SCIM schema, specific data types are defined to simplify interoperability between partners.

SCIM Data Types

The SCIM core schema has a support for common data types to provide maximum interoperability between SCIM Service Providers and SCIM Consumers. The following data types are available in the SCIM specification and examples are provided in JSON representation:

String

"familyName" : "Archer"

Boolean

"active" : true

Decimal

"weight" : 173.2

Integer

"age" : 36

DateTime (xml date/time format)

"created" : "2015-05-18T15:00:00Z"

Binary (base64 encoded string)

"photo" : "U2F5IENoZWVzZSE="

SCIM Attribute Types

Attributes in SCIM can be either single-valued or multi-valued and SCIM can support complex attributes where an attribute can be comprised of multiple single or multi-valued sub attributes, for example:

Simple Attribute (single-valued)

An attribute that contains a single value

{
  "displayName": "Archer, Meredith A"
}

Simple Attribute (multi-valued)

An attribute that contains multiple values. Multiple values can include a "type" attribute to define the type of value specified (i.e. work vs home address).

{
  "emails": [
    {
      "type" : "other",
      "value" : "marcher@pingdevelopers.com"
    },
    {
      "type": "work",
      "value" : "meredith.archer@pingdevelopers.com"
    }
  ]
}

Complex Attribute

An attribute that contains one or more simple attributes

{
  "name":
    {
      "familyName": "Archer",
      "givenName": "Meredith",
      "displayName" : "Archer, Meredith A"
    }
}

Sub-Attribute

An attribute that is a member of a complex attribute.

using the previous example, "familyName" is a sub-attribute of "name"

Common Schema Attributes

Common schema elements must be included on all resources and are used to provide a reference identifier for the resource as well as information about the resource:

id

String

Unique identifier for the resource as defined by the Service Provider [REQUIRED]

externalId

String

Identifier for the resource as defined by the SCIM Consumer (i.e. a local identifier or customerId in an application) [REQUIRED]

meta

Complex Attribute

The resources metadata, the "meta" complex attribute may consist of the following attributes: [REQUIRED]

created

meta

DateTime

When the resource was created

lastModified

meta

DateTime

When the resource was last modified (if the resource has not been modified since creation, this value will be the same as the created attribute)

location

meta

String

The direct URI of the resource. You can use this URI to directly manage a resource rather than searching for it and then modifying.

version

meta

String

(if supported). The version of the resource being returned.

attributes

meta

String (multi-valued)

(if supported). Contains the list of attributes to remove during a PATCH operation.

SCIM User Attributes

A SCIM User consists of one required attribute (userName) and additional descriptive attributes:

userName

String

Unique identifier for the User as described by the SCIM Consumer (typically the user name used to login) [REQUIRED]

name

Complex Attribute

Components of the user’s real name:

formatted

name

String

The formatted representation of the user (i.e. "Ms Meredith Anne Archer, II")

familyName

name

String

Family or last name of the user (i.e. Archer)

givenName

name

String

Given or first name of the user (i.e. Meredith)

middleName

name

String

The middle name(s) or initial(s) of the user (i.e. Anne)

honorificPrefix

name

String

Honorific or personal title of the user (i.e. Mr, Ms)

honorificSuffix

name

String

Honorific or generational suffix of the user (i.e. Jr, II)

displayName

String

How the user name should be presented in an application, this is not necessarily tied to the formatted name attribute (i.e. Archer, Meredith A)

nickName

String

Casual or preferred representation of the user’s name (i.e. Bob rather than Robert)

profileUrl

String

A fully qualified URL of the users profile (i.e. https://profiles.pingdevelopers.com/marcher)

title

String

Work title of the user (i.e. "Software Developer")

userType

String

Defines the relationship of the user to the SCIM Service Provider organization (i.e. Employee)

preferredLanguage

String

User’s preferred language and dialect (i.e. en_US)

locale

String

User’s locale for localization purposes (currency, date time format etc) (i.e. en_US)

timezone

String

User’s timezone in the "Olson" timezone database format (i.e. America/Denver)

active

Boolean

Whether the user is active at the Service Provider

password

String

WRITE-ONLY. The user’s clear-text password. Can only be provided in a POST operation (for a create) or a PUT operation for a password change.

emails

String Multi-valued

Email address(es) for the user. Common "type" values are work, home, other.

phoneNumbers

String Multi-valued

Telephone number(s) for the user. Common "type" values are work, home, fax, pager, mobile, other.

ims

String Multi-valued

Instant messaging address(es) for the user. Common "type" values are gtalk, icq, aim, skype

photos

String Multi-valued

URL of a profile photo for the user. Common "type" values are thumbnail, photo

addresses

Complex Attribute Multi-Valued

Physical mailing address for the user. Common "type" values are home, work, other

formatted

addresses

String

Full mailing address formatted for display (i.e. 1001 17th Street\nSuite 100\nDenver CO 80202)

streetAddress

addresses

String

Full street address component (i.e. 1001 17th Street\nSuite 100)

locality

addresses

String

The city or locality (i.e. Denver)

region

addresses

String

The region / state / province of the address (i.e. CO)

postalCode

addresses

String

The postal code or zipcode of the address (i.e. 80202)

country

addresses

String

ISO3166-1 alpha 2 "short" format of the country (i.e. US)

groups

String Multi-Valued

List of groups the user belongs to

entitlements

Undefined Multi-Valued

List of entitlements for the user (SCIM doesn’t specify a format for these entitlements)

roles

String Multi-Valued

List of roles the user has (although SCIM doesn’t specify a format for roles, its expected that they are a list of String values)

x509Certificates

Binary

List of x509 certificates for the user. Value is a binary (base64 encoded) DER encoded x509 certificate.

Group Schema Attributes

A group resource can be used to define roles or groups a user is a member of.NOTE: Groups can be nested inside other groups to provide users with indirect membership of a group.

displayName

String

Human readable name for the group [REQUIRED]

members

String Multi-Valued

List of members of the group, the value will be the "id" value of the resource (user or group) and the multi-valued attribute type may be "user" or "group"