You can use Microsoft Graph to build compelling app experiences based on users, their relationships with other users and groups, and their mail, calendar, and files. You can access users through Microsoft Graph in two ways:. One of the following permissions is required to access user operations. The first three permissions can be granted to an app by a user. The rest can only be granted to an app by the administrator.
The following represent the default set of properties that are returned when getting a user or listing users. These are a subset of all available properties.
For details and a list of all the properties, see the user object. You may also leave feedback directly on GitHub.
Skip to main content. Exit focus mode. All User. Read User. ReadWrite User. All Directory.Authenticate and connect with Microsoft Graph - June 2019
All Common properties The following represent the default set of properties that are returned when getting a user or listing users. Property Description id The unique identifier for the user. Common operations Note: Some of these operations require additional permissions. Related Articles Is this page helpful?
Yes No.Represents an Azure AD user account.
Simplify user onboarding with Microsoft Graph
Inherits from directoryObject. This section explains how the three age group properties legalAgeGroupClassificationageGroup and consentProvidedForMinor are used by Azure AD administrators and enterprise application developers to meet age-related regulations.
For example: Cameron is administrator of a directory for an elementary school in Holyport in the United Kingdom. At the beginning of the school year he uses the admissions paperwork to obtain consent from the minor's parents based on the age-related regulations of the United Kingdom. The consent obtained from the parent allows the minor's account to be used by Holyport school and Microsoft apps.
Cameron then creates all the accounts and sets ageGroup to "minor" and consentProvidedForMinor to "granted". Applications used by his students are then able to suppress features that are not suitable for minors. This read-only property is used by enterprise application developers to ensure the correct handling of a user based on their legal age group. It is calculated based on the user's ageGroup and consentProvidedForMinor properties.
The age group and minor consent properties are optional properties used by Azure AD administrators to help ensure the use of an account is handled correctly based on the age-related regulatory rules governing the user's country or region. You may also leave feedback directly on GitHub. Skip to main content. Exit focus mode. This resource supports: Adding your own data to custom properties as extensions. Subscribing to change notifications.
Using delta query to track incremental additions, deletions, and updates, by providing a delta function. Create user user Create a new user object. Get user user Read properties and relationships of user object. Update user user Update user object. Delete user None Delete user object. Get delta user collection Get incremental changes for users. Calendar Create calendar calendar Create a new Calendar by posting to the calendars collection. Create event event Create a new Event by posting to the events collection.
List calendars calendar collection Get a Calendar object collection. List calendarView event collection Get a Event object collection. List events event collection Get a list of event objects in the user's mailbox. The list contains single instance meetings and series masters.
Contacts Create contact contact Create a new Contact by posting to the contacts collection. List contacts contact collection Get a contact collection from the default Contacts folder of the signed-in user. List contactFolders contactFolder collection Get the contact folder collection in the default Contacts folder of the signed-in user. Directory objects assignLicense user Add or remove subscriptions for the user. You can also enable and disable specific plans associated with a subscription.Create a new user.
The request body contains the user to create. At a minimum, you must specify the required properties for the user. You can optionally specify any other writable properties. To create external users, use the invitation API. One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions. In the request body, supply a JSON representation of user object. The following table lists the properties that are required when you create a user.
If you're including an identities property for the user you're creating, not all the properties listed are required. For a social identity, none of the properties are required. Because the user resource supports extensionsyou can use the POST operation and add custom properties with your own data to the user instance while creating it.
Federated users created using this API will be forced to sign-in every 12 hours by default. For more information on how to change this, see Exceptions for token lifetimes. If successful, this method returns Created response code and user object in the response body. Here is an example of the response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.
Create a new user, with a local account identity with a sign-in name, an email address as sign-in, and with a social identity. This example is typically used for migration scenarios in B2C tenants. For local account identities, password expirations must be disabled, and force change password at next sign-in must also be disabled.
Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call. You may also leave feedback directly on GitHub. Skip to main content. Exit focus mode. Note To create external users, use the invitation API. Note Federated users created using this API will be forced to sign-in every 12 hours by default.
Note For local account identities, password expirations must be disabled, and force change password at next sign-in must also be disabled. Is this page helpful?
Yes No. Any additional feedback? Skip Submit. Send feedback about This product This page.Subscribes a listener application to receive notifications when the requested type of changes occur to the specified resource in Microsoft Graph. Creating a subscription requires read scope to the resource. For example, to get notifications on messages, your app needs the Mail. Read permission. Depending on the resource and the permission type delegated or application requested, the permission specified in the following table is the least privileged required to call this API.
To learn more, including how to choose permissions, see Permissions. Note: There are additional limitations for subscriptions on OneDrive and Outlook items. The limitations apply to creating as well as managing subscriptions getting, updating, and deleting subscriptions. On personal OneDrive, you can subscribe to the root folder or any subfolder in that drive. On OneDrive for Business, you can subscribe to only the root folder.
Notifications are sent for the requested types of changes on the subscribed folder, or any file, folder, or other driveItem instances in its hierarchy. You cannot subscribe to drive or driveItem instances that are not folders, such as individual files. In Outlook, delegated permission supports subscribing to items in folders in only the signed-in user's mailbox. That means, for example, you cannot use the delegated permission Calendars.
Read to subscribe to events in another user's mailbox. To subscribe to change notifications of Outlook contacts, events, or messages in shared or delegated folders:. If successful, this method returns Created response code and a subscription object in the response body. In the request body, supply a JSON representation of the subscription object.
The clientState and latestSupportedTlsVersion fields are optional. Here is an example of the response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call. The subscription notification endpoint specified in the notificationUrl property must be capable of responding to a validation request as described in Set up notifications for changes in user data.
If validation fails, the request to create the subscription returns a Bad Request error. You may also leave feedback directly on GitHub. Skip to main content. Exit focus mode. Permissions Creating a subscription requires read scope to the resource.
Supported resource Delegated work or school account Delegated personal Microsoft account Application contact Contacts. Read Contacts. All Not supported Files.
All event Calendars. Read Calendars. Read group Group.Note: Getting a user returns a default set of properties only businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName.
One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions. This method supports the OData Query Parameters to help customize the response. By default, only a limited set of properties are returned businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName.
If successful, this method returns a OK response code and user object in the response body. This method returns Accepted when the request has been processed successfully but the server requires more time to complete related background operations.
Working with users in Microsoft Graph
This example illustrates the default request and response. You may also leave feedback directly on GitHub. Skip to main content. Exit focus mode.
Permissions One of the following permissions is required to call this API. Permission type Permissions from least to most privileged Delegated work or school account User.
Read, User. ReadWrite, User. All, User. All, Directory. All Delegated personal Microsoft account User. ReadWrite Application User. Response If successful, this method returns a OK response code and user object in the response body. Examples Example 1: Standard users request By default, only a limited set of properties are returned businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName.
Is this page helpful? Yes No.Before any user management application or script you write can interact with the resources in your Azure AD B2C tenant, you need an application registration that grants the permissions to do so. Follow the steps in this how-to article to create an application registration that your management application can use:. The displayName is the name to display in Azure portal user management for the user, and in the access token Azure AD B2C returns to the application.
This property is required. A customer account, which could be a consumer, partner, or citizen, can be associated with these identity types:. A user with a customer account can sign in with multiple identities. For example, username, email, employee ID, government ID, and others. A single account can have multiple identities, both local and social, with the same password. In the Microsoft Graph API, both local and federated identities are stored in the user identities attribute, which is of type objectIdentity.
The identities collection represents a set of identities used to sign in to a user account. This collection enables the user to sign in to the user account with any of its associated identities.
The following Identities property, with a local account identity with a sign-in name, an email address as sign-in, and with a social identity. For federated identities, depending on the identity provider, the issuerAssignedId is a unique value for a given user per application or development account.
Configure the Azure AD B2C policy with the same application ID that was previously assigned by the social provider or another application within the same development account.
For a local identity, the passwordProfile property is required, and contains the user's password. For a federated social identity, the passwordProfile property is not required. The Azure AD B2C sign-up or sign-in and password reset policies require this strong password strength, and don't expire passwords.
In user migration scenarios, if the accounts you want to migrate have weaker password strength than the strong password strength enforced by Azure AD B2C, you can disable the strong password requirement.
To change the default password policy, set the passwordPolicies property to DisableStrongPassword. For example, you can modify the create user request as follows:. Every customer-facing application has unique requirements for the information to be collected.For example, you can use Azure AD Graph API to create a new user, view or update user's properties, change user's password, check group membership for role-based access, disable, or delete the user. You specify the version for a Graph API request in the "api-version" query parameter.
For version 1. You can enter this URL in the address bar of a web browser to see the metadata. The CSDL metadata document returned describes the entities and complex types, their properties, and the functions and actions exposed by the version of Graph API you requested. Omitting the api-version parameter returns metadata for the most recent version. Azure AD Graph API common queries lists common queries that can be used with the Azure AD Graph, including queries that can be used to access top-level resources in your directory and queries to perform operations in your directory.
If you run Azure AD Graph Explorer against your own tenant, either you or your administrator needs to consent during sign-in. If you have an Office subscription, you automatically have an Azure AD tenant. Run a query : To run a query, type your query in the request text box and click GET or click the enter key. The results are displayed in the response box. For the purposes of this Quickstart guide, you can use the Fiddler Web Debugger to practice performing 'write' operations against your Azure AD directory.
For example, you can get and upload a user's profile photo which is not possible with Azure AD Graph Explorer. For more information, see Authentication scenarios for Azure AD. Since you want to create a new security group, select Post as the HTTP method from the pull-down menu. For more information about creating groups, see Create Group. You may also leave feedback directly on GitHub. Skip to main content. Exit focus mode. Is this page helpful?
Yes No. Any additional feedback? Skip Submit. Send feedback about This product This page. This page. Submit feedback. There are no open issues. View on GitHub.