Partager via

Tutoriel : développer et planifier l’approvisionnement d’un point de terminaison SCIM dans Microsoft Entra ID

  • Article

En tant que développeur d’applications, vous pouvez utiliser l’API de gestion des utilisateurs SCIM (System for Cross-Domain Identity Management) pour activer le provisionnement automatique des utilisateurs et des groupes entre votre application et Microsoft Entra ID. Cet article explique comment créer un point de terminaison SCIM et l’intégrer au service de provisionnement Microsoft Entra. La spécification SCIM fournit un schéma utilisateur commun pour l’approvisionnement. Utilisé avec des normes de fédération telles que SAML ou OpenID Connect, SCIM offre aux administrateurs une solution de bout en bout, fondée sur des normes, pour la gestion des accès.

Approvisionnement de Microsoft Entra ID vers une application avec SCIM

SCIM 2.0 est une définition normalisée de deux points d'extrémité : un point d'extrémité /Users et un point d'extrémité/Groups. Il utilise les points de terminaison courants de l'API REST pour créer, mettre à jour et supprimer des objets. Le SCIM consiste en un schéma prédéfini pour les attributs communs tels que le nom de groupe, le nom d'utilisateur, le prénom, le nom de famille et l'adresse électronique.

Les applications proposant une API REST SCIM 2.0 peuvent réduire ou éliminer les difficultés liées à l’utilisation d’une API de gestion des utilisateurs propriétaires. Par exemple, tout client SCIM conforme sait comment effectuer une requête HTTP POST d’objet JSON sur le point de terminaison /Users pour créer une entrée d’utilisateur. Sans devoir utiliser une API légèrement différente pour les mêmes actions de base, les applications conformes à la norme SCIM peuvent instantanément tirer parti des clients, des outils et du code existants.

Le schéma d’objet utilisateur standard et les API REST de gestion définies dans SCIM 2.0 (RFC 7642, 7643, 7644) permettent aux fournisseurs d’identité et aux applications de s’intégrer plus facilement entre eux. Les développeurs d’applications qui créent un point de terminaison SCIM peuvent s’intégrer à n’importe quel client conforme à SCIM sans avoir à effectuer de travail personnalisé.

Pour automatiser l’approvisionnement d’une application, il nécessite la création et l’intégration d’un point de terminaison SCIM qui est accessible par le service d’approvisionnement Microsoft Entra. Effectuez les étapes suivantes pour commencer à provisionner des utilisateurs et des groupes dans votre application.

  1. Concevoir votre schéma d'utilisateurs et de groupes - Identifiez les objets et les attributs de l'application pour déterminer comment ils correspondent au schéma d'utilisateurs et de groupes pris en charge par l'implémentation SCIM de Microsoft Entra.

  2. Comprendre l’implémentation SCIM de Microsoft Entra : découvrez comment le service d’approvisionnement Microsoft Entra est implémenté pour modéliser la gestion et les réponses de vos demandes de protocole SCIM.

  3. Construire un point de terminaison SCIM - Un point de terminaison doit être compatible avec SCIM 2.0 pour s'intégrer au service de provisionnement Microsoft Entra. Vous pouvez utiliser des bibliothèques Microsoft Common Language Infrastructure (CLI) et des exemples de code pour créer votre point de terminaison. Ces exemples sont fournis à des fins de référence et de test uniquement. Nous vous déconseillons de les utiliser comme des dépendances dans votre application de production.

  4. Intégrer votre terminal SCIM avec le service de provisionnement Microsoft Entra. Microsoft Entra ID prend en charge plusieurs applications tierces qui implémentent SCIM 2.0. Si vous utilisez l’une de ces applications, vous pouvez rapidement automatiser le provisionnement et le déprovisionnement des utilisateurs et des groupes.

  5. [Facultatif] Publiez votre application dans la galerie d’applications Microsoft Entra - facilitez la découverte de votre application et la configuration facile de l’approvisionnement.

Diagramme indiquant les étapes nécessaires à l’intégration d’un point de terminaison SCIM avec Microsoft Entra ID.

Concevoir votre schéma d'utilisateurs et de groupes

Chaque application nécessite des attributs différents pour créer un utilisateur ou un groupe. Commencez votre intégration en identifiant les objets (utilisateurs, groupes) et attributs (nom, responsable, fonction, etc.) nécessaires à votre application.

La norme SCIM définit un schéma pour la gestion des utilisateurs et des groupes.

Le schéma utilisateur core ne nécessite que trois attributs (tous les autres attributs sont facultatifs) :

  • id, identificateur défini par le fournisseur de services
  • userName, identificateur unique de l’utilisateur (mappe généralement au nom d’utilisateur principal Microsoft Entra)
  • meta, métadonnées en lecture seule gérées par le fournisseur de services

En plus du schéma utilisateur principal, la norme SCIM définit une extension utilisateur d'entreprise avec un modèle permettant d'étendre le schéma utilisateur pour répondre aux besoins de votre application.

Par exemple, si votre application nécessite à la fois l'adresse e-mail d'un utilisateur et le responsable de l'utilisateur, utilisez le schéma principal pour collecter l'adresse e-mail de l'utilisateur et le schéma de l'utilisateur d'entreprise pour collecter le responsable de l'utilisateur.

Pour concevoir votre schéma, effectuez les étapes suivantes :

  1. Répertoriez les attributs requis par votre application, puis catégorisez en tant qu’attributs nécessaires pour l’authentification (par exemple, loginName et e-mail). Les attributs sont nécessaires pour gérer le cycle de vie de l’utilisateur (par exemple, état/actif) et tous les autres attributs nécessaires pour que l’application fonctionne (par exemple, gestionnaire, balise).

  2. Vérifiez si ces attributs sont déjà définis dans le schéma utilisateur core ou le schéma utilisateur enterprise. Si ce n’est pas le cas, vous devez définir une extension pour le schéma utilisateur afin d’inclure les attributs manquants. Pour voir une extension utilisateur permettant de provisionner une tag d’utilisateur, consultez l’exemple.

  3. Mappez les attributs SCIM aux attributs d’utilisateur dans Microsoft Entra. Si l’un des attributs que vous avez définis dans votre point de terminaison SCIM n’a pas d’équivalent clair dans le schéma utilisateur Microsoft Entra, expliquez à l’administrateur de locataire comment étendre son schéma ou utiliser un attribut d’extension, comme indiqué dans l’exemple pour la propriété tags.

Le tableau suivant répertorie un exemple d’attributs requis :

Attribut/Exemple d’application obligatoire Attribut SCIM mappé Attribut Microsoft Entra mappé
loginName userName userPrincipalName
firstName name.givenName givenName
lastName name.familyName surName
workMail emails[type eq "work"].value Messagerie
manager manager manager
tag urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag extensionAttribute1
status active isSoftDeleted (valeur calculée non stockée sur l’utilisateur)

La charge utile JSON suivante montre un exemple de schéma SCIM :

{
     "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:CustomExtensionName:2.0:User"],
     "userName":"bjensen@testuser.com",
     "id": "48af03ac28ad4fb88478",
     "externalId":"bjensen",
     "name":{
       "familyName":"Jensen",
       "givenName":"Barbara"
     },
     "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
     "manager": "123456"
   },
     "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User": {
     "tag": "701984",
   },
   "meta": {
     "resourceType": "User",
     "created": "2010-01-23T04:56:22Z",
     "lastModified": "2011-05-13T04:42:34Z",
     "version": "W\/\"3694e05e9dff591\"",
     "location":
 "https://example.com/v2/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
   }
}

Remarque

En plus des attributs exigés par l’application, la représentation JSON contient également les attributs obligatoires id, externalId et meta.

Cela permet de les classer dans les catégories /User et /Group en vue de mapper les attributs utilisateur par défaut entre Microsoft Entra et le RFC SCIM. Pour plus d’informations, découvrez comment les attributs personnalisés sont mappés entre Microsoft Entra et votre point de terminaison SCIM.

Le tableau suivant présente un exemple d'attributs d'utilisateur :

Utilisateur Microsoft Entra urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
IsSoftDeleted active
department urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department
displayName displayName
employeeId urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber
Facsimile-TelephoneNumber phoneNumbers[type eq "fax"].value
givenName name.givenName
jobTitle title
mail emails[type eq "work"].value
mailNickName externalId
manager urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager
mobile phoneNumbers[type eq "mobile"].value
postalCode addresses[type eq "work"].postalCode
proxy-Addresses emails[type eq "other"].Value
physical-Delivery-OfficeName addresses[type eq "other"].Formatted
streetAddress addresses[type eq "work"].streetAddress
surname name.familyName
telephone-Number phoneNumbers[type eq "work"].value
user-PrincipalName userName

Le tableau suivant donne un exemple d'attributs de groupe :

Groupe Microsoft Entra urn:ietf:params:scim:schemas:core:2.0:Group
displayName displayName
membres membres
objectId externalId

Remarque

Il n’est pas nécessaire de prendre en charge à la fois les utilisateurs et les groupes, ou tous les attributs indiqués ici. Nous montrons simplement comment les attributs Microsoft Entra ID sont souvent mappés aux propriétés du protocole SCIM.

Plusieurs points de terminaison sont définis dans la RFC SCIM. Vous pouvez commencer avec le point de terminaison /User, puis développer à partir de celui-ci. Le tableau suivant répertorie certains points de terminaison SCIM :

Point de terminaison Description
/User Permet d’effectuer des opérations CRUD sur un objet utilisateur.
/Group Permet d’effectuer des opérations CRUD sur un objet groupe.
/Schemas L’ensemble des attributs pris en charge par chaque client et chaque fournisseur de services peut varier. Un fournisseur de services peut inclure name, title et emails, tandis qu’un autre fournisseur de services utilise name, title et phoneNumbers. Le point de terminaison /Schemas permet la découverte des attributs pris en charge.
/Bulk Les opérations en bloc vous permettent d’effectuer des opérations sur un grand nombre d’objets ressource à la fois (par exemple, pour mettre à jour les appartenances dans un grand groupe).
/ServiceProviderConfig Fournit des détails sur les fonctionnalités de la norme SCIM prises en charge, par exemple les ressources prises en charge et la méthode d’authentification.
/ResourceTypes Spécifie les métadonnées relatives à chaque ressource.

Remarque

Utilisez le point de terminaison /Schemas pour prendre en charge les attributs personnalisés. Vous pouvez également l’utiliser si votre schéma change fréquemment, car il permet à un client de récupérer automatiquement le schéma le plus à jour. Utilisez le point de terminaison /Bulk pour prendre en charge les groupes.

Comprendre l’implémentation SCIM de Microsoft Entra

Le service de provisionnement Microsoft Entra est conçu pour prendre en charge une API de gestion d’utilisateurs SCIM 2.0.

Important

La dernière mise à jour du comportement de l’implémentation SCIM de Microsoft Entra a été effectuée le 18 décembre 2018. Pour plus d’informations sur ce qui a changé, consultez Conformité au protocole SCIM 2.0 du service d’approvisionnement des utilisateurs Microsoft Entra.

Dans la spécification du protocole SCIM 2.0, votre application doit satisfaire aux conditions suivantes :

Condition requise Notes de référence (protocole SCIM)
Créer des utilisateurs, et facultativement des groupes Section 3.3
Modifier des utilisateurs ou des groupes avec des requêtes PATCH Section 3.5.2. La prise en charge garantit que les groupes et les utilisateurs sont provisionnés de manière performante.
Récupérer une ressource connue pour un utilisateur ou un groupe créé précédemment Section 3.4.1
Interroger des utilisateurs ou des groupes Section 3.4.2. Par défaut, les utilisateurs sont récupérés avec leur id et interrogés avec leurs username et externalId, et les groupes sont interrogés avec displayName.
Le filtre excludedAttributes=members lors de l’interrogation de la ressource de groupe Section 3.4.2.2.
Prendre en charge la création d’une liste d’utilisateurs et la pagination Section 3.4.2.4.
Suppression réversible d’un utilisateur active=false et restauration de l’utilisateur active=true. L’objet utilisateur doit être retourné dans une requête, que l’utilisateur soit actif ou non. La seule fois où l’utilisateur ne doit pas être retourné est lorsqu’il est supprimé définitivement de l’application.
Prendre en charge le point de terminaison /Schemas Section 7 Le point de terminaison de découverte de schéma est utilisé pour découvrir des attributs supplémentaires.
Accepter un jeton du porteur unique pour l’authentification et l’autorisation de Microsoft Entra ID dans votre application.

Suivez ces recommandations lors de l’implémentation d’un point de terminaison SCIM pour garantir la compatibilité avec Microsoft Entra ID :

Général :

  • id est une propriété obligatoire pour toutes les ressources. Chaque réponse qui retourne une ressource doit garantir que chaque ressource dispose de cette propriété, sauf pour ListResponse sans élément.
  • Les valeurs envoyées doivent être stockées dans le même format que celui dans lequel elles ont été envoyées. Les valeurs non valides doivent être rejetées avec un message d’erreur descriptif et exploitable. Aucune transformation de données ne doit se produire entre les données provenant de Microsoft Entra ID et celles stockées dans l’application SCIM. (par exemple. Un numéro de téléphone envoyé comme 55555555555 ne doit pas être enregistré/retourné sous la forme + 5 (555) 555-5555)
  • Il n’est pas nécessaire d’inclure la ressource entière dans la réponse PATCH.
  • N’exigez pas un respect de la casse pour les éléments structurels SCIM, en particulier pour les valeurs d’opération op PATCH, comme défini dans la section 3.5.2. Microsoft Entra ID émet les valeurs de op ainsi : Ajouter, Remplacer et Supprimer.
  • Microsoft Entra ID effectue des requêtes pour récupérer un utilisateur et un groupe aléatoires afin de vérifier que le point de terminaison et les informations d’identification sont valides. Cela est également effectué dans le cadre du flux Test Connection.
  • Prenez en charge HTTPS sur votre point de terminaison SCIM.
  • Les attributs complexes et à valeurs multiples personnalisés sont pris en charge, mais Microsoft Entra ID ne dispose pas de nombreuses structures de données complexes pour extraire des données dans ces cas. Les attributs nom/valeur peuvent facilement être mappés, mais le flux de données vers des attributs complexes avec au moins trois sous-attributs n’est pas pris en charge.
  • Les valeurs de sous-attribut « type » des attributs complexes à valeurs multiples doivent être uniques. Par exemple, il ne peut pas y avoir deux adresses e-mail différentes avec le sous-type « work ».
  • L’en-tête de toutes les réponses doit être de type « content » : application/scim+json

Récupération de ressources :

  • La réponse à une demande de requête/filtre doit toujours être ListResponse.
  • Microsoft Entra utilise uniquement les opérateurs suivants : eq, and
  • L'attribut sur lequel les ressources peuvent être interrogées doit être défini comme attribut correspondant sur l'application, voir Personnalisation des mappages d'attributs de provisionnement utilisateur.

/Users :

  • L’attribut de droit n’est pas pris en charge.
  • Tous les attributs pris en compte pour l’unicité de l’utilisateur doivent être utilisables dans le cadre d’une requête filtrée. (par exemple, si l’unicité de l’utilisateur est évaluée pour userName et emails[type eq "work"], un GET sur /Users avec un filtre doit permettre les requêtes userName eq "user@contoso.com" et emails[type eq "work"].value eq "user@contoso.com".

/Groups :

  • Les groupes sont facultatifs et uniquement pris en charge si l’implémentation SCIM prend en charge les requêtes PATCH.
  • Les groupes doivent avoir unicité sur la valeur « displayName » pour qu’ils correspondent à Microsoft Entra ID et à l’application SCIM. L'unicité n'est pas une exigence du protocole SCIM, mais une exigence pour l'intégration d'un point de terminaison SCIM avec Microsoft Entra ID.

/Schemas (découverte de schéma) :

  • Exemple de demande/réponse
  • La découverte de schéma est utilisée dans certaines applications de galerie. La découverte de schéma est la seule méthode utilisée pour ajouter des attributs supplémentaires au schéma d’une application SCIM de galerie existante. La découverte de schéma n’est actuellement pas prise en charge sur une application SCIM hors galerie personnalisée.
  • Si une valeur n’est pas présente, n’envoyez pas de valeurs Null.
  • Utilisez une casse mixte pour les valeurs de propriété (par exemple, readWrite).
  • Doit retourner une réponse de liste.
  • Le service de provisionnement Microsoft Entra effectue la requête /schemas lorsque vous enregistrez la configuration de provisionnement. La requête est également effectuée lorsque vous ouvrez la page de modification du provisionnement. Les autres attributs découverts sont présentés aux clients dans les mappages d’attributs sous la liste des attributs cibles. La découverte de schémas ne fait qu'entraîner l'ajout de nouveaux attributs cibles. Les attributs ne sont pas supprimés.

Approvisionnement et déprovisionnement d'utilisateurs

Le diagramme suivant montre les messages que Microsoft Entra ID envoie à un point de terminaison SCIM pour gérer le cycle de vie d'un utilisateur dans le magasin d'identité de votre application.

Diagramme qui montre la séquence de déprovisionnement des utilisateurs.

Approvisionnement et déprovisionnement de groupes

L’approvisionnement et le déprovisionnement de groupes sont facultatifs. Lorsqu'elle est mise en œuvre et activée, l'illustration suivante montre les messages que Microsoft Entra ID envoie à un point de terminaison SCIM pour gérer le cycle de vie d'un groupe dans le magasin d'identité de votre application. Ces messages diffèrent des messages concernant les utilisateurs de deux manières :

  • Les demandes d’extraction de groupes précisent que l’attribut des membres doit être exclu des ressources fournies en réponse à la demande.
  • Les requêtes permettant de déterminer si un attribut de référence a une certaine valeur sont des requêtes sur les attributs membres.

Le diagramme suivant montre la séquence de déprovisionnement de groupe :

Diagramme qui montre la séquence de déprovisionnement du groupe.

Demandes et réponses du protocole SCIM

Cet article fournit des exemples de demandes SCIM émises par le service d’approvisionnement Microsoft Entra et des exemples de réponses attendues. Pour de meilleurs résultats, vous devez coder votre application pour gérer ces demandes dans ce format et émettre les réponses attendues.

Important

Pour comprendre comment et quand le service de provisionnement d’utilisateurs de Microsoft Entra émet les opérations décrites dans l’exemple, consultez la section Cycles de provisionnement : cycle initial et cycle incrémentiel de l’article Fonctionnement du provisionnement.

Opérations utilisateur

Opérations de groupe

Découverte de schéma

Opérations utilisateur

  • Utilisez des attributs userName ou emails[type eq "work"] pour interroger les utilisateurs.

Create User

Requête

POST /Users

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
    "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
    "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "active": true,
    "emails": [{
        "primary": true,
        "type": "work",
        "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com"
    }],
    "meta": {
        "resourceType": "User"
    },
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName"
    },
    "roles": []
}
response

HTTP/1.1 201 Created

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "48af03ac28ad4fb88478",
    "externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Obtenir un utilisateur

Requête

GET /Users/5d48a0a8e9f04aa38008

Réponse (Utilisateur trouvé)

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "5d48a0a8e9f04aa38008",
    "externalId": "58342554-38d6-4ec8-948c-50044d0a33fd",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
        "type": "work",
        "primary": true
    }]
}
Requête

GET /Users/5171a35d82074e068ce2

Réponse (Utilisateur non trouvé. Le détail n'est pas requis, seulement le statut).

HTTP/1.1 404 introuvable

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "status": "404",
    "detail": "Resource 23B51B0E5D7AE9110A49411D@7cca31655d49f3640a494224 not found"
}

Obtenir un utilisateur par requête

Requête

GET /Users?filter=userName eq "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee"

Response

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "Resources": [{
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
        "id": "2441309d85324e7793ae",
        "externalId": "7fce0092-d52e-4f76-b727-3955bd72c939",
        "meta": {
            "resourceType": "User",
            "created": "2018-03-27T19:59:26.000Z",
            "lastModified": "2018-03-27T19:59:26.000Z"
            
        },
        "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "name": {
            "familyName": "familyName",
            "givenName": "givenName"
        },
        "active": true,
        "emails": [{
            "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
            "type": "work",
            "primary": true
        }]
    }],
    "startIndex": 1,
    "itemsPerPage": 20
}

Obtenir un utilisateur par requête - sans résultat

Requête

GET /Users?filter=userName eq "non-existent user"

response

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 0,
    "Resources": [],
    "startIndex": 1,
    "itemsPerPage": 20
}

Mettre à jour un utilisateur [Propriétés à plusieurs valeurs]

Requête

PATCH /Users/6764549bef60420686bc HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
            {
            "op": "Replace",
            "path": "emails[type eq \"work\"].value",
            "value": "updatedEmail@microsoft.com"
            },
            {
            "op": "Replace",
            "path": "name.familyName",
            "value": "updatedFamilyName"
            }
    ]
}
response

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "6764549bef60420686bc",
    "externalId": "6c75de36-30fa-4d2d-a196-6bdcdb6b6539",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "name": {
        "formatted": "givenName updatedFamilyName",
        "familyName": "updatedFamilyName",
        "givenName": "givenName"
    },
    "active": true,
    "emails": [{
        "value": "updatedEmail@microsoft.com",
        "type": "work",
        "primary": true
    }]
}

Mettre à jour un utilisateur [Propriétés à une seule valeur]

Requête

PATCH /Users/5171a35d82074e068ce2 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Replace",
        "path": "userName",
        "value": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com"
    }]
}
response

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "5171a35d82074e068ce2",
    "externalId": "aa1eca08-7179-4eeb-a0be-a519f7e5cd1a",
    "meta": {
        "resourceType": "User",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
        
    },
    "userName": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
        "type": "work",
        "primary": true
    }]
}

Désactiver l’utilisateur

Requête

PATCH /Users/5171a35d82074e068ce2 HTTP/1.1

{
    "Operations": [
        {
            "op": "Replace",
            "path": "active",
            "value": false
        }
    ],
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ]
}
response
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "CEC50F275D83C4530A495FCF@834d0e1e5d8235f90a495fda",
    "userName": "deanruiz@testuser.com",
    "name": {
        "familyName": "Harris",
        "givenName": "Larry"
    },
    "active": false,
    "emails": [
        {
            "value": "gloversuzanne@testuser.com",
            "type": "work",
            "primary": true
        }
    ],
    "addresses": [
        {
            "country": "ML",
            "type": "work",
            "primary": true
        }
    ],
    "meta": {
        "resourceType": "Users",
        "location": "/scim/5171a35d82074e068ce2/Users/CEC50F265D83B4530B495FCF@5171a35d82074e068ce2"
    }
}

Supprimer l'utilisateur

Requête

DELETE /Users/5171a35d82074e068ce2 HTTP/1.1

response

HTTP/1.1 204 No Content

Opérations de groupe

  • Des groupes sont créés avec une liste de membres vide.
  • Utilisez l’attribut displayName pour interroger les groupes.
  • La mise à jour de la requête PATCH de groupe doit renvoyer HTTP 204 No Content dans la réponse. Il n’est pas conseillé de renvoyer un corps avec une liste de tous les membres.
  • Il n’est pas nécessaire de prendre en charge le renvoi de tous les membres du groupe.

Créer un groupe

Requête

POST /Groups HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group", "http://schemas.microsoft.com/2006/11/ResourceManagement/ADSCIM/2.0/Group"],
    "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
    "displayName": "displayName",
    "meta": {
        "resourceType": "Group"
    }
}
response

HTTP/1.1 201 Created

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "927fa2c08dcb4a7fae9e",
    "externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
    "meta": {
        "resourceType": "Group",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
        
    },
    "displayName": "displayName",
    "members": []
}

Obtenir un groupe

Requête

GET /Groups/40734ae655284ad3abcc?excludedAttributes=members HTTP/1.1

response

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "id": "40734ae655284ad3abcc",
    "externalId": "60f1bb27-2e1e-402d-bcc4-ec999564a194",
    "meta": {
        "resourceType": "Group",
        "created": "2018-03-27T19:59:26.000Z",
        "lastModified": "2018-03-27T19:59:26.000Z"
    },
    "displayName": "displayName",
}

Obtenir un groupe par displayName

Requête

GET /Groups?excludedAttributes=members&filter=displayName eq "displayName" HTTP/1.1

Response

HTTP/1.1 200 OK

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "totalResults": 1,
    "Resources": [{
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
        "id": "8c601452cc934a9ebef9",
        "externalId": "0db508eb-91e2-46e4-809c-30dcbda0c685",
        "meta": {
            "resourceType": "Group",
            "created": "2018-03-27T22:02:32.000Z",
            "lastModified": "2018-03-27T22:02:32.000Z",
            
        },
        "displayName": "displayName",
    }],
    "startIndex": 1,
    "itemsPerPage": 20
}

Mettre à jour un groupe [Attributs non membre]

Requête

PATCH /Groups/fa2ce26709934589afc5 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Replace",
        "path": "displayName",
        "value": "1879db59-3bdf-4490-ad68-ab880a269474updatedDisplayName"
    }]
}
response

HTTP/1.1 204 No Content

Mettre à jour un groupe [Ajouter des membres]

Requête

PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Add",
        "path": "members",
        "value": [{
            "$ref": null,
            "value": "f648f8d5ea4e4cd38e9c"
        }]
    }]
}
response

HTTP/1.1 204 No Content

Mettre à jour un groupe [Supprimer des membres]

Requête

PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Remove",
        "path": "members",
        "value": [{
            "$ref": null,
            "value": "f648f8d5ea4e4cd38e9c"
        }]
    }]
}
response

HTTP/1.1 204 No Content

Suppression d’un groupe

Requête

DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1

response

HTTP/1.1 204 No Content

Découverte de schéma

Découvrir le schéma

Requête

GET /Schemas

response

HTTP/1.1 200 OK

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "itemsPerPage": 50,
    "startIndex": 1,
    "totalResults": 3,
    "Resources": [
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
    "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"
      },                
    ],
    "meta" : {
      "resourceType" : "Schema",
      "location" :
        "/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
    }
  },
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
    "id" : "urn:ietf:params:scim:schemas:core:2.0:Group",
    "name" : "Group",
    "description" : "Group",
    "attributes" : [
      {
        "name" : "displayName",
        "type" : "string",
        "multiValued" : false,
        "description" : "A human-readable name for the Group.
REQUIRED.",
        "required" : false,
        "caseExact" : false,
        "mutability" : "readWrite",
        "returned" : "default",
        "uniqueness" : "none"
      },
    ],
    "meta" : {
      "resourceType" : "Schema",
      "location" :
        "/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group"
    }
  },
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
    "id" : "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "name" : "EnterpriseUser",
    "description" : "Enterprise User",
    "attributes" : [
      {
        "name" : "employeeNumber",
        "type" : "string",
        "multiValued" : false,
        "description" : "Numeric or alphanumeric identifier assigned
to a person, typically based on order of hire or association with an
organization.",
        "required" : false,
        "caseExact" : false,
        "mutability" : "readWrite",
        "returned" : "default",
        "uniqueness" : "none"
      },
    ],
    "meta" : {
      "resourceType" : "Schema",
      "location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    }
  }
]
}

Spécifications de sécurité

Versions du protocole TLS

La seule version de protocole acceptable est TLS 1.2. Aucune autre version SSL/TLS n’est autorisée.

  • Les clés RSA doivent comporter au moins 2 048 bits.
  • Les clés ECC doivent avoir au moins 256 bits et être générées à l’aide d’une courbe elliptique approuvée

Longueur des clés

Tous les services doivent utiliser des certificats X.509 générés à l’aide de clés de chiffrement d’une longueur suffisante, à savoir :

Suites de chiffrement

Tous les services doivent être configurés pour utiliser les suites de chiffrement suivantes, dans l’ordre exact indiqué dans l’exemple. Si vous ne disposez que d'un certificat RSA, l'installation des suites de chiffrement ECDSA n'a aucun effet.

Barre minimale des suites de chiffrement TLS 1.2 :

  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

Plages d’adresses IP

Le service d'approvisionnement Microsoft Entra fonctionne actuellement dans le cadre des plages d’adresses IP pour Microsoft Entra ID, comme indiqué ici. Vous pouvez ajouter les plages d’adresses IP listées sous la balise AzureActiveDirectory pour autoriser le trafic en provenance du service d’approvisionnement Microsoft Entra dans votre application. Vous devez examiner attentivement la liste des plages d'adresses IP pour les adresses calculées. Une adresse telle que « 40.126.25.32 » peut être représentée dans la liste de plages d’adresses IP sous la forme « 40.126.0.0/18 ». Vous pouvez aussi récupérer programmatiquement la liste de plages d’adresses IP avec l’API suivante.

Microsoft Entra ID prend également en charge une solution basée sur agent pour assurer la connectivité aux applications dans les réseaux privés (localement, hébergés dans Azure, hébergés dans AWS, etc.). Les clients peuvent déployer un agent léger, qui permet de se connecter à Microsoft Entra ID sans ouvrir de ports entrants sur un serveur de leur réseau privé. En savoir plus ici.

Créer un point de terminaison SCIM

Maintenant que vous avez conçu votre schéma et compris l'implémentation de Microsoft Entra SCIM, vous pouvez commencer à développer votre point de terminaison SCIM. Plutôt que de partir de zéro et de construire la mise en œuvre entièrement par vos propres moyens, vous pouvez vous appuyer sur de nombreuses bibliothèques SCIM open source publiées par la communauté SCIM.

Pour obtenir des conseils sur la façon de créer un point de terminaison SCIM avec des exemples, consultez Développer un exemple de point de terminaison SCIM.

L’exemple de code de référence .NET Core open source publié par l’équipe d’approvisionnement Microsoft Entra est une ressource qui peut vous permettre de démarrer rapidement votre développement. Générez un point de terminaison SCIM, puis testez-le en exécutant les exemples de requêtes/réponses fournies.

Remarque

Le code de référence est destiné à vous aider à prendre en main la création d’un point de terminaison SCIM et est fourni « tel quel ». Les contributions de la communauté sont destinées à vous aider à créer le code et à le tenir à jour.

La solution est composée de deux projets, Microsoft.SCIM et Microsoft.SCIM.WebHostSample.

Le projet Microsoft.SCIM est la bibliothèque qui définit les composants du service web conforme à la spécification SCIM. Il déclare l'interface Microsoft.SCIM.IProvider, les requêtes sont traduites en appels aux méthodes du fournisseur, qui seraient programmées pour fonctionner sur un magasin d'identités.

Décomposition : Une requête est traduite en appels vers les méthodes du fournisseur

Le projet Microsoft.SCIM.WebHostSample est une application Web ASP.NET Core, basée sur le modèle Empty. Cela permet de déployer l’exemple de code de manière autonome dans des conteneurs ou au sein d’Internet Information Services. Il implémente également l’interface Microsoft.SCIM.IProvider en conservant les classes en mémoire comme exemple de magasin d’identités.

public class Startup
{
    ...
    public IMonitor MonitoringBehavior { get; set; }
    public IProvider ProviderBehavior { get; set; }

    public Startup(IWebHostEnvironment env, IConfiguration configuration)
    {
        ...
        this.MonitoringBehavior = new ConsoleMonitor();
        this.ProviderBehavior = new InMemoryProvider();
    }
    ...

Création d’un point de terminaison SCIM personnalisé

Le service SCIM doit avoir une adresse HTTP et un certificat d’authentification émanant du serveur dont l’autorité de certification racine est l’un des noms suivants :

  • CNNIC
  • Comodo
  • CyberTrust
  • DigiCert
  • GeoTrust
  • GlobalSign
  • Go Daddy
  • VeriSign
  • WoSign
  • DST Root CA X3

Le SDK .NET Core inclut un certificat de développement HTTPS utilisé pendant le développement. Le certificat est installé dans le cadre de la première expérience d’exécution. Selon la façon dont vous exécutez l’application web ASP.NET Core, elle écoute un autre port :

  • Microsoft.SCIM.WebHostSample : https://localhost:5001
  • IIS Express : https://localhost:44359

Pour plus d’informations sur le protocole HTTPS dans ASP.NET Core, utilisez le lien suivant : Appliquer le protocole HTTPS dans ASP.NET Core

Gestion de l’authentification du point de terminaison

Les demandes provenant du service d'approvisionnement Microsoft Entra comprennent un jeton de support OAuth 2.0. Un serveur d’autorisation émet le jeton du porteur. Microsoft Entra ID est un exemple de serveur d’autorisation approuvé. Configurez le service de provisionnement Microsoft Entra pour utiliser l’un des jetons suivants :

  • Un jeton porteur à longue durée de vie. Si le point de terminaison SCIM requiert un jeton de porteur OAuth d’un émetteur autre que Microsoft Entra ID, copiez le jeton de porteur OAuth requis dans le champ facultatif Secret Token (Jeton secret). Dans un environnement de développement, vous pouvez utiliser le jeton de test à partir du point de terminaison /scim/token. Les jetons de test ne doivent pas être utilisés dans les environnements de production.

  • Jeton du porteur Microsoft Entra. Si le champ Secret Token est laissé vide, Microsoft Entra ID inclut un jeton de porteur OAuth émis par Microsoft Entra ID avec chaque demande. Les applications qui utilisent Microsoft Entra ID en tant que fournisseur d’identité peuvent valider ce jeton émis par l’ID Microsoft Entra.

    • L’application qui reçoit des demandes doit valider l’émetteur de jeton comme étant Microsoft Entra ID pour un locataire Microsoft Entra attendu.
    • Une revendication iss identifie l’émetteur du jeton. Par exemple : "iss":"https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/". Dans cet exemple, l'adresse de base de la valeur de revendication https://sts.windows.net identifie l'ID Microsoft Entra en tant qu'émetteur, tandis que le segment d'adresse relative, aaaabbbb-0000-cccc-1111-dddd2222eeee, est un identifiant unique du locataire Microsoft Entra pour lequel le jeton a été émis.
    • L’audience d’un jeton est l’ID d’application de l’application dans la galerie. Les applications enregistrées dans un seul locataire reçoivent la même revendication iss avec les demandes SCIM. L'ID de l'application pour toutes les applications personnalisées est 8adf8e6e-67b2-4cf2-a259-e3dc5476c621. Le jeton généré par Microsoft Entra ID doit être utilisé uniquement pour le test. Il ne doit pas être utilisé dans les environnements de production.

Dans l’exemple de code, les requêtes sont authentifiées à l’aide du package Microsoft.AspNetCore.Authentication.JwtBearer. Le code suivant garantit que les demandes adressées à l'un des points de terminaison du service sont authentifiées à l'aide du jeton du support émis par Microsoft Entra ID pour un locataire donné :

public void ConfigureServices(IServiceCollection services)
{
    if (_env.IsDevelopment())
    {
        ...
    }
    else
    {
        services.AddAuthentication(options =>
        {
            options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
        })
            .AddJwtBearer(options =>
            {
                options.Authority = " https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/";
                options.Audience = "8adf8e6e-67b2-4cf2-a259-e3dc5476c621";
                ...
            });
    }
    ...
}

public void Configure(IApplicationBuilder app)
{
    ...
    app.UseAuthentication();
    app.UseAuthorization();
    ...
}

L’exemple de code utilise des environnements ASP.NET Core pour modifier les options d’authentification pendant la phase de développement et activer l’utilisation d’un jeton autosigné.

Pour plus d’informations sur l’utilisation de plusieurs environnements dans ASP.NET Core, consultez Utiliser plusieurs environnements dans ASP.NET Core.

Le code suivant impose que les requêtes adressées à l'un des points de terminaison du service soient authentifiées à l'aide d'un jeton de porteur signé avec une clé personnalisée :

public void ConfigureServices(IServiceCollection services)
{
    if (_env.IsDevelopment())
    {
        services.AddAuthentication(options =>
        {
            options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
            options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
        })
        .AddJwtBearer(options =>
        {
            options.TokenValidationParameters =
                new TokenValidationParameters
                {
                    ValidateIssuer = false,
                    ValidateAudience = false,
                    ValidateLifetime = false,
                    ValidateIssuerSigningKey = false,
                    ValidIssuer = "Microsoft.Security.Bearer",
                    ValidAudience = "Microsoft.Security.Bearer",
                    IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("A1B2C3D4E5F6A1B2C3D4E5F6"))
                };
        });
    }
...

Envoyez une requête GET au contrôleur de jetons pour obtenir un jeton du porteur valide, la méthode GenerateJSONWebToken est chargée de créer un jeton correspondant aux paramètres configurés pour le développement :

private string GenerateJSONWebToken()
{
    // Create token key
    SymmetricSecurityKey securityKey =
        new SymmetricSecurityKey(Encoding.UTF8.GetBytes("A1B2C3D4E5F6A1B2C3D4E5F6"));
    SigningCredentials credentials =
        new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);

    // Set token expiration
    DateTime startTime = DateTime.UtcNow;
    DateTime expiryTime = startTime.AddMinutes(120);

    // Generate the token
    JwtSecurityToken token =
        new JwtSecurityToken(
            "Microsoft.Security.Bearer",
            "Microsoft.Security.Bearer",
            null,
            notBefore: startTime,
            expires: expiryTime,
            signingCredentials: credentials);

    string result = new JwtSecurityTokenHandler().WriteToken(token);
    return result;
}

Gestion du provisionnement et de l’annulation du provisionnement des utilisateurs

Exemple 1. Interroger le service pour obtenir un utilisateur correspondant

Microsoft Entra ID interroge le service pour trouver un utilisateur avec une valeur d’attribut externalId correspondant à la valeur d’attribut mailNickname d’un utilisateur dans Microsoft Entra ID. La requête est exprimée dans le protocole HTTP (Hypertext Transfer Protocol) comme dans cet exemple, jyoung étant un exemple de mailNickname d’utilisateur dans Microsoft Entra ID.

Remarque

Il s'agit simplement d'un exemple. Tous les utilisateurs n’auront pas d’attribut mailNickname, et la valeur dont dispose un utilisateur peut ne pas être unique dans le répertoire. De plus, l’attribut utilisé pour la correspondance (dans ce cas, externalId) est configurable dans les mappages d’attributs Microsoft Entra.

GET https://.../scim/Users?filter=externalId eq jyoung HTTP/1.1
 Authorization: Bearer ...

Dans l'exemple de code, la requête est traduite en un appel à la méthode QueryAsync du fournisseur du service. Voici la signature de cette méthode :

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.Resource is defined in 
// Microsoft.SCIM.Schemas.  
// Microsoft.SCIM.IQueryParameters is defined in 
// Microsoft.SCIM.Protocol.  

Task<Resource[]> QueryAsync(IRequest<IQueryParameters> request);

Dans l’exemple de requête, pour un utilisateur avec une valeur d’attribut externalId donnée, les valeurs des arguments transmis à la méthode QueryAsync sont :

  • parameters.AlternateFilters.Count: 1
  • parameters.AlternateFilters.ElementAt(0).AttributePath: "externalId"
  • parameters.AlternateFilters.ElementAt(0).ComparisonOperator: ComparisonOperator.Equals
  • parameters.AlternateFilter.ElementAt(0).ComparisonValue: "jyoung"

Exemple 2. Approvisionner un utilisateur

Si la réponse à une requête adressée au point de terminaison SCIM pour un utilisateur dont la valeur d'attribut externalId correspond à la valeur d'attribut mailNickname d'un utilisateur ne renvoie aucun utilisateur, Microsoft Entra ID demande au service de fournir un utilisateur correspondant à celui qui se trouve dans Microsoft Entra ID. Voici un exemple de requête :

POST https://.../scim/Users HTTP/1.1
Authorization: Bearer ...
Content-type: application/scim+json
{
   "schemas":
   [
     "urn:ietf:params:scim:schemas:core:2.0:User",
     "urn:ietf:params:scim:schemas:extension:enterprise:2.0User"],
   "externalId":"jyoung",
   "userName":"jyoung@testuser.com",
   "active":true,
   "addresses":null,
   "displayName":"Joy Young",
   "emails": [
     {
       "type":"work",
       "value":"jyoung@Contoso.com",
       "primary":true}],
   "meta": {
     "resourceType":"User"},
    "name":{
     "familyName":"Young",
     "givenName":"Joy"},
   "phoneNumbers":null,
   "preferredLanguage":null,
   "title":null,
   "department":null,
   "manager":null}

Dans l'exemple de code, la requête est traduite en un appel à la méthode CreateAsync du fournisseur de services. Voici la signature de cette méthode :

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.Resource is defined in 
// Microsoft.SCIM.Schemas.  

Task<Resource> CreateAsync(IRequest<Resource> request);

Dans une requête de provisionnement d’utilisateur, la valeur de l’argument de ressource est une instance de la classe Microsoft.SCIM.Core2EnterpriseUser. Cette classe est définie dans la bibliothèque Microsoft.SCIM.Schemas. Si la requête de provisionnement d’utilisateur aboutit, alors l’implémentation de la méthode renvoie une instance de la classe Microsoft.SCIM.Core2EnterpriseUser. La valeur de la propriété Identifier est définie sur l’identificateur unique de l’utilisateur qui vient d’être provisionné.

Exemple 3. Interroger l'état actuel d’un utilisateur

Microsoft Entra ID demande l’état actuel de l’utilisateur spécifié auprès du service avec une requête comme :

GET ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...

Dans l'exemple de code, la requête est traduite en un appel à la méthode RetrieveAsync du fournisseur du service. Voici la signature de cette méthode :

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.Resource and 
// Microsoft.SCIM.IResourceRetrievalParameters 
// are defined in Microsoft.SCIM.Schemas 

Task<Resource> RetrieveAsync(IRequest<IResourceRetrievalParameters> request);

Dans le cas d’une requête servant à récupérer l’état actuel d’un utilisateur, les valeurs des propriétés de l’objet fourni comme valeur d’argument des paramètres sont les suivantes :

  • Identifiant : "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
  • SchemaIdentifier : urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Exemple 4. Interroger la valeur d’un attribut de référence à mettre à jour

Microsoft Entra ID vérifie la valeur d’attribut actuelle dans le magasin d’identités avant de le mettre à jour. Toutefois, seul l’attribut manager est le premier sélectionné pour les utilisateurs. Voici un exemple de requête permettant de déterminer si l'attribut manager d'un objet utilisateur a actuellement une certaine valeur : Dans l'exemple de code, la requête est traduite en un appel à la méthode QueryAsync du fournisseur de service. La valeur des propriétés de l’objet fourni en tant que valeur d’argument des paramètres est la suivante :

  • parameters.AlternateFilters.Count: 2
  • parameters.AlternateFilters.ElementAt(x).AttributePath: « ID »
  • parameters.AlternateFilters.ElementAt(x).ComparisonOperator: ComparisonOperator.Equals
  • settings.AlternateFilter.ElementAt(x).ComparisonValue : "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
  • parameters.AlternateFilters.ElementAt(y).AttributePath: "manager
  • parameters.AlternateFilters.ElementAt(y).ComparisonOperator: ComparisonOperator.Equals
  • parameters.AlternateFilter.ElementAt(y).ComparisonValue: "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
  • parameters.RequestedAttributePaths.ElementAt(0): « ID »
  • paramètres. SchemaIdentifier : urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

La valeur de l’index x peut être 0 et la valeur de l’index y peut être 1. Ou la valeur de x peut être 1 et la valeur de y peut être 0. Elle dépend de l’ordre des expressions du paramètre de requête de filtre.

Exemple 5. Demande Microsoft Entra ID à un service SCIM pour mettre à jour un utilisateur

Voici un exemple de demande de Microsoft Entra ID à un point de terminaison SCIM pour mettre à jour un utilisateur :

PATCH ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...
Content-type: application/scim+json
{
    "schemas": 
    [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations":
    [
      {
        "op":"Add",
        "path":"manager",
        "value":
          [
            {
              "$ref":"http://.../scim/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
              "value":"00aa00aa-bb11-cc22-dd33-44ee44ee44ee"}]}]}

Dans l'exemple de code, la requête est traduite en un appel à la méthode UpdateAsync du fournisseur de services. Voici la signature de cette méthode :

// System.Threading.Tasks.Tasks and 
// System.Collections.Generic.IReadOnlyCollection<T>  // are defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in
// Microsoft.SCIM.Service.
// Microsoft.SCIM.IPatch, 
// is defined in Microsoft.SCIM.Protocol. 

Task UpdateAsync(IRequest<IPatch> request);

Dans le cas d’une requête de mise à jour d’un utilisateur, l’objet fourni comme valeur d’argument de correctif a les valeurs de propriété suivantes :

Argument Valeur
ResourceIdentifier.Identifier "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
ResourceIdentifier.SchemaIdentifier urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
(PatchRequest as PatchRequest2).Operations.Count 1
(PatchRequest as PatchRequest2).Operations.ElementAt(0).OperationName OperationName.Add
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Path.AttributePath Manager
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.Count 1
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Reference http://.../scim/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value 00aa00aa-bb11-cc22-dd33-44ee44ee44ee

Exemple 6. Déprovisionner un utilisateur

Pour déprovisionner un utilisateur à partir d'un magasin d'identités géré par un point de terminaison SCIM, Microsoft Entra ID envoie une requête telle que :

DELETE ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...

Dans l'exemple de code, la requête est traduite en un appel à la méthode DeleteAsync du fournisseur de services. Voici la signature de cette méthode :

// System.Threading.Tasks.Tasks is defined in mscorlib.dll.  
// Microsoft.SCIM.IRequest is defined in 
// Microsoft.SCIM.Service.  
// Microsoft.SCIM.IResourceIdentifier, 
// is defined in Microsoft.SCIM.Protocol. 

Task DeleteAsync(IRequest<IResourceIdentifier> request);

L’objet fourni en tant que valeur d’argument resourceIdentifier présente ces valeurs de propriété dans le cas d’une demande de déprovisionnement d'un utilisateur :

  • ResourceIdentifier.Identifier : "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
  • ResourceIdentifier.SchemaIdentifier : urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

Intégrer votre terminal SCIM avec le service de provisionnement Microsoft Entra

Microsoft Entra ID peut être configuré pour attribuer automatiquement des utilisateurs et groupes dans les applications qui implémentent un profil spécifique du protocole SCIM 2.0. Les détails du profil sont documentés dans Comprendre l’implémentation de SCIM de Microsoft Entra.

Vérifiez avec votre fournisseur d’application ou dans la documentation du fournisseur de votre application la conformité à ces exigences.

Important

L’implémentation de SCIM de Microsoft Entra repose sur le service d’approvisionnement d’utilisateur Microsoft Entra, conçu pour conserver constamment les utilisateurs synchronisés avec Microsoft Entra et l’application cible, et implémente un ensemble très spécifique d’opérations standard. Il est important de comprendre ces comportements pour comprendre le comportement du service d'approvisionnement Microsoft Entra. Pour plus d'informations, consultez la section Cycles d'approvisionnement : cycle initial et cycle incrémentiel de l'article Fonctionnement de l'approvisionnement.

Prise en main

Conseil

Les étapes décrites dans cet article peuvent varier légèrement en fonction du portail de départ.

Les applications qui prennent en charge le profil SCIM décrit dans cet article peuvent être connectées à Microsoft Entra ID à l’aide de la fonctionnalité « application ne figurant pas dans la galerie » dans la galerie d’applications Microsoft Entra. Une fois connecté, Microsoft Entra ID exécute un processus de synchronisation. Le processus s’exécute toutes les 40 minutes. Le processus interroge le point de terminaison de SCIM de l’application pour les utilisateurs et les groupes assignés, et les crée ou les modifie en fonction des détails de l’attribution.

Pour connecter une application qui prend en charge SCIM :

  1. Connectez-vous au centre d'administration Microsoft Entra au minimum en tant qu’Administrateur d'application.

  2. Accédez à Identité>Applications>Applications d’entreprise.

  3. Une liste de toutes les applications configurées s’affiche, dont les applications qui ont été ajoutées à partir de la galerie.

  4. Sélectionnez + Nouvelle application>+ Créer votre propre application.

  5. Entrez un nom pour votre application, choisissez l’option « Intégrer une autre application que vous ne trouvez pas dans la galerie », puis sélectionnez Ajouter pour créer un objet d’application. La nouvelle application est ajoutée à la liste des applications d’entreprise et s’ouvre sur son écran de gestion d’application.

    La capture d'écran suivante montre la galerie d'applications Microsoft Entra :

    La capture d'écran montre la galerie d'applications Microsoft Entra.

  6. Dans l’écran de gestion d’application, sélectionnez Approvisionnement dans le volet gauche.

  7. Dans le menu Mode d’approvisionnement, sélectionnez Automatique.

    La capture d'écran suivante montre la configuration des paramètres de provisionnement dans le centre d’administration Microsoft Entra :

    Capture d'écran de la page de provisionnement des applications dans le centre d’administration Microsoft Entra.

  8. Dans le champ URL du locataire, entrez l’URL du point de terminaison SCIM de l’application. Exemple : https://api.contoso.com/scim/

  9. Si le point de terminaison SCIM requiert un jeton de porteur OAuth d’un émetteur autre que Microsoft Entra ID, copiez le jeton de porteur OAuth requis dans le champ facultatif Secret Token (Jeton secret). Si ce champ est laissé vide, Microsoft Entra ID inclut un jeton de porteur OAuth émis par Microsoft Entra ID avec chaque demande. Les applications qui utilisent Microsoft Entra ID en tant que fournisseur d’identité peuvent valider ce jeton émis par l’ID Microsoft Entra.

    Remarque

    Il est déconseillé de laisser ce champ vide et d’utiliser un jeton généré par Microsoft Entra ID. Cette option est principalement destinée à des fins de test.

  10. Sélectionnez Tester la connexion pour que Microsoft Entra ID tente de se connecter au point de terminaison SCIM. Si la tentative échoue, des informations d’erreur s’affichent.

    Remarque

    Tester la connexion interroge le point de terminaison SCIM pour un utilisateur qui n’existe pas, en utilisant un GUID aléatoire en tant que propriété correspondante sélectionnée dans la configuration Microsoft Entra. La réponse correcte attendue est HTTP 200 OK avec un message SCIM ListResponse vide.

  11. Si la tentative de connexion à l’application réussit, sélectionnez Enregistrer pour enregistrer les informations d’identification d’administrateur.

  12. La section Mappages présente deux ensembles sélectionnables de mappages d’attributs : un pour les objets utilisateur et un autre pour les objets de groupe. Sélectionnez chacun d’eux pour consulter les attributs qui sont synchronisés entre Microsoft Entra ID et votre application. Les attributs sélectionnés en tant que propriétés de Correspondance sont utilisés pour faire correspondre les utilisateurs et les groupes dans votre application pour les opérations de mise à jour. Sélectionnez Enregistrer pour valider les modifications.

    Remarque

    Vous pouvez éventuellement désactiver la synchronisation des objets de groupe en désactivant le mappage « Groupes ».

  13. Sous Paramètres, le champ Étendue définit les utilisateurs et les groupes qui sont synchronisés. Sélectionnez Sync only assigned users and groups (recommended) (Synchroniser uniquement les utilisateurs et les groupes attribués (recommandé)) pour que seuls les utilisateurs et les groupes attribués soient synchronisés dans l’onglet Utilisateurs et groupes.

  14. Une fois votre configuration terminée, définissez l’état d’approvisionnement sur Activé.

  15. Sélectionnez Enregistrer pour démarrer le service d’approvisionnement Microsoft Entra.

  16. Si vous souhaitez synchroniser uniquement les utilisateurs et groupes assignés (recommandé), sélectionnez l'onglet Utilisateurs et groupes. Ensuite, affectez les utilisateurs ou les groupes que vous souhaitez synchroniser.

Une fois le cycle initial démarré, vous pouvez sélectionner Journaux d’approvisionnement dans le panneau de gauche pour suivre la progression, qui indique toutes les actions effectuées par le service d'approvisionnement de votre application. Pour plus d’informations sur la lecture des journaux de provisionnement Microsoft Entra, consultez Rapports sur le provisionnement automatique de comptes d’utilisateur.

Remarque

Le cycle initial prend plus de temps que les synchronisations suivantes, qui se produisent environ toutes les 40 minutes, tant que le service est en cours d’exécution.

Si vous créez une application utilisée par plusieurs locataires, rendez-la disponible dans la galerie d’applications Microsoft Entra. Il est facile pour les organisations de découvrir l'application et de configurer le provisionnement. Vous pouvez facilement publier votre application dans la galerie Microsoft Entra et mettre l’approvisionnement à la disposition d’autres utilisateurs. Découvrez les étapes ici. Microsoft vous aide à intégrer votre application à la galerie, à tester votre point de terminaison et à publier la documentation d’intégration destinée aux clients.

Utilisez la liste de vérification pour intégrer rapidement votre application et permettre à vos clients une expérience de déploiement facile. Les informations sont collectées auprès de vous lors de l’intégration à la galerie.

  • Prise en charge d’un point de terminaison de groupe et d’utilisateur SCIM 2.0 (un seul est obligatoire, mais il est recommandé de disposer des deux)
  • Prise en charge d’au moins 25 requêtes par seconde par locataire pour s’assurer que les utilisateurs et les groupes sont provisionnés et déprovisionnés sans délai (obligatoire)
  • Établissement de contacts d’ingénierie et de support pour guider l’intégration des clients à la galerie de publications (obligatoire)
  • Trois informations d’identification de test sans date d’expiration pour l’application (obligatoire)
  • Prise en charge de l’octroi de code d’autorisation OAuth ou d’un jeton de longue durée, comme décrit dans l’exemple (obligatoire)
  • Les applications OIDC doivent avoir au moins 1 rôle défini (personnalisé ou par défaut)
  • Établissement d’un point de contact d’ingénierie et de support pour la prise en charge de l’intégration des clients à la galerie de publications (obligatoire)
  • Prise en charge de la détection de schéma (obligatoire)
  • Prise en charge de la mise à jour de l’appartenance à plusieurs groupes avec un seul correctif
  • Documentation publique de votre point de terminaison SCIM

La spécification SCIM ne définit pas un schéma propre à SCIM pour l’authentification et l’autorisation. En outre, elle s’appuie sur l’utilisation de normes industrielles existantes.

Méthode d’autorisation Avantages Inconvénients Support
Nom d’utilisateur et mot de passe (non recommandé ou pris en charge par Microsoft Entra ID) Facile à implémenter Non sécurisé - Votre Pa$$word n’a pas d’importance Non pris en charge pour les nouvelles applications de la galerie ou hors galerie.
Jeton de porteur de longue durée Les jetons de longue durée ne nécessitent aucune intervention de la part d’un utilisateur. Ils sont simples à utiliser par les administrateurs qui configurent le provisionnement. Les jetons de longue durée peuvent être difficiles à partager avec un administrateur sans utiliser de méthodes non sécurisées telles que la messagerie électronique. Prise en charge pour toutes les applications (celles de la galerie et les autres).
Octroi du code d’autorisation OAuth Les jetons d’accès ont une durée de vie plus courte que les mots de passe et comportent un mécanisme d’actualisation automatisée, ce qui n’est pas le cas des jetons de porteur de longue durée. Un utilisateur doit être physiquement présent lors de l’autorisation initiale, ce qui ajoute un niveau de responsabilité. Nécessite la présence d’un utilisateur. Si l’utilisateur quitte l’organisation, le jeton n’est plus valide et l’autorisation doit être recommencée. Prise en charge pour les applications de la galerie, mais pas pour les autres. Toutefois, vous pouvez fournir un jeton d’accès dans l’interface utilisateur en tant que jeton secret à des fins de test à court terme. La prise en charge de l’octroi de code OAuth pour les applications hors galerie fait partie de notre backlog. De même, la prise en charge des URL d’authentification/de jeton configurables pour l’application de galerie fait également partie de notre backlog.
Octroi d’informations d’identification de client OAuth Les jetons d’accès ont une durée de vie plus courte que les mots de passe et comportent un mécanisme d’actualisation automatisée, ce qui n’est pas le cas des jetons de porteur de longue durée. L’octroi du code d’autorisation et l’octroi d’informations d’identification du client permettent de créer le même type de jeton d’accès. L’utilisation de l’une ou l’autre de ces méthodes est donc transparente pour l’API. L'approvisionnement peut être automatisé, et de nouveaux jetons peuvent être demandés silencieusement sans interaction avec l'utilisateur. Prise en charge pour les applications de la galerie, mais pas pour les autres. Toutefois, vous pouvez fournir un jeton d’accès dans l’interface utilisateur en tant que jeton secret à des fins de test à court terme. Notre backlog inclut une prise en charge de l’octroi de client OAuth sur une application ne figurant pas dans la galerie.

Remarque

Il est déconseillé de laisser le champ du jeton vide dans l’interface utilisateur de l’application personnalisée de configuration du provisionnement Microsoft Entra. Le jeton généré est principalement destiné à des fins de test.

Flux d’octroi du code OAuth

Le service de provisionnement prend en charge l’octroi de code d’autorisation. Une fois que vous aurez envoyé la demande de publication de votre application dans la galerie, notre équipe vous demandera les informations suivantes :

  • URL d’autorisation : URL client permettant d’obtenir l’autorisation du propriétaire de la ressource via la redirection de l’agent utilisateur. L’utilisateur est redirigé vers cette URL pour autoriser l’accès.

  • URL d’échange de jetons : URL client permettant d’échanger un octroi d’autorisation pour un jeton d’accès, généralement avec authentification du client.

  • ID client : serveur d’autorisation qui fournit au client inscrit un identifiant client. Il s’agit d’une chaîne unique représentant les informations d’inscription fournies par le client. L’identifiant client n’est pas secret ; il est exposé au propriétaire de la ressource et ne doit pas être utilisé seul à des fins d'authentification du client.

  • Secret client : secret généré par le serveur d’autorisation. Il doit s’agir d’une valeur unique connue uniquement du serveur d’autorisation.

Remarque

L’URL d’autorisation et l’URL d’échange de jetons ne sont pas configurables par le locataire.

Remarque

OAuth v1 n’est pas pris en charge en raison de l’exposition du secret client. OAuth v2 est pris en charge.

Lorsque vous utilisez le flux d’octroi de code OAuth, vous devez prendre en charge un modèle dans lequel chaque client envoie son propre ID client et secret client lors de la configuration d’une instance d’approvisionnement. Une seule paire ID client et clé secrète client à l’échelle de l’application n’est pas prise en charge.

Comment mettre en place le flux d'octroi de code OAuth

  1. Connectez-vous au centre d'administration Microsoft Entra au minimum en tant qu’Administrateur d'application.

  2. Accédez à Identité>Applications>Applications d’entreprise>Application>Provisionnement, puis sélectionnez Autoriser.

  3. Connectez-vous au centre d'administration Microsoft Entra au minimum en tant qu’Administrateur d'application.

  4. Accédez à Identité>Applications>Applications d’entreprise.

  5. Sélectionnez votre application et accédez à Provisioning.

  6. Sélectionnez Autoriser.

    1. Les utilisateurs sont redirigés vers l'URL d'autorisation (page de connexion pour l'application tierce).

    2. L’administrateur fournit des informations d’identification à l’application tierce.

    3. L'application tierce redirige l'utilisateur et fournit le code d'octroi

    4. Le service Provisioning appelle l'URL du jeton et fournit le code d'octroi. L’application tierce répond avec le jeton d’accès, le jeton d’actualisation et la date d’expiration

  7. Lors du démarrage du cycle d’approvisionnement, le service vérifie si le jeton d’accès actuel est valide et l’échange contre un nouveau jeton si nécessaire. Le jeton d’accès est fourni dans chaque demande adressée à l’application et la validité de la demande est vérifiée avant chaque demande.

Remarque

Même s’il n’est pas possible de configurer OAuth dans les applications qui ne figurent pas dans la galerie, vous pouvez générer manuellement un jeton d’accès à partir de votre serveur d’autorisation et l’entrer comme jeton secret pour une application ne figurant pas dans la galerie. Cela vous permet de vérifier la compatibilité de votre serveur SCIM avec le service d'approvisionnement Microsoft Entra avant d'intégrer la galerie d'applications, qui prend en charge l'octroi de code OAuth.

Jetons de porteur OAuth à longue durée : Si votre application ne prend pas en charge le flux d’octroi de code OAuth, générez un jeton de porteur OAuth à longue durée qu’un administrateur peut utiliser pour configurer l’intégration du provisionnement. Le jeton doit être perpétuel, à défaut de quoi le travail de provisionnement est mis en quarantaine à l’expiration du jeton.

Si vous souhaitez davantage de méthodes d’authentification et d’autorisation, faites-le nous savoir sur UserVoice.

Pour contribuer à la sensibilisation et à la demande de notre intégration conjointe, nous vous recommandons de mettre à jour votre documentation existante et d’amplifier son intégration dans vos canaux marketing. Nous vous recommandons de suivre la liste de contrôle suivante pour prendre en charge le lancement :

  • Assurez-vous que l’équipe du support technique et l’équipe commerciale sont informées et capables de parler des fonctionnalités d’intégration. Informez vos équipes, mettez à leur disposition la liste des questions fréquentes (FAQ), et incluez l’intégration dans vos documents de vente.
  • Élaborez un billet de blog ou un communiqué de presse décrivant l’intégration conjointe, les avantages et la prise en main. Exemple : Communiqué de presse Imprivata et Microsoft Entra
  • Tirez parti de vos réseaux sociaux tels que X, Facebook ou LinkedIn pour promouvoir l’intégration à vos clients. Veillez à inclure @Microsoft Entra ID pour pouvoir retweeter votre publication. Exemple : Imprivata X Post
  • Créez ou mettez à jour vos pages marketing ou vos sites web (par exemple, page d’intégration, page de partenaire, page des tarifs, etc.) pour inclure la disponibilité de l’intégration conjointe. Exemple : Page d’intégration Pingboard, page d’intégration Smartsheet, page de tarification Monday.com
  • Créez un article du centre d’aide ou une documentation technique sur la façon dont les clients peuvent commencer. Exemple : Intégration Envoy + Microsoft Entra.
  • Avertissez les clients de la nouvelle intégration dans le cadre de votre communication (bulletins mensuels, campagnes par courrier électronique, notes de publication de produits).

Étapes suivantes

Développer un exemple de point de terminaison SCIMAutomatiser le provisionnement et le déprovisionnement des utilisateurs pour les applications SaaSPersonnaliser les mappages d’attributs pour le provisionnement d’utilisateursÉcriture d’expressions pour les mappages d’attributsFiltres d’étendue pour le provisionnement des utilisateursNotifications du provisionnement de comptesListe des tutoriels sur l’intégration des applications SaaS