SCIM is a widely accepted open standard designed to make managing user identities in cloud-based applications and services easier. 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.
Accessing SCIM
One should consider SCIM implementation as an extension of Showpad's Public API. Access can be done via Bearer authentication.
You need this to succeed
- Showpad Enterprise package
- Showpad admin account
- A third-party identity management system
The base endpoint for the API is:
https://{organisation subdomain}.showpad.biz/api/users/scim/v2 |
Every following request needs to be prefixed with the base endpoint.
GET /Schemas
Outputs configuration details.
You can also retrieve them separately:
- GET /Schemas/urn:ietf:params:scim:schemas:core:2.0:User
- GET /Schemas/urn:ietf:params:scim:schemas:core:2.0:Group
- GET /Schemas/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
GET /ResourceTypes
Outputs types of resources.
You can also retrieve them separately:
- GET /ResourceTypes/User
- GET /ResourceTypes/Group
GET /ServiceProviderConfig
Returns a list of operations supported in the current implementation
User
User maps SCIM attributes to a Showpad User. You can list, filter, add, edit or remove users.
Attributes
Attributes such as phoneNumbers
, emails
, roles
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.
groups
is a read-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.
enterprise
in the table corresponds to enterprise schema urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
emails[0].value
and username
attributes have to be unique in the system. Otherwise you will get an uniqueness
error.
emails[0].value
should follow email pattern.
A new user will be automatically assigned to "All Users" group. That's 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 Groups endpoint.
While changing roles[0].value
be aware that only certain roles are supported in the system:
- owner (see note)
- admin
- manager
- tablet, a default role
Note: Only 1 owner is allowed in the system. You will get an uniqueness
error if you try to create another one.
Entitlements
When a user has the manager
role he can have groups assigned for which he can coach the users. Assigning these groups can happen via the entitlements
section using:
"entitlements": [
{
"value": "22b3d7f8eea74c37d3d140642ccbaeba",
"type": "coach_for_group"
}
]
It is possible to have multiple entitlements assigned to a single manager. This is the only entitlement currently supported.
Mapping
SCIM attribute |
Showpad Field |
Attribute Type |
Required | Default |
---|---|---|---|---|
ID | id | Singular | True | |
userName | userName | Singular | True | |
name.givenName | firstName | Singular | True | |
name.familyName | lastName | Singular | True | |
active | isActive | Singular | False | |
timezone | timezone | Singular | False | |
locale | language | Singular | False | en |
title | companyRole | Singular | False | "" |
externalID | scimId | Singular | False | "" |
enterprise.organization | companyName | Singular | False | Current organization |
phoneNumbers[0].value | phone | Singular | False | "" |
phoneNumbers[0].type | -- | Singular | False | "work" (read-only) |
emails[0].value | Singular | True | ||
emails[0].type | -- | Singular | False | "work" (read-only) |
emails[0].primary | -- | Singular | False | True (read-only) |
roles[0].value | userType | Singular | False | "tablet" |
groups | usergroups | Multi-Valued | False | "All users" group |
groups.value | usergroups.id | Singular | False | "All users" group id |
groups.display | usergroups.name | Singular | False | "All users" |
entitlements | managedUsergroups | Multi-Valued | False | |
entitlements.type | -- | Singular | False | |
entitlements.value | managedUsergroups.id | Singular | False |
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"
}
|
Get /Users/{Id}
This command returns a user with the specified ID.
GET {{url}}/Users/{id}
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}
GET {{url}}/Users?startIndex=11&count=10&filter=username%20eq%20%22john.doe@showpad.com%22
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}
You can paginate through the results by using startIndex
and count
query parameters.
For example: /Users?startIndex=11&count=10
will output the second page of a 10-paged result.
Filtering
You can filter for users by fields following the specs. Currently, only EQ
operator on username
is supported.
For example: /Users?filter=username%20eq%20"john.doe@showpad.com"
will result in a list of users with username=john.doe@showpad.com
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"
}
DELETE /Users/{id}
This command deletes a user.
DELETE {{url}}/Users/{id}
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}
Returns 204 No Content
in case of successful deletion.
PATCH /Users/{id}
This feature has not been implemented in Showpad's SCIM 2.0 version.
Group maps SCIM attributes to a Showpad Usergroup. You can list, filter, add, edit or remove groups.
The "All Users" group exists by default and it's in a read-only mode. It can't be changed or removed.
A user's membership can be modified by adding or removing it from the members
attribute. Only the value
attribute is taken into account when adding a user to a group.
SCIM attribute |
Showpad field |
Attribute Type |
Required |
Default |
---|---|---|---|---|
ID |
id |
Singular |
True |
|
displayName |
name |
Singular |
True |
|
members |
users |
Multi-Valued |
False |
|
members.value |
users.id |
Singular |
False |
|
members.display |
users.username |
Singular |
False |
|
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 {{url}}/Groups/{id}
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}
GET {{url}}/Groups?startIndex=11&count=10"
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}
startIndex
and count
query parameters.
For example: /Groups?startIndex=11&count=10
will output the second page of a 10-page result.
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 {{url}}/Groups/{id}
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}
204 No Content
in the case of a successful deletion.