Utilize SCIM 2.0 with Showpad

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:

• SCIM open standard
• SCIM 2.0 specification

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 concepts of awesomeness

• Endpoints
• Basic Commands
• SCIM 2.0 methods
• Group Commands

Endpoints

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.

Basic Commands

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, rolesare 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"
    }
]

SCIM 2.0 Methods

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}}

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 {{url}}/Users/{id}
Accept: application/json
Authorization: Bearer {{token}}
Host: {{host}}

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}}

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}}