Extensions de schéma d’annuaire | Concepts de l’API Graph

Article
10/21/2021

Cette rubrique présente les extensions d’annuaire de l’API Azure AD Graph, qui peuvent être utilisées pour ajouter des propriétés aux objets d’annuaire sans avoir recours à une banque de données externe. Par exemple, si une organisation possède une application métier nécessitant un identifiant Skype pour chaque utilisateur de l’annuaire, l’API Graph peut être utilisée pour enregistrer une nouvelle propriété dénommée skypeId sur l’objet User de l’annuaire, puis pour écrire une valeur dans la nouvelle propriété associée à un utilisateur spécifique. Cette rubrique va vous aider à comprendre les limitations applicables aux extensions d’annuaire ainsi que la façon dont ces dernières sont enregistrées dans un annuaire. Elle fournit également des exemples de leur utilisation dans l’API Graph.

Important

Nous vous recommandons fortement d’utiliser Microsoft Graph plutôt que l’API Graph Azure AD pour accéder aux ressources Azure Active Directory. Nos efforts de développement sont désormais axés sur Microsoft Graph et aucune autre amélioration n’est prévue pour l’API Graph Azure AD. Il existe un nombre très limité de scénarios pour lesquels l’API Graph Azure AD peut être encore appropriée ; pour plus d’informations, consultez le billet de blog Microsoft Graph ou l’API Azure AD dans le Centre de développement Office.

Types de données d’extension

Les extensions peuvent uniquement être enregistrées à l’aide de la version 1.5 de l’API Graph ou une version ultérieure. Les types de propriétés suivants peuvent être enregistrés :

Type de propriété	Remarques
Binary	256 octets au maximum
Booléen
DateTime	Doit figurer au format ISO 8601. Est stocké au format UTC.
Entier	Valeur 32 bits.
LargeInteger	Valeur 64 bits.
Chaîne	256 caractères au maximum

Les types de propriétés mentionnés ci-dessus peuvent être enregistrés dans les objets d’annuaire suivants :

[User]
[Groupe]
[TenantDetail]
[Dispositif]
Application
[ServicePrincipal]

Procédure d’enregistrement d’une extension

Il est important de comprendre le processus d’enregistrement d’une propriété d’extension dans un annuaire et la manière dont le modèle de consentement d’Azure AD influe sur l’enregistrement. Pour plus d’informations sur l’autorisation d’application dans Azure AD, consultez Vue d’ensemble de l’infrastructure de consentement dans Intégration d’applications à Azure Active Directory.

Les propriétés d’extension sont enregistrées dans un objet Application au sein de l’annuaire du développeur. Une fois l’application consentie par un utilisateur ou un administrateur dans l’annuaire du développeur, la propriété est ajoutée au type d’annuaire cible et devient immédiatement accessible dans l’annuaire du développeur. Pour une application mutualisée, lorsque celle-ci reçoit le consentement d’un utilisateur ou d’un administrateur d’une autre organisation, les propriétés de l’extension deviennent immédiatement accessibles dans le type d’annuaire cible de l’annuaire de l’autre organisation.

Si une organisation accorde les autorisations « lecture seule » pour une application avec des extensions enregistrées, les propriétés seront toujours accessibles dans l’annuaire de l’autre organisation. De plus, les propriétés d’extension sont accessibles par toute application ayant reçu un consentement dans une organisation, et pas seulement pour l’application dans laquelle elles sont enregistrées. D’autres applications ayant reçu un consentement dans cette organisation peuvent lire ou écrire des valeurs pour la nouvelle propriété d’extension si elles disposent des autorisations nécessaires.

Si l’application est supprimée ou si le consentement est annulé dans l’annuaire de l’autre organisation, la propriété d’extension devient inaccessible pour l’objet d’annuaire cible. Si l’extension est supprimée par l’application, elle devient inaccessible pour l’objet d’annuaire cible. Si une application mutualisée ajoute des propriétés d’extension supplémentaires après que le consentement a été octroyé, ces propriétés deviennent également accessibles immédiatement dans l’annuaire de l’autre organisation.

Remarque: si la valeur d’une propriété d’extension est définie sur un objet et que cette propriété devient inaccessible dans l’annuaire de l’objet, la propriété est toujours déduite des 100 valeurs de propriété d’extension maximum pour cet objet. La seule façon qu’une valeur de propriété soit désactivée est de la définir explicitement sur null. Vous ne pouvez pas faire cela si la propriété d’extension n’est pas accessible.

Exemple de scénario

Considérez le scénario suivant : Litware, éditeur de logiciels indépendant, a développé une application SaaS pour le compte d’autres organisations. Cette application nécessite une propriété d’extension appelée skypeId sur un objet User. Litware enregistre tout d’abord l’application dans son propre annuaire, puis l’API Graph est appelée pour enregistrer la propriété d’extension sur l’objet Application, ce qui a pour effet de rendre la propriété accessible sur les objets User dans l’annuaire de Litware. Enfin, Litware active la mutualisation pour l’application afin que celle-ci puisse être utilisée dans d’autres organisations.

Contoso souhaite utiliser l’application SaaS de Litware. Un administrateur ou un utilisateur de Contoso donne donc le consentement à l’application. Une fois le consentement reçu, l’application est enregistrée dans l’annuaire de Contoso et les propriétés d’extension enregistrées pour l’application par Litware deviennent immédiatement disponibles dans cet annuaire. Étant donné que la propriété d’extension skypeId pour un objet User a été enregistrée par Litware sur l’application, la propriété devient accessible sur les objets [User] dans l’annuaire de Contoso. L’application Litware, ou toute autre application ayant reçu le consentement dans l’annuaire de Contoso, peut désormais accéder à la nouvelle propriété conformément aux autorisations configurées pour cette application dans l’annuaire de Contoso. Cela signifie que, selon leurs autorisations, les applications peuvent écrire une valeur pour cette propriété d’extension sur un ou plusieurs utilisateurs dans l’annuaire. Seuls les utilisateurs pour lesquels une valeur skypeId a été écrite retournent cette propriété sur leur objet [User]. C’est le cas jusqu’à ce que la propriété skypeId soit définie sur null, auquel cas l’objet User de cet utilisateur ne renvoie plus la propriété.

Exemples de demandes REST pour les extensions d’annuaire

Les exemples de demandes suivants vous montrent comment enregistrer, afficher, écrire, lire, filtrer et annuler l’enregistrement des extensions dans votre annuaire. Remplacez l’espace réservé <applicationObjectId> par l’ID d’objet de votre application enregistrée. Vous pouvez obtenir cette valeur comme suit :

Accédez à https://graphexplorer.cloudapp.net/, cliquez sur le lien Sign In en haut à droite, puis entrez les informations d’identification d’un compte d’administration de l’annuaire de votre organisation.
Une fois que vous êtes connecté, cliquez sur l’URL dans la zone de texte de ressources (à côté du bouton GET) et sélectionnez l’URL figurant à la fin d’applications/, puis cliquez sur GET ou sur la touche Entrée.
Recherchez l’application souhaitée dans les résultats, puis copiez sa valeur objectId, comme dans l’exemple suivant : "objectId": "269fc2f7-6420-4ea4-be90-9e1f93a87a64"

Dans cette section, il existe des exemples de demandes pour les opérations suivantes :

Enregistrer une extension
Afficher les extensions enregistrées
Écrire une valeur d’extension
Supprimer une valeur d’extension
Lire une valeur d’extension
Filtrer une valeur d’extension
Annuler l’enregistrement d’une extension

Pour obtenir des exemples complets sur l’utilisation des propriétés d’extension, reportez-vous aux exemples Azure AD suivants sur Github :

WebApp-GraphAPI-DirectoryExtensions-PHP : indique comment créer et utiliser des extensions avec PHP.
WebApp-GraphAPI-DirectoryExtensions-DotNet : affiche l’organigramme des locataires AAD et permet de lire directement les valeurs d’extension.

Enregistrer une extension

L’exemple de demande suivant permet de créer un extensionProperty sur l’objet Application souhaité.

Format de la demande

POST https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties?api-version=1.5 HTTP/1.1

{
    "name": "<extensionPropertyName>",
    "dataType": "<String or Binary>",
    "targetObjects": [
        "<DirectoryObject>"
    ]
}

Exemple de demande

POST https://graph.windows.net/contoso.onmicrosoft.com/applications/269fc2f7-6420-4ea4-be90-9e1f93a87a64/extensionProperties?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Content-Type: application/json
Host: graph.windows.net
Content-Length: 104

{
    "name": "skypeId",
    "dataType": "String",
    "targetObjects": [
        "User"
    ]
}

Si l’opération fonctionne correctement, un code d’état HTTP 201 Created est renvoyé avec le nom complet de la propriété d’extension, qui peut être utilisé pour écrire des valeurs dans le type cible.

Exemple de réponse

HTTP/1.1 201 Created
...

{
    "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty/@Element",
    "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty",
    "objectType": "ExtensionProperty",
    "objectId": "dc893d45-a75b-4ccf-9b92-ce7d80922aa7",
    "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
    "dataType": "String",
    "targetObjects": [
        "User"
    ]
}

Afficher les extensions enregistrées

L’exemple de demande suivant permet d’obtenir les extensions enregistrées sur votre objet Application.

Format de la demande

GET https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties?api-version=1.5 HTTP/1.1

Exemple de demande

GET https://graph.windows.net/contoso.onmicrosoft.com/applications/269fc2f7-6420-4ea4-be90-9e1f93a87a64/extensionProperties?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

Si l’opération fonctionne correctement, un code d’état HTTP 200 OK est renvoyé avec toutes les informations concernant chaque propriété d’extension enregistrée sur votre objet Application.

Exemple de réponse

HTTP/1.1 200 OK
...

{
    "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty",
    "value": [
        {
            "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty",
            "objectType": "ExtensionProperty",
            "objectId": "dc893d45-a75b-4ccf-9b92-ce7d80922aa7",
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "dataType": "String",
            "targetObjects": [
                "User"
            ]
        }
    ]
}

Écrire une valeur d’extension

L’exemple de demande suivant permet d’écrire une valeur d’extension pour la propriété d’extension *skypeId^ sur un objet [User].

Format de la demande

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1

{
    "<extensionPropertyName>": <value>
}

Exemple de demande

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/jim@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Content-Type: application/json
Host: graph.windows.net
Content-Length: 65

{
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

Si l’opération fonctionne correctement, un code d’état HTTP 204 No Content est renvoyé.

Exemple de réponse

HTTP/1.1 204 No Content

Si la tentative d’écriture dépasse la limite de 100 valeurs d’extension pour l’objet, elle renvoie une réponse HTTP 403 Interdit avec le code d’erreur « Directory_ResourceSizeExceeded » et le message suivant : « L’objet a dépassé sa taille limite. Réduisez le nombre de valeurs et renouvelez votre demande ».

Supprimer une valeur d’extension

L’exemple de demande suivant permet de supprimer une valeur d’extension précédemment définie pour la propriété d’extension skypeIdsur un objet [User] en affectant null à la valeur.

Format de la demande

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1

{
    "<extensionPropertyName>": null
}

Exemple de demande

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/jim@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Content-Type: application/json
Host: graph.windows.net
Content-Length: 65

{
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": null
}

Si l’opération fonctionne correctement, un code d’état HTTP 204 No Content est renvoyé.

Exemple de réponse

HTTP/1.1 204 No Content

Lire une valeur d’extension

L’exemple de demande suivant permet de réaliser une opération GET simple sur l’utilisateur, ce qui a pour effet de renvoyer les valeurs de propriété standard ainsi que la nouvelle valeur de la propriété d’extension.

Format de la demande

GET https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1

Exemple de demande

GET https://graph.windows.net/contoso.onmicrosoft.com/users/jim@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

Si l’opération fonctionne correctement, un code d’état HTTP 200 OK est renvoyé avec la nouvelle valeur de la propriété d’extension (par souci de concision, un grand nombre de propriétés utilisateur ont été supprimées de l’exemple de réponse).

Exemple de réponse

HTTP/1.1 200 OK

{
    ...
    "usageLocation": null,
    "userPrincipalName": "Jim@contoso.onmicrosoft.com",
    "userType": "Member"
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

Filtrer une valeur d’extension

L’exemple de filtres de demande suivant permet de filtrer les utilisateurs en fonction de la valeur de la propriété d’extension spécifiée.

Remarque : les recherches de préfixe sont limitées à 71 caractères pour les recherches de chaîne et à 207 octets pour les recherches d’extensions binaires.

Format de la demande

GET https://graph.windows.net/contoso.onmicrosoft.com/users?api-version=1.5&$filter=<extensionName>%20eq%20'<value>' HTTP/1.1

Exemple de demande

GET https://graph.windows.net/contoso.onmicrosoft.com/users?api-version=1.5&$filter=extension_ab603c56068041afb2f6832e2a17e237_skypeId%20eq%20'jimbob.skype' HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

Si l’opération fonctionne correctement, un code d’état HTTP 200 OK est renvoyé avec l’objet utilisateur résultant.

Exemple de réponse

HTTP/1.1 200 OK

{
    ...
    "usageLocation": null,
    "userPrincipalName": "Jim@contoso.onmicrosoft.com",
    "userType": "Member"
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

Annuler l’enregistrement d’une extension

L’exemple de demande suivant permet d’annuler l’enregistrement d’une propriété d’extension en réalisant une opération DELETE sur l’ID d’objet de l’extension.

Format de la demande

DELETE https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties/<extensionObjectId>?api-version=1.5 HTTP/1.1

Exemple de demande

DELETE https://graph.windows.net/contoso.onmicrosoft.com/applications/269fc2f7-6420-4ea4-be90-9e1f93a87a64/extensionProperties/dc893d45-a75b-4ccf-9b92-ce7d80922aa7?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

Si l’opération fonctionne correctement, un code d’état HTTP 204 No Content est renvoyé et l’enregistrement de la propriété d’extension est annulé dans l’application.

Exemple de réponse

HTTP/1.1 204 No Content

Comportement et limitations de l’extension

Le comportement et les limitations suivantes s’appliquent aux propriétés d’extension dans un annuaire :

Les propriétés d’extension enregistrées pour une application deviennent disponibles dans un annuaire lorsqu’un utilisateur ou un administrateur d’annuaire donne son consentement à une application.
Dès qu’une propriété d’extension est disponible dans une application, n’importe quelle application consentie peut lire ou écrire une valeur dans cette propriété d’extension pour les objets auxquels cette propriété s’applique selon les autorisations de l’application dans l’annuaire. Les objets concernés par la propriété d’extension sont spécifiés dans la propriété targetObjects.
Un maximum de 100 valeurs de propriété d’extension peut être écrit sur un objet spécifique dans un annuaire. Par exemple, en supposant qu’aucune autre valeur de propriété d’extension n’a été écrite sur un utilisateur dans un annuaire, si une application écrit une valeur de propriété d’extension pour utilisateur1, alors il est possible d’écrire 99 autres propriétés d’extension pour celui-ci dans le cadre de cette application ou d’une autre possédant les autorisations appropriées dans l’annuaire ; pour les autres utilisateurs cependant, il sera toujours possible d’écrire un maximum de 100 valeurs de propriété d’extension.
Si une application tente de définir une valeur pour une propriété d’extension supplémentaire sur un objet pour lequel 100 valeurs d’extension ont été définies, l’API Graph renvoie une réponse 403 Interdit avec le code d’erreur « Directory_ResourceSizeExceeded » et le message suivant : « L’objet a dépassé sa taille limite. Réduisez le nombre de valeurs et renouvelez votre demande ».
Si un développeur annule l’enregistrement d’une propriété d’extension (la supprime) d’une application, cette propriété d’extension devient immédiatement inaccessible dans l’annuaire du développeur ainsi que dans les annuaires accessibles par l’application.
Si l’application est supprimée de l’annuaire d’un développeur, toutes les propriétés d’extension enregistrées pour celle-ci deviennent immédiatement inaccessibles dans l’annuaire du développeur et dans les annuaires pour lesquels l’application a reçu un consentement.
Si une application mutualisée a été consentie dans un annuaire, puis que son enregistrement est annulé (supprimé) de cet annuaire, par exemple, par un administrateur utilisant le portail de gestion Azure, les propriétés d’extension enregistrées sur l’application deviennent immédiatement inaccessibles dans ce répertoire.
Une valeur de propriété d’extension doit être explicitement définie sur null afin d’être supprimée d’un objet d’annuaire. Si la valeur d’une propriété d’extension est définie sur un objet d’annuaire et que cette propriété devient inaccessible dans l’annuaire pour l’une des raisons précitées, la propriété d’extension n’est plus visible pour cet objet d’annuaire. Elle est toutefois déduite de la limite des 100 valeurs de propriété d’extension pour cet objet. Jusqu’à ce que la propriété d’extension redevienne disponible, par exemple, dans certains cas, en accordant à nouveau un consentement à l’application, la valeur ne pourra être ni lue ni écrite.

Ressources supplémentaires

Référence de l’API Azure AD Graph

contact [Contract]: ../api/entity-and-complex-type-reference.md#contract-entity [Dispositif]: ../api/entity-and-complex-type-reference.md#device-entity [DirectoryLinkChange]: ../api/entity-and-complex-type-reference.md#directorylinkchange-entity [DirectoryObject]: ../api/entity-and-complex-type-reference.md#directoryobject-entity [DirectoryRole]: ../api/entity-and-complex-type-reference.md#directoryrole-entity [DirectoryRoleTemplate]: ../api/entity-and-complex-type-reference.md#directoryroletemplate-entity [ExtensionProperty]: ../api/entity-and-complex-type-reference.md#extensionproperty-entity [Groupe]: ../api/entity-and-complex-type-reference.md#group-entity [OAuth2PermissionGrant]: ../api/entity-and-complex-type-reference.md#oauth2permissiongrant-entity [ServicePrincipal]: ../api/entity-and-complex-type-reference.md#serviceprincipal-entity [SubscribedSku]: ../api/entity-and-complex-type-reference.md#subscribedsku-entity [TenantDetail]: ../api/entity-and-complex-type-reference.md#tenantdetail-entity [User]: ../api/entity-and-complex-type-reference.md#user-entity