Aperçu
Le système de gestion des identités interdomaines (SCIM, System for Cross-Domain Identity Management) est une API standard dédiée à l'automatisation du provisionnement/déprovisionnement d'utilisateurs et de groupes, ainsi qu'à la mise à jour des données d'utilisateurs et de groupes auprès du fournisseur d'identité (IdP) du client dans le compte Udemy Business. SCIM est pris en charge par un certain nombre de fournisseurs d'identité comme Okta, Azure AD et OneLogin. Vous pouvez aussi utiliser l'API SCIM Udemy Business pour d'autres IdP ou vos propres outils.
Si votre organisation utilise l'un des IdP suivants, consultez plutôt nos guides ci-dessous pour configurer SCIM :
- Configuration du provisionnement SCIM avec Okta
- Configuration du provisionnement SCIM avec Azure Active Directory (AD)
- Configuration du provisionnement SCIM avec OneLogin
SCIM utilise une API REST normalisée avec des données au format JSON. Udemy Business prend en charge la version 2.0 de la norme SCIM. L'API est disponible pour tous les clients disposant de l'abonnement d'entreprise.
L'API SCIM Udemy Business prend en charge les fonctionnalités suivantes :
- Provisionnement des utilisateurs
- Déprovisionnement des utilisateurs (désactivation)
- Modification des adresses e-mail
- Modification des détails utilisateur
- Provisionnement des groupes
- Ajout/suppression d'utilisateurs des groupes
Description du protocole SCIM
Le protocole SCIM est un protocole REST d'application pour le provisionnement et la gestion des données d'identification sur le Web. C'est un protocole de type client-serveur, où le client est le fournisseur d'identité (IdP) et le serveur est Udemy Business.
Le flux de base est le suivant :
- Lorsque l'accès à Udemy Business est octroyé à l'utilisateur par le client, l'IdP nous envoie une demande pour vérifier si cet utilisateur existe dans notre base de données. Le client émet une demande de recherche d'utilisateur par attribut, par exemple, avec un nom d'utilisateur ou une adresse e-mail.
- Si l'utilisateur n'existe pas, l'IdP envoie une demande de création d'utilisateur.
- Si l'utilisateur existe, l'IdP envoie une demande de mise à jour pour l'utilisateur.
- Lorsque l'accès à Udemy Business est révoqué, l'IdP nous envoie une demande de désactivation de l'utilisateur de notre base de données.
- L'IdP peut également envoyer des demandes de modification des détails de l'utilisateur.
Comment accéder à l'API ?
Pour obtenir les informations d'identification d'autorisation pour vous connecter à l'API SCIM, vous devez configurer l'intégration SCIM via la page Gérer -> Paramètres -> Provisionnement (SCIM) dans le compte Udemy Business. Seuls les administrateurs ont accès à cette page.
Cliquez sur Commencer la configuration.
À l'étape suivante, sélectionnez Choisir un fournisseur, puis Personnaliser.
Cliquez sur Générer le jeton.
Sur cet écran, cliquez sur Copier afin de copier le jeton Bearer dans le presse-papiers.
Vous devez inclure l'en-tête HTTP Autorisation avec le jeton Bearer dans vos demandes, par exemple :
GET /scim/v2/Users HTTP/1.1
Hôte : myorganization.udemy.com
Accepter : application/scim+json
Autorisation : Bearer <entrez votre jeton Bearer ici>
Content-Type: application/scim+json
L'API SCIM Udemy Business utilise le protocole HTTP et n'est disponible qu'avec une connexion HTTPS sécurisée.
L'URL de base pour l'API est la suivante : https://<organization>.udemy.com/scim/v2/.
Si vous développez une application qui doit interagir avec l'API SCIM Udemy Business, nous vous recommandons de vous reporter aux RFC SCIM incluses à la fin de ce document. L'implémentation de l'API SCIM Udemy Business est conforme à la norme.
Adresses d'API SCIM
Adresses d'informations
Ces adresses correspondent à des informations et servent à configurer les clients. L'authentification n'est pas nécessaire pour y accéder, vous n'avez donc pas besoin d'inclure l'en-tête Autorisation lors de l'accès à ces adresses.
GET /ServiceProviderConfig
Renvoie des détails sur l'implémentation SCIM Udemy Business, y compris les méthodes prises en charge.
GET /Schemas
Renvoie des informations sur les schémas que notre implémentation SCIM prend en charge. Les schémas pris en charge sont Utilisateurs et Groupes.
GET /Schemas/Users
Renvoie tous les attributs que nous prenons en charge pour les ressources Utilisateur.
GET /Schemas/Groups
Renvoie tous les attributs que nous prenons en charge pour les ressources Groupe.
Adresses d'utilisateur
Ces adresses permettent de répertorier les utilisateurs, de filtrer par attributs, d'ajouter de nouveaux utilisateurs, de mettre à jour les informations sur les utilisateurs ou de désactiver/anonymiser les utilisateurs. N'oubliez pas que vous n'aurez accès qu'aux utilisateurs qui ont été créés à l'aide de l'API SCIM, les utilisateurs créés dans Udemy Business ne seront pas disponibles, à moins de les rapprocher via SCIM. Vous trouverez plus de détails sur le rapprochement ci-dessous.
Attributs pris en charge
Attribut SCIM | Requis ? | Description |
emails[type=”work”]]['value’] | Oui | E-mail de l'utilisateur. Doit être unique |
userName | Oui | Nom d'utilisateur provenant de l'IdP. Doit être unique. |
segments | Oui | Indicateur de désactivation/réactivation des utilisateurs |
externalId | Oui | ID externe de l'utilisateur provenant de l'IdP. Doit être unique. |
urn:ietf:params:scim:schemas:extension: enterprise:2.0:User:employeeNumber |
Oui | Renvoie le champ employeeNumber depuis EnterpriseSchema et le stocke en tant que champ external_id |
name.givenName | Non | Prénom de l'utilisateur. Même s'ils ne sont pas obligatoires, nous vous recommandons de toujours spécifier ces attributs, car cela facilite l'identification des utilisateurs. |
name.familyName | Non | Nom de famille de l'utilisateur. Même s'ils ne sont pas obligatoires, nous vous recommandons de toujours spécifier ces attributs, car cela facilite l'identification des utilisateurs. |
name, { givenName, familyName } | Non | Prénom et nom de famille de l'utilisateur. Même s'ils ne sont pas obligatoires, nous vous recommandons de toujours spécifier ces attributs, car cela facilite l'identification des utilisateurs. |
title | Non | Intitulé du poste de l'utilisateur, par exemple « Ingénieur sénior » |
groupes |
Non | Groupe SCIM auquel l'utilisateur appartient |
Si vous spécifiez d'autres attributs que ceux indiqués dans cette liste, ils seront ignorés.
Lorsque SCIM est activé, Udemy suit le protocole SCIM pour le mappage d'attributs via SAML. Les groupes n'étant pas un attribut utilisateur SCIM, ils ne sont pas transmis via SAML si vous avez précédemment mappé l'attribut dans le cadre d'une configuration SAML uniquement.
GET /Users
Renvoie une liste paginée d'utilisateurs, avec, par défaut, 12 utilisateurs par page. Vous pouvez spécifier les paramètres count et startIndex pour paginer l'ensemble des résultats. Par exemple :
GET /scim/v2/Users?startIndex=1&count=100 HTTP/1.1
Hôte : myorganization.udemy.com
Accepter : application/scim+json
Autorisation : Bearer <entrez votre jeton Bearer ici>
- startIndex est l'index de base 1 du premier résultat dans l'ensemble actuel des résultats de la liste (décalage)
- count correspond au nombre de ressources renvoyées dans une page de réponse de liste (limite). Vous pouvez extraire 1 000 utilisateurs maximum par demande. Si cet élément est omis, la valeur par défaut est 12.
GET /Users?filter=
Cette adresse permet de filtrer les utilisateurs par attributs spécifiques. Par exemple, il est possible d'effectuer une recherche par attribut userName :
GET /Users?filter=userName eq "gloria.graynor”
Dans l'exemple ci-dessus, vous devez encoder les paramètres d'URL de sorte que l'URL ressemble à ce qui suit :
GET /Users?filter=userName%20eq%20%22gloria.graynor%22
Cette opération renvoie la liste des ressources utilisateur. S'il n'y a pas de résultat, une liste vide est renvoyée.
Les filtres pris en charge sont les suivants :
- userName
- externalID
- emails[type eq=”work”]
- groupes
Les opérateurs pris en charge sont les suivants :
- et
- eq
Réponse :
- Code d'état HTTP 200 avec la liste des entités en cas de réussite
- Code d'état HTTP 501 si un filtre non pris en charge a été fourni
POST /Users
Cette adresse permet de créer (provisionner) de nouveaux utilisateurs dans Udemy Business.
La réponse contient un attribut id à utiliser lorsque cet utilisateur est référencé dans toutes les demandes ultérieures.
Remarque :
- Les nouveaux utilisateurs créés de cette façon n'utiliseront pas de licence tant qu'ils ne se seront pas connectés pour la première fois.
-
S'il existait une invitation en attente pour cet utilisateur, elle est utilisée à ce stade.
L'utilisateur est ajouté à des groupes et il reçoit les affectations de rôle/cours appropriées selon les spécifications de l'invitation. - Si vous tentez de créer un utilisateur qui existe déjà dans Udemy Business, cet utilisateur est alors géré par SCIM (s'affiche avec une petite icône de lien dans les pages Gérer les utilisateurs). Le statut et l'utilisation de licence de cet utilisateur ne seront pas modifiés. Si l'utilisateur était actif, il le restera, et si l'utilisateur était inactif, il le restera également.
Réponse :
- Code d'état HTTP 201 et la ressource de l'utilisateur en cas de réussite
- Code d'état HTTP 409 si un membre ayant le même attribut userName existe déjà dans l'organisation
- Code d'état HTTP 400 avec les détails de l'erreur dans le corps de la réponse si la demande n'a pas été validée
GET /Users/<id>
Cette adresse permet d'extraire les détails relatifs à l'utilisateur spécifié. Le paramètre id dans la demande ci-dessus est un identifiant unique qui a été renvoyé lorsque l'utilisateur a été créé à l'aide de SCIM ou lors de la création de la liste de tous les utilisateurs existants.
Réponse :
- Code d'état HTTP 200 et la ressource de l'utilisateur en cas de réussite
- Code d'état HTTP 404 si l'utilisateur est introuvable
PUT /Users/<id>
Cette adresse permet de remplacer (écraser) les détails utilisateur dans Udemy Business. S'il est spécifié, l'attribut active permet de désactiver ou de réactiver l'utilisateur.
Réponse :
- Code d'état HTTP 200 et la ressource d'utilisateur mise à jour
- Code d'état HTTP 404 si l'utilisateur n'existe pas.
- Code d'état HTTP 400 en cas de tentative de désactivation d'un propriétaire d'organisation.
PATCH /Users/<id>
Cette adresse permet d'effectuer des mises à jour partielles des détails de l'utilisateur dans notre système, ce qui signifie que vous pouvez l'utiliser pour modifier seulement certains attributs de l'utilisateur. C'est donc l'inverse de PUT, qui remplace l'utilisateur dans son intégralité.
Elle peut contenir l'attribut active, qui désactive et réactive l'utilisateur.
- Le corps de chaque demande DOIT contenir l'attribut « schemas » avec la valeur d'URI suivante : urn:ietf:params:scim:api:messages:2.0:PatchOp.
- Le corps d'une demande PATCH HTTP doit contenir l'attribut « Operations », dont la valeur est une série d'opérations PATCH. Chaque objet d'opération PATCH DOIT avoir exactement un membre « op », dont la valeur indique l'opération à effectuer, et PEUT avoir « add », « remove » ou « replace ».
- L'attribut « path » peut être vide. Dans ce cas, « value » doit être un dictionnaire au format {“path”: “value”}.
Réponse :
- Code d'état HTTP 200 et la ressource de l'utilisateur mise à jour en cas de réussite
- Code d'état HTTP 404 si l'utilisateur est introuvable
- Code d'état HTTP 400 en cas de tentative de désactivation d'un propriétaire d'organisation ou en cas d'opération non valide.
Adresses de groupe
Attributs pris en charge
Attribut SCIM |
Requis ? |
Description |
displayName |
Oui |
Titre du groupe. Doit être unique parmi tous les groupes Udemy Business. |
externalId |
Non |
ID externe du groupe provenant du fournisseur d'identité. |
Si vous spécifiez d'autres attributs que ceux indiqués dans cette liste, ils seront ignorés.
GET /Groups
Cette adresse permet d'obtenir la liste de tous les groupes provisionnés. Indiquez les paramètres de chaîne de requête startIndex et count afin de paginer les résultats.
N'oubliez pas que seuls les groupes créés à l'aide de SCIM seront renvoyés. Les groupes créés dans Udemy Business ne seront pas renvoyés.
GET /Groups?filter=
Cette adresse permet de filtrer les groupes par attributs spécifiques. Par exemple, il est possible d'effectuer une recherche par attribut displayName :
GET /Groups?filter=displayName eq "Marketing”
Cette opération renvoie la liste des ressources de groupe. S'il n'y a pas de résultat, une liste vide est renvoyée.
Vous devez encoder les paramètres d'URL pour que la demande ressemble à ce qui suit :
GET /Groups?filter=displayName%20eq%20%22Marketing%22
Les filtres pris en charge sont les suivants :
- displayName
- externalId
- ID
- member.value
Les opérateurs pris en charge sont les suivants :
- et
- eq
Réponse :
- Code d'état HTTP 200 avec la liste des entités en cas de réussite
- Code d'état HTTP 501 si un filtre non pris en charge est utilisé
POST /Groups
Cette adresse permet de créer (provisionner) de nouveaux groupes dans Udemy Business.
Réponse :
- Code d'état HTTP 409. Si un groupe provisionné portant le même nom existe déjà dans l'organisation, nous renvoyons le code 409 (Conflit) avec un code d'erreur scimType relatif à l'unicité.
- Lorsque le groupe a été créé avec succès, nous renvoyons la représentation complète du groupe avec le code d'état HTTP 201 (Créé) avec l'en-tête Location qui contient l'URL de la ressource de groupe créée.
GET /Groups/<id>
Cette adresse permet d'extraire les détails du groupe à partir d'Udemy Business.
Réponse :
- Code d'état HTTP 200 et une ressource de groupe
- Code d'état HTTP 404 si le groupe est introuvable
PUT /Groups/<id>
Cette adresse permet de remplacer les détails du groupe dans Udemy Business.
Réponse :
- Code d'état HTTP 200 et la ressource de groupe mise à jour
- Code d'état HTTP 404 si le groupe n'existe pas.
PATCH /Groups/<id>
Cette adresse permet d'effectuer des mises à jour partielles des détails du groupe dans Udemy Business.
L'adresse PATCH est plus complexe à utiliser que d'autres, car elle prend en charge différents types d'opérations (qui peuvent être combinées) :
- L'opération replace modifie la valeur spécifiée. Dans notre cas, il s'agit des membres ou du nom de groupe.
- L'opération remove supprime une membre du groupe.
- L'opération add ajoute des membres au groupe.
Les règles sont les suivantes :
- Nous ne supprimons jamais les membres non provisionnés du groupe (en cas d'opération « replace » sur des membres, par exemple).
- Une demande PATCH, quel que soit le nombre d'opérations qu'elle intègre, DOIT être traitée comme atomique.
Les validations d'entrée sont les suivantes :
- Le corps de chaque demande DOIT contenir l'attribut « schemas » avec la valeur d'URI suivante : urn:ietf:params:scim:api:messages:2.0:PatchOp.
- Le corps d'une demande PATCH HTTP doit contenir l'attribut « Operations », dont la valeur est une série d'opérations PATCH. Chaque objet d'opération PATCH DOIT avoir exactement un membre « op », dont la valeur indique l'opération à effectuer, et PEUT avoir « add », « remove » ou « replace ».
- L'attribut « path » peut être vide. Dans ce cas, « value » doit être un dictionnaire au format {“path”: “value”}.
- Pour une opération « Remove », le chemin « members » est requis.
- Pour une opération « Add », le chemin « members » ou « externalId » doit être présent.
- Pour une opération « Replace », le chemin « members » doit être présent. Si ce n'est pas le cas, cela signifie que nous remplaçons les détails du groupe (comme le nom du groupe), mais pas les membres.
Remarque :
- L'affectation ou l'annulation de l'affectation d'utilisateurs à un groupe s'effectue de manière asynchrone, donc les modifications ne sont pas visibles immédiatement dans Udemy Business.
- Nous ne prenons pas en charge les groupes imbriqués, ils sont donc ignorés lors de cette demande.
Réponse :
- Code d'état HTTP 204 si l'opération a réussi.
- Code d'état HTTP 404 si le groupe n'existe pas.
- Code d'état HTTP 404 avec les détails d'erreur en cas de tentative d'affectation d'un groupe à un utilisateur qui n'est pas membre de l'organisation.
- Code d'état HTTP 400 avec les détails de l'erreur dans le corps de la réponse si la demande n'a pas été validée
DELETE /Groups/<id>
Cette adresse permet de supprimer ou de déprovisionner un groupe dans Udemy Business. La suppression d'un groupe n'entraîne pas la suppression des utilisateurs qui s'y trouvent. Les utilisateurs seront simplement retirés du groupe supprimé.
Les règles sont les suivantes :
- Si le groupe contient des membres non provisionnés, supprimez les utilisateurs provisionnés du groupe et supprimez l'enregistrement « OrganizationSCIMGroup ».
Réponse :
- Code d'état HTTP 204 si l'opération a réussi.
- Code d'état HTTP 404 si le groupe n'existe pas.
Informations supplémentaires
- Présentation de SCIM : http://www.simplecloud.info
- RFC 7642, SCIM - Definitions, Overview, Concepts, and Requirements : https://tools.ietf.org/pdf/rfc7642.pdf
- RFC 7643, SCIM - Core Schema : https://tools.ietf.org/pdf/rfc7643.pdf
- RFC 7644, SCIM - Protocol : https://tools.ietf.org/pdf/rfc7644.pdf