SCIM 2.0 : Initiation au standard [1/2]

Published in

Smile with WSO2

7 min readFeb 3, 2021

SCIM 2.0 est devenu ces dernières années le standard de référence pour échanger des données d’identités entre domaines et applications. Nous allons dans cette série comprendre ses principes et comment l’utiliser avec WSO2 Identity Server.

Cette série, “SCIM 2.0” est en 2 parties :
1. Initiation au standard
2. Usage avec WSO2 Identity Server [Bientôt]

Qu’est-ce que SCIM 2.0 ?

System for Cross-domain Identity Management, ou SCIM, est un standard qui vise à rendre inter-opérable et uniforme l’échange automatique d’information d’identité entre des systèmes. Il se base sur l’usage d’une API REST normalisée et extensible en JSON.

La première version, dépréciée depuis, a été publiée en 2011 par l’Open Web Foundation sous le nom Simple Cloud Identity Management (oui les mêmes initiales!)

Juste après sa publication le standard a été transféré à l’IETF et a changé de nom. En 2015 sort la version SCIM 2.0 avec la publication de 3 RFC:

Comment ça marche ?

Modèle d’objets

SCIM 2.0 est d’abord et avant tout basé sur la définition d’un modèle d’objets extensible dans la RFC 7643. Tous ces objets sont des Ressources qui sont gérés par un fournisseur de services et qui contiennent un ou plusieurs attributs.

Il définit dans son Core 2 types de ressources User et Group et une extension Enterprise User.

Chaque type de ressource peut correspondre à un ou plusieurs schémas contenant des attributs caractérisés comme suit :

Name : en CamelCase contenant lettres, chiffres et $_-
Required : si l’attribut est obligatoire
cannonicalValues : liste fini de type de valeur (work, home, mobile, etc.)
caseExact : sensible à la casse ou non
multiValued : mono ou multivalent
mutability : readOnly/readWrite/immutable/writeOnly
returned : always/never/default/request
uniqueness : none/server/global
referenceTypes : ressourceType/external/uri
type : string/boolean/decimal/integer/dateTime/binary/reference/complex

Chaque attribut peut être monovalent ou multivalent. Quand il est multivalent 2 représentations existe :

un tableau de primitive
un tableau d’attribut complexe

Par complexe SCIM 2.0 veut tout simplement dire un sous-attribut. Et oui, nous sommes dans une représentation JSON arborescente!

Exemple de structure pour un User:

{
     "schemas":
       ["urn:ietf:params:scim:schemas:core:2.0:User",
         "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],

     "id": "2819c223-7f76-453a-413861904646",
     "externalId": "701984",

     "userName": "bjensen@example.com",
     "name": {
       "formatted": "Ms. Barbara J Jensen, III",
       "familyName": "Jensen",
       "givenName": "Barbara",
       "middleName": "Jane",
       "honorificPrefix": "Ms.",
       "honorificSuffix": "III"
     },
     "phoneNumbers": [
        {
          "value": "555-555-5555",
          "type": "work"
        },
        {
          "value": "555-555-4444",
          "type": "mobile"
        }
     ],
     ...

     "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
       "employeeNumber": "701984",
       "costCenter": "4130",
       ...
     },

     "meta": {
       "resourceType": "User",
       "created": "2010-01-23T04:56:22Z",
       "lastModified": "2011-05-13T04:42:34Z",
       "version": "W\/\"3694e05e9dff591\"",
       "location":
         "https://example.com/v2/Users/2819c223-7f76-453a-413861904646"
     }
   }

Dans cette structure nous avons :

la liste des schémas applicables
des attributs communs
- id : identifiant unique de la ressource
- externalId : un identifiant unique extérieur au système
- meta : des méta-données sur la ressource
des attributs core, c’est-à-dire défini à la racine de l’arbre JSON et défini dans le schema urn:ietf:params:scim:schemas:core:2.0:*
des attributs d’extension, fonctionnant de manière additive ils s’ajoutent dans leur propre sous arbre JSON par exemple pour l’extension EnterpriseUser contenu dans la RCF 7643 urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

De la même manière pour les groupes nous avons:

{
     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
     "id": "e9e30dba-f08f-4109-8486-d5c6a331660a",
     "displayName": "Tour Guides",
     "members": [
       {
         "value": "2819c223-7f76-453a-919d-413861904646",
         "$ref":
   "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
         "display": "Babs Jensen"
       },
       {
         "value": "902c246b-6245-4190-8e05-00816be7344a",
         "$ref":
   "https://example.com/v2/Users/902c246b-6245-4190-8e05-00816be7344a",
         "display": "Mandy Pepperidge"
       }
     ],
     "meta": {
       "resourceType": "Group",
       "created": "2010-01-23T04:56:22Z",
       "lastModified": "2011-05-13T04:42:34Z",
       "version": "W\/\"3694e05e9dff592\"",
       "location":
   "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a"
     }

Découverte

SCIM 2.0 définissant un modèle d’objet personnalisable, à la carte et extensible, il implémente des outils de découverte pour faciliter son emploi.

2 ressources spécialisées permettent de répondre à cet objectif:

ResourceType permet d’obtenir la liste des types de ressources disponibles

Exemple de liste de type de ressources disponibles :

[{
     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
     "id": "User",
     "name": "User",
     "endpoint": "/Users",
     "description": "User Account",
     "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
     "schemaExtensions": [
       {
         "schema":
           "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
         "required": true
       }
     ],
     "meta": {
       "location": "https://example.com/v2/ResourceTypes/User",
       "resourceType": "ResourceType"
     }
    },
    {
     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
     "id": "Group",
     "name": "Group",
     "endpoint": "/Groups",
     "description": "Group",
     "schema": "urn:ietf:params:scim:schemas:core:2.0:Group",
     "meta": {
       "location": "https://example.com/v2/ResourceTypes/Group",
       "resourceType": "ResourceType"
     }
   }]

Schema : permet d’obtenir la définition exacte des schémas servis par le service

Exemple du schéma core User

[
  {
    "id" : "urn:ietf:params:scim:schemas:core:2.0:User",
    "name" : "User",
    "description" : "User Account",
    "attributes" : [
      {
        "name" : "userName",
        "type" : "string",
        "multiValued" : false,
        "description" : "Unique identifier for the User, typically
used by the user to directly authenticate to the service provider.
Each User MUST include a non-empty userName value.  This identifier
MUST be unique across the service provider's entire set of Users.
REQUIRED.",
        "required" : true,
        "caseExact" : false,
        "mutability" : "readWrite",
        "returned" : "default",
        "uniqueness" : "server"
      },
      {
        "name" : "name",
        "type" : "complex",
        "multiValued" : false,
        "description" : "The components of the user's real name.
Providers MAY return just the full name as a single string in the
formatted sub-attribute, or they MAY return just the individual
component attributes using the other sub-attributes, or they MAY
return both.  If both variants are returned, they SHOULD be
describing the same name, with the formatted name indicating how the
component attributes should be combined.",
        "required" : false,
        "subAttributes" : [
          {
            "name" : "formatted",
            "type" : "string",
            "multiValued" : false,
            "description" : "The full name, including all middle
names, titles, and suffixes as appropriate, formatted for display
(e.g., 'Ms. Barbara J Jensen, III').",
            "required" : false,
            "caseExact" : false,
            "mutability" : "readWrite",
            "returned" : "default",
            "uniqueness" : "none"
          },

Service Production Configuration permet de connaitre les fonctionnalités SCIM 2.0 supportées ou non par le service pour un client

Exemple de configuration

{
    "schemas":
      ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
    "documentationUri": "http://example.com/help/scim.html",
    "patch": {
      "supported":true
    },
    "bulk": {
      "supported":true,
      "maxOperations":1000,
      "maxPayloadSize":1048576
    },
    "filter": {
      "supported":true,
      "maxResults": 200
    },
    "changePassword": {
      "supported":true
    },
    "sort": {
      "supported":true
    },
    "etag": {
      "supported":true
    },
    "authenticationSchemes": [
      {
        "name": "OAuth Bearer Token",
        "description":
          "Authentication scheme using the OAuth Bearer Token Standard",
        "specUri": "http://www.rfc-editor.org/info/rfc6750",
        "documentationUri": "http://example.com/help/oauth.html",
        "type": "oauthbearertoken",
        "primary": true
      },

      {
        "name": "HTTP Basic",
        "description":
          "Authentication scheme using the HTTP Basic Standard",
        "specUri": "http://www.rfc-editor.org/info/rfc2617",
        "documentationUri": "http://example.com/help/httpBasic.html",
        "type": "httpbasic"
       }
    ],
    "meta": {
      "location": "https://example.com/v2/ServiceProviderConfig",
      "resourceType": "ServiceProviderConfig",
      "created": "2010-01-23T04:56:22Z",
      "lastModified": "2011-05-13T04:42:34Z",
      "version": "W\/\"3694e05e9dff594\""
    }
  }

Protocole

Le protocole SCIM 2.0, défini dans la RFC 7644, est basé sur HTTP et implémente les concepts REST.

Il ne définit pas de moyen d’authentification et autorisation et laisse libre le choix à l’implémentation d’une solution.

Les endpoints mis à disposition de base sont:

/Users : ressource User
/Groups : ressource Group
/Me : ressource User, personne réalisant l’appel
/ServiceProviderConfig : configuration du service SCIM 2.0
/ResourceTypes : types de ressources exposées
/Schemas : schémas supportés
/Bulk : opérations en masse
[prefix]/.search : recherche

Pour chaque ressource les opérations suivantes sont disponibles:

Création : POST https://example.com/{v}/{Resources}
Lecture : GET https://example.com/{v}/{Resources}/{id}?ﬁlter={attribute}{op}{value}&sortBy={attributeName}&sortOrder={ascending|descending}
Remplacement : PUT https://example.com/{v}/{Resources}/{id}
Mise à jour : PATCH https://example.com/{v}/{Resources}/{id}
Suppression : DELETE https://example.com/{v}/{Resources}/{id}
Opérations en masse : POST https://example.com/{v}/Bulk

Exemple d’appel de création d’un utilisateur:

POST /Users  HTTP/1.1
   Host: example.com
   Accept: application/scim+json
   Content-Type: application/scim+json
   Authorization: Bearer h480djs93hd8
   Content-Length: ...

   {
     "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
     "userName":"bjensen",
     "externalId":"bjensen",
     "name":{
       "formatted":"Ms. Barbara J Jensen III",
       "familyName":"Jensen",
       "givenName":"Barbara"
     }
   }HTTP/1.1 201 Created
   Content-Type: application/scim+json
   Location:
    https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
   ETag: W/"e180ee84f0671b1"

   {
     "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
     "id":"2819c223-7f76-453a-919d-413861904646",
     "externalId":"bjensen",
     "meta":{
       "resourceType":"User",
       "created":"2011-08-01T21:32:44.882Z",
       "lastModified":"2011-08-01T21:32:44.882Z",
       "location":
   "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
       "version":"W\/\"e180ee84f0671b1\""
     },
     "name":{
       "formatted":"Ms. Barbara J Jensen III",
       "familyName":"Jensen",
       "givenName":"Barbara"
     },
     "userName":"bjensen"

Exemple de requête d’ajout d’un utilisateur à un groupe:

{ "schemas":
       ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
     "Operations":[
       {
        "op":"add",
        "path":"members",
        "value":[
         {
           "display": "Babs Jensen",
           "$ref":
   "https://example.com/v2/Users/2819c223...413861904646",
           "value": "2819c223-7f76-453a-919d-413861904646"
         }
        ]
       },
       ... + additional operations if needed ...
     ]
   }

Qui l’utilise?

SCIM 2.0 devient le standard du marché pour échanger des identités entre domaines et services. La version 1 et les standards SPML, Portable Contact ou vCards sont en voie de disparition. LDAP est parfois comparé à tort comme un concurrent alors qu’il traite d’une autre problématique.

SCIM 2.0 est implémenté dans tous les IAMs sérieux du marché (WSO2 IS, Ping Identity, Gluu, Okta, SailPoint, etc.) et est également implémenté par des services SaaS (Salesforce, Office 365, G Suite, Dropbox, etc.)

Quelles sont ses limites?

SCIM 2.0 est le premier protocole qui a su fédérer et a été réellement implémenté par la communauté. Il a su surfer sur le dévelopment des services cloud mais pour fédérer autant d’acteurs des compromis ont dû être fait.

Sa volonté de répondre à tous les besoins est sa principale force et sa principale faiblesse. Au final chaque service implémente son propre sous-standard et configuration. Il est donc impossible d’utiliser un client complètement générique.
Son modèle d’extension additif facilite son traitement, mais comme il n’accepte pas l’héritage, des informations connexes peuvent se retrouver à plusieurs endroits différents, ne facilitant pas son usage
Les paramètres d’attributs, de tri/filtrage, et pagination, sont extrêmement dépendants des capacités de requêtage des annuaires sous-jacents. Par exemple les services LDAP ne savent pas paginer.
L’usage du format en vogue JSON facilite son usage au détriment des performances. Ce format est verbeux et son concept d’encapsulation détériore la capacité à traiter des données en masse.

Dans le prochain billet nous découvrirons comment WSO2 implémente ce standard dans WSO2 Identity Server et comment nous pouvons l’utiliser.