Retrieve user information

  • 3 minutes

In this unit you learn how to retrieve Microsoft Graph user data from a Microsoft Teams app and understand the permissions required for different scenarios.

The User resource

Users in Microsoft Graph are the representation of a Microsoft Entra work or school user account or a Microsoft account. You can use Microsoft Graph to access the relationships, documents, contacts, and preferences that are contextually relevant to the signed-in user. The user can be the currently signed-in user, or another user if your identity and application has been granted the necessary permissions.

Scenarios

What kinds of things can you do with the Microsoft Graph user resource?

  • Manage your organization: Create new users in your organization or update the resources and relationships for existing users. For example, list a user's group memberships and determine whether a user is a member of a group.

  • Manage calendars: View, query, and update user calendar and calendar groups associated with a user. For example, list and create events on a user's calendar.

  • Administer mail and handle contacts: You can configure user mail settings and contact lists and send mail on a user's behalf. For example, create and list user contacts and organize contacts in folders.

  • Enrich your app with user insights: Maximize relevance in your application by promoting recently used or trending documents and contacts associated with a user. For example, return documents recently viewed and modified by a user.

Retrieve user information

Accessing specific users

There are two ways you can access users through Microsoft Graph.

Access the signed-in user through the "me" alias at https://graph.microsoft.com/v1.0/me. This alias maps to the same endpoint as /users/{signed-in user's id}.

To access a specific user, use either their ID or their userPrincipalName. For example:

  • https://graph.microsoft/com/v1.0/users/{user's ID}
  • https://graph.microsoft/com/v1.0/users/{userPrincipalName}

Here's an example of a user request using the Graph SDK:

// GET https://graph.microsoft.com/v1.0/me
const user = await graphClient.api('/me').get();

Accessing all users in the organization

Microsoft Graph also enables developers to get a list of users. The /users endpoint will return all users in the organization using the Microsoft Graph API.

Retrieving a list of entities is similar to retrieving a single entity, except other options exist for configuring the request. The $filter query parameter can reduce the result set to only those rows that match the provided condition. The $orderby query parameter requests that the server provide the list of entities sorted by the specified properties.

Here's an example demonstrating retrieving a list of messages with the subject "Hello world," retrieving only the subject and sender for each message:

// GET https://graph.microsoft.com/v1.0/me/messages?
// $select=subject,sender&$filter=subject eq 'Hello world'
const messages = await graphClient
  .api('/me/messages')
  .select(['subject', 'sender'])
  .filter(`subject eq 'Hello world'`)
  .get();

The object returned when retrieving a list of entities is likely to be a paged collection.

User permissions

To perform user operations, you'll need one of the following permissions. The specific permission required will depend on the operation you want to perform.

For example, if you're creating, editing or deleting a user, one of the write permissions is required. Some permissions can be granted by a user while others must be granted to the app by an administrator.

Users can grant delegated permission to access the following information on-behalf-of the signed-in user. These are all delegated permissions:

  • User.ReadBasic.All: Allows the app to read the basic profile information of all users in the organization on-behalf-of the signed-in user. This includes display name, first and last name, email address and photo.
  • User.Read: Allows users to sign into the app, and allows the app to read the profile of signed-in users. It also allows the app to read basic company information of signed-in users.
  • User.ReadWrite: Allows the app to read the signed-in user's profile. It also allows the app to update the signed-in user's profile information on their behalf.

Administrators must grant the following permissions, which may be granted as delegated permissions (performed on-behalf-of the signed-in user) or application permissions (performed without a signed-in user):

  • User.Read.All
  • User.ReadWrite.All
  • Directory.Read.All
  • Directory.ReadWrite.All
  • Directory.AccessAsUser.All

Each user resource has more referenced resources such as their email messages (/messages), calendar items (/events), and files in OneDrive Consumer or OneDrive for Business (/drive).