Export (0) Print
Expand All

Azure AD Graph API Directory Schema Extensions

Updated: May 26, 2015

This topic discusses directory extensions in the Azure AD Graph API, which can be used to add properties to directory objects without requiring an external data store. For example, if an organization has a line of business (LOB) application that requires a Skype Id for each user in the directory, the Graph API can be used to register a new skypeId property on the directory’s User object, and then write a value to the new property for a specific user. Read the sections below to understand the limitations of directory extensions, how they’re registered in a directory, and examples of how they’re used in the Graph API.

Extensions can only be registered using Graph API version 1.5 or newer. Each directory is limited to a total of 100 registered extensions per object for all registered applications. For example, if an application registers 99 extension properties on a directory’s User object, only one more property can be registered on the User object by other applications. The following property types can be registered:

 

Property Type Remarks

Binary

256 bytes maximum.

Boolean

DateTime

Must be specified in ISO 8601 format. Will be stored in UTC.

Integer

32-bit value.

LargeInteger

64-bit value.

String

256 characters maximum.

The property types above can be registered on the following objects in a directory:

It’s important to understand how an extension property is registered in a directory and how Azure AD’s consent model affects its registration. For more information about application consent in Azure AD, see Overview of the Consent Framework.

Extension properties are registered on an Application object within the developer’s directory. After registration, the property is added to the target directory type and becomes immediately accessible in the developer’s directory. For a multi-tenant application, when the application is granted consent by a user in another organization, the extension properties become immediately accessible on the target directory type in the other organization’s directory.

If an organization consents to “read only” permissions for an application with registered extensions, the properties will still become accessible in the other organization’s directory. Additionally, extension properties are accessible by any consented application in an organization, not just for the application to which they are registered. Other consented applications in that organization can read or write values for the new extension property if they have sufficient permissions.

If the application is deleted or consent is removed in the other organization’s directory, the extension property is removed on the target directory object. If the extension is deleted by the application, it is removed on the target directory object. If a multi-tenant application adds additional extension properties after consent was granted, these properties will also become immediately accessible in the other organization’s directory.

Example Scenario

Consider the following scenario: Litware is an independent software vendor (ISV) that has developed a SaaS application for other organizations to use, and this application requires an extension property named skypeId on a User object. Litware first registers the application in its own directory, and then the Graph API is called to register the extension property on the Application object, which makes the property accessible on User objects in Litware’s directory. Finally, Litware makes the application multi-tenant capable so that it can be used in other organizations.

Contoso wants to use Litware’s SaaS application, so a user or administrator in Contoso consents to the application. Upon consent, the application is registered in Contoso’s directory and the extension properties registered for the application by Litware immediately become available in the Contoso directory. Since the skypeId extension property for a User object was registered by Litware on the application, the property becomes accessible on User objects in Contoso’s directory. Litware’s application or other consented applications in Contoso’s directory can now access the new property according to the permissions configured for that application in Contoso’s directory.

The following sample requests show you how to register, view, write, read, filter, and unregister extensions in your directory. Replace the <applicationObjectId> placeholder with your registered application’s Object ID. You can get this value in the following way:

  1. Go to https://graphexplorer.cloudapp.net/, click the Sign In link at the top-right corner, and then sign in using the credentials for an administrator account in your organization’s directory.

  2. After you have signed in, add applications/ to the URL in the Resource field and click Get.

  3. Find the desired application entry from the results, and then copy its objectId value, such as the following: "objectId": "269fc2f7-6420-4ea4-be90-9e1f93a87a64"

In this topic, there are sample requests for the following operations:

For full samples that use extension properties, see the following samples in the Azure AD samples on Github:

The following sample request creates an extensionProperty on the desired Application object.

Request Format

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>"
    ]
}

Sample Request

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"
    ]
}

If the operation was successful, it will return an HTTP 201 Created status code along with the fully-qualified extension property name, which can be used for writing values to the target type.

Sample Response

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"
    ]
}

The following sample request gets the extensions that are registered on your Application object.

Request Format

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

Sample Request

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

If the operation was successful, it will return an HTTP 200 OK status code along with all the information about each extension property registered on your Application object.

Sample Response

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"
            ]
        }
    ]
}

The following sample request writes an extension value for the skypeId extension property on a User object.

Request Format

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

{
    "<extensionPropertyName>": <value>
}

Sample Request

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"
}

If the operation was successful, it will return a HTTP 204 No Content status code.

Sample Response

HTTP/1.1 204 No Content
...

The following sample request removes an extension value that was previously set for the skypeId extension property on a User object by setting the value to null.

Request Format

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

{
    "<extensionPropertyName>": null
}

Sample Request

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
}

If the operation was successful, it will return a HTTP 204 No Content status code.

Sample Response

HTTP/1.1 204 No Content
...

The following sample request performs a simple GET operation on the user, which will return the standard property values as well as the new extension property value.

Request Format

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

Sample Request

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

If the operation was successful, it will return an HTTP 200 OK status code along with the new extension property value (many user properties have been removed from the sample response for brevity).

Sample Response

HTTP/1.1 200 OK

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

The following sample request filters the users by the specified extension property value.

noteNote
Prefix searches on extensions are limited to 71 characters for string searches and 207 bytes for searches on binary extensions.

Request Format

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

Sample Request

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

If the operation was successful, it will return an HTTP 200 OK status code, along with the resulting user object.

Sample Response

HTTP/1.1 200 OK

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

The following sample request unregisters an extension property by performing a DELETE operation on the extension object ID.

Request Format

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

Sample Request

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

If the operation was successful, it will return an HTTP 204 No Content status code, and the extension property will be unregistered on the application.

Sample Response

HTTP/1.1 204 No Content

See Also

Show:
© 2015 Microsoft