Skip to main content

SCIM 2.0

SCIM is a widely accepted open standard designed to make managing user identities and user groups easier in cloud-based applications and services. It has a set of default contracts for users and groups which can be extended.

Our SCIM implementation targets version 2.0 of the protocol. Useful links:

This article covers SCIM implementation in Showpad.

Prerequisites
  • Showpad Enterprise package
  • Showpad admin account
  • A third-party identity management system

You should consider SCIM implementation as an extension of the Showpad API. Access can be done via Bearer authentication.

Base Endpoint

The base endpoint for SCIM calls is:

https://{your subdomain}.showpad.biz/api/users/scim/v2

Every request needs to be prefixed with the base endpoint.

Mapping

User maps SCIM attributes to a Showpad User. You can list, filter, add, edit or remove users.

A new user will be automatically assigned to the "All Users" group. This is a default group that you can't unassign from the user. If you want to assign the user to another group, it should exist already or be created via the groups endpoint.

SCIM attributeShowpad FieldAttribute TypeRequiredDefault
IDidSingularTrue
userNameuserNameSingularTrue
name.givenNamefirstNameSingularTrue
name.familyNamelastNameSingularTrue
emails[0].valueemailSingularTrue
activeisActiveSingularFalse
timezonetimezoneSingularFalse
localelanguageSingularFalseen
titlecompanyRoleSingularFalse""
externalIDscimIdSingularFalse""
enterprise.organizationcompanyNameSingularFalseCurrent organization
phoneNumbers[0].valuephoneSingularFalse""
phoneNumbers[0].type--SingularFalse"work" (read-only)
emails[0].type--SingularFalse"work" (read-only)
emails[0].primary--SingularFalseTrue (read-only)
roles[0].valueuserTypeSingularFalse"tablet"
groupsusergroupsMulti-ValuedFalse"All users" group
groups.valueusergroups.idSingularFalse"All users" group ID
groups.displayusergroups.nameSingularFalse"All users"
entitlementsmanagedUsergroupsMulti-ValuedFalse
entitlements.type--SingularFalse
entitlements.valuemanagedUsergroups.idSingularFalse

Attributes

User

User attributes are multi-valued in SCIM but singular in Showpad. When you're creating or replacing the user and specify multiple values, the primary value will be mapped and the other values discarded. If there is no primary, the first value will be used.

AttributeDescription
phoneNumbers
emails
rolesA means of grouping users with similar permissions, each group of users has access to the information intended for them according to rules that have been pre-defined by an administrator.

When changing this value, be aware that only certain roles are supported:

  • owner - Only 1 owner is allowed. You will get a uniqueness error if you try to create another one.
  • admin
  • manager - When a user has the manager role, they can have groups assigned for which they can coach other users. Assigning these groups can happen via the entitlements section. A single manager can have multiple entitlements assigned to them. Note: this is the only entitlement currently supported.
  • tablet - This is a default role.
groupsRead-only attribute. This allows you to see to which user groups a user belongs. Modifying a user's membership to a group should be handled through the Usergroup resource.
enterpriseIn the table corresponds to enterprise schema urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
emails[0].valueShould follow email pattern. Must be unique in the system. Otherwise you will get an uniquenesserror.
usernameThis must be unique in the system, otherwise you'll get a uniquenesserror.

Entitlements

When a user has the manager role, they can have groups assigned for which they can coach other users. Assigning these groups can happen via the entitlementssection using:

"entitlements": [
{
"value": "22b3d7f8eea74c37d3d140642ccbaeba",
"type": "coach_for_group"
}
]

Groups

SCIM attributeShowpad fieldAttribute TypeRequiredDefault
IDidSingularTrue
displayNamenameSingularTrue
membersusersMulti-ValuedFalse
members.valueusers.idSingularFalse
members.displayusers.usernameSingularFalse

Pagination

You can paginate through results by using startIndex and count query parameters.

For example, the following code will output the second page of a 10-paged result:

User

/Users?startIndex=11&count=10

Groups

/Groups?startIndex=11&count=10

Filtering

You can filter for users by fields following the specs. Currently, only the EQ operator on username is supported.

User

The following code will result in a list of users whose username is "john.doe@showpad.com":

/Users?filter=username%20eq%20"john.doe@showpad.com"

Groups

Filtering for groups has not been implemented in Showpad's SCIM 2.0 version.

POST

Users

This command creates a user.

POST {{url}}/Users
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

{
"active": true,
"emails": [
{
"primary": true,
"type": "work",
"value": "john.doe@showpad.com"
}
],
"locale": "en",
"name": {
"familyName": "Doe",
"givenName": "John"
},
"entitlements": [
{
"value": "22b3d7f8eea74c37d3d140642ccbaeba",
"type": "coach_for_group"
}
],
"roles": [
{
"value": "manager"
}
],
"timezone": "Europe/Brussels",
"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:enterprise:2.0:User": {
"organization": "John Doe's org"
},
"userName": "john.doe@showpad.com"
}

Groups

This command creates a group.

POST {{url}}/Groups
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "SCIM test group",
"members": [
{
"value": "abcdefgh123456789"
},
{
"value": "123456789abcdefgh"
}
]
}

GET

Schemas

Using a GET request you can retrieve:

EndpointDescription
/SchemasRetrieves all configuration details.
/Schemas/urn:ietf:params:scim:schemas:core:2.0:UserRetrieves user configuration details.
/Schemas/urn:ietf:params:scim:schemas:core:2.0:GroupRetrieves group configuration details.
/Schemas/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

ResourceTypes

Using a GET request you can retrieve:

EndpointDescription
/ResourceTypesOutputs types of resources.
/ResourceTypes/User
/ResourceTypes/Group

ServiceProviderConfig

Using a GET request you can retrieve:

EndpointDescription
/ServiceProviderConfigReturns a list of operations supported in the current implementation.

Users

This command returns a list of users, at 100 per page by default. You can adjust the results by sing pagination and/or filtering.

GET {{url}}/Users?startIndex=11&count=10&filter=username%20eq%20%22john.doe@showpad.com%22
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

Users/{Id}

This command returns a user with the specified ID.

GET {{url}}/Users/{id}
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

Groups

This command returns a list of groups, 100 groups per page by default. You can adjust the results by using pagination.

GET {{url}}/Groups?startIndex=11&count=10"
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

Groups{id}

This command returns a group with a specified ID.

GET {{url}}/Groups/{id}
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

PUT

Users/{id}

This command updates a user.

PUT {{url}}/Users/{id}
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

{
"emails": [
{
"value": "john.doe.second@showpad.com"
}
],
"name": {
"familyName": "Doe Second",
"givenName": "John"
},
"userName": "john-doe-second"
}

Groups/{id}

This command updates a group.

PUT {{url}}/Groups/{id}
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "SCIM test group change",
"members": [
{
"value": "abcdefgh123456789"
},
{
"value": "123456789abcdefgh"
}
]
}

DELETE

Users/{id}

This command deletes a specific user.

DELETE {{url}}/Users/{id}
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

A 204 No Content response will be returned in the case of a successful deletion.

Groups/{id}

This command deletes a specific group.

DELETE {{url}}/Groups/{id}
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

A 204 No Content response will be returned in the case of a successful deletion.

PATCH

This feature has not been implemented in Showpad's SCIM 2.0 version.