Support Center

Single Sign On - User Identity Sync (SCIM)

In this article you will learn :

  • What is User Identity Sync (SCIM)
  • Benefits of using SCIM
  • SCIM terminology
  • How to use SCIM with Sherpany

Preface

With Single Sign-on (SSO) users can authenticate in Sherpany using an external Identity Provider. User attributes like Email and Name are updated in Sherpany every time a user logs in.

User Identity Sync builds on top of that and also allows the Enterprise Identity Provider to write User attributes to the Sherpany database whenever necessary (without waiting for a user to login).

REQUIRED Package: Enterprise (with SSO)


Benefits of User Identity Sync

Implementing User Identity Sync brings several advantages to your org.

  • Reduced administrative costs - With User Identity Sync, User details changes only need to be done in one place and reduce time spent by administrators keeping permissions up to date in Sherpany.
  • Leverage existing investment - Many companies use a central LDAP database to manage user identities. You can use the existing system and processes to assign roles in Sherpany. So if a User changes from one department to another that can automatically reflect into permission changes in Sherpany.
  • Increased security - Users changing departments within the company won't have access to resources they are not supposed to see in Sherpany automatically. SCIM also supports offboarding users when they leave the company.

SCIM

System for Cross-domain Identity Management (SCIM) is a standard for managing user identities across applications.

It is a REST API with a clearly defined structure. Many vendors (such as Microsoft, Github, Slack, and Salesforce) support the SCIM standard and there are libraries available for various programming languages (such as Java, Python).

Sherpany supports SCIM2 (Version 1.x is not supported).

We don't include in-depth technical descriptions about the SCIM API in general in this document, see http://www.simplecloud.info/ for details.


Definitions

Term
Description
Service Provider

The web application that allows editing of identity information over the SCIM protocol.

Sherpany is the Service Provider.

Client

An application that uses the SCIM protocol to manage identity data maintained by the Service Provider.

The Sherpany Enterprise Customer is the Client.

Resource (e.g User)An artifact that is managed by a service provider that contains has attributes, e.g a User.
OrganizationThe Sherpany Customer
UserA person who has access to the Sherpany app.


Resources


externalIdmax length 255 characters


User

Schema: urn:ietf:params:scim:schemas:core:2.0:User

See https://tools.ietf.org/html/rfc7643#section-4.1 for the full definition in SCIM. Sherpany supports the following subset:


FieldExampleDescription
id85d0c1a8-fda3-4656-b4d3-7bcf8fda6d95Set by Sherpany. A unique unchanging id.
externalIdx1234asdfuiopqere

Set by Client. A unique unchanging id assigned to a User. The value must be unique within the Organisation and must match the NameID used in SAML.

Required

activetrue or false

The Users administrative status. A value of true implies that the user is able to log in, while a value of false implies that the user's account has been suspended.

userNamebjensen@example.com

The email of the User. We validate that the domain part (@example.com) is on the whitelist of allowed domains for this client.

Required

name

{
    "familyName": "Jensen",
    "givenName": "Barbara"
}

Sherpany uses familyName and givenName (required) from name. Other values are ignored. 

Required

preferredLanguageen-gb

allowed values: en-gb, de-ch, fr-fr, it-it, pt-pt

Optional (falls back to the default value of en-gb)

phones
						
{				
        "value": "+41791234567",				
        "type": "work"				
}
						

Sherpany only uses the first item in the list.

Optional


Not supported attributes

Sherpany User Attributes not supported by SCIM:

  • Profile picture
  • hand-signature
  • gender

User resources can not be deleted. Set users as inactive instead.


Operations


Supported
Operation
Description
SCIM Documentation Link
(tick)GETRetrieve an existing resource (or list of resources)https://tools.ietf.org/html/rfc7644#section-3.4
(tick)POSTCreate a new resourcehttps://tools.ietf.org/html/rfc7644#section-3.3
(tick)PUTUpdate an existing resourcehttps://tools.ietf.org/html/rfc7644#section-3.5.1
(minus)DELETE

Delete a resource

Some resources do not support deletion.
Some resource support deletion (Sherpany does a "soft-delete" on the server-side). Uniqueness constraints still apply.

Can't be deleted:

  • User
https://tools.ietf.org/html/rfc7644#section-3.6
(minus)PATCHAtomic partial updatehttps://tools.ietf.org/html/rfc7644#section-3.5.2


SCIM bulk operations are not supported.


Configuration

Sherpany will setup the Organisation and configure SSO (SAML) with a whitelist of allowed email domains which will be under the jurisdiction of this SCIM Domain.


Name
Value
SCIM API base URLhttps://app.sherpany.com/api/scim/
Authentication

using a Bearer Token in the http header of all requests

Authorization: Bearer <TheToken>

The Token is bound to an Organisation and access is limited to Resources associated with that Organisation.

Sherpany Staff will provide the Token through a secure channel.

Advanced Token creation

It is also possible for the Sherpany Enterprise Customer to generate the RSA Keypair and use the Private key themselves to generate a RS512 JWT following our guidelines.

This has the benefit that:

  • the Secret Key never has to be communicated (only the public key needs to be sent to Sherpany)
  • the Customer can generate short lived tokens as needed which mitigates the risk of a token being stolen in-transit.


Examples

Get all users

Example Request to get all Users

GET /api/scim/Users HTTP/1.1
Host: app.sherpany.com
Accept: application/scim+json
Authorization: Bearer eyJhbG.eyJvaWQiO.a7jxyB_kMcmi5
      

Create user

POST /api/scim/Users HTTP/1.1
Host: app.sherpany.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer eyJhbG.eyJvaWQiO.a7jxyB_kMcmi5
 
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "test.tester@sherpany.com",
  "externalId": "123",
  "name": {
    "givenName": "Test",
    "familyName": "Tester"
  },
  "active": true
} 

Update an existing user

PUT /api/scim/Users/965ffb27-6966-472d-a4b6-592bba3eeb82 HTTP/1.1
Host: app.sherpany.com
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer eyJhbG.eyJvaWQiO.a7jxyB_kMcmi5
 
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "test.tester@sherpany.com",
  "externalId": "123",
  "name": {
    "givenName": "Test",
    "familyName": "Tester II"
  },
  "active": true
}

When to sync

It is recommended to sync individual Users right away when the changes happen. If that is not possible full sync can also be done periodically.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.