Trabalhar com usuários no Microsoft Graph

O Microsoft Graph permite criar experiências de aplicativo com base nos usuários e suas relações com outros objetos, como grupos, emails, calendários, arquivos e funções administrativas. Você pode acessar e gerenciar dados do usuário por meio de operações comuns de API, modelos de autorização, privilégios e tratamento de ações confidenciais.

Acessando usuários

Acesse os usuários por meio do Microsoft Graph de duas maneiras:

  • Por sua ID ou userPrincipalName: /users/{id} ou /users/{userPrincipalName}
  • Usando o alias /me para o usuário conectado, que é igual a /users/{signed-in user's id}

Operações comuns de API

No Microsoft Graph, os usuários são representados pelo tipo de recurso de usuário . A tabela a seguir lista operações comuns que você pode executar em usuários.

Caminho Descrição
/me Obter os detalhes do usuário conectado.
/users Lista os usuários na organização.
/users/{id} Obtém um usuário específico por ID.
/users/{id}/photo/$value Obtém a foto de perfil do usuário.
/users/{id}/manager Obtém o gerente do usuário.
/users/{id}/messages Lista as mensagens de email do usuário em sua caixa de entrada principal.
/users/{id}/events Lista os eventos futuros do usuário em seu calendário.
/users/{id}/drive Obtém o repositório de arquivos do OneDrive do usuário.
/users/{id}/memberOf Lista os grupos dos quais o usuário é membro.
/users/{id}/joinedTeams Lista as Microsoft Teams das quais o usuário é membro.
POST /invitations Convide um convidado como parte da colaboração B2B (entre empresas) no ID externa do Microsoft Entra

Autorização e privilégios

O Microsoft Graph dá suporte a permissões delegadas e de aplicativo para gerenciar operações de usuário. Compreender essas permissões é crucial para o desenvolvimento de aplicativos seguros e eficientes.

Algumas operações do usuário podem ser executadas pelo usuário conectado em seus próprios detalhes. Para essas operações, o usuário pode conceder ao aplicativo permissões do Microsoft Graph para acessar seus próprios detalhes. As permissões User.ReadBasic.All, User.Read e User.ReadWrite são essas permissões.

Outras operações, incluindo o gerenciamento de detalhes para outros usuários, exigem privilégios administrativos concedidos por meio de permissões do Microsoft Graph que somente administradores autorizados podem consentir e funções do Microsoft Entra. Além disso, algumas operações são consideradas confidenciais e apenas administradores limitados podem executá-las. Para obter mais informações, consulte as seções Quem pode redefinir senhas e Quem pode atualizar atributos confidenciais .

Permissões de usuário padrão no Microsoft Entra ID

Existem dois tipos de usuários no Microsoft Entra ID: membros e convidados. Os membros são criados nativamente no locatário. Os convidados ingressam no locatário resgatando o convite e acessam o locatário como convidados de colaboração B2B (entre empresas).

Os usuários do Microsoft Entra ID têm permissões padrão que lhes permitem realizar determinadas operações. Esse conjunto de permissões padrão depende se o usuário é membro ou convidado, e o administrador do locatário pode alterar as configurações dessas permissões padrão. Para obter mais informações sobre o que os usuários membros e usuários convidados podem fazer, consulte Quais são as permissões de usuário padrão no Microsoft Entra ID?.

Permissões de usuário padrão em locatários externos

Também há permissões padrão para clientes no Microsoft Entra ID em locatários externos. A tabela a seguir mostra as operações de API que os clientes podem usar para gerenciar seus próprios perfis.

A ID de usuário ou userPrincipalName é sempre do usuário conectado.

Operação do usuário Operação da API Permissões obrigatórias
Ler perfil GET /me ou GET /users/{id or userPrincipalName} User.Read
Atualizar perfil PATCH /me ou PATCH /users/{id or userPrincipalName}

As seguintes propriedades são atualizáveis: city, country, displayName, givenName, jobTitle, postalCode, state, streetAddress, surname e preferredLanguage		 User.ReadWrite
Alterar senha POST /me/changePassword Directory.AccessAsUser.All

Propriedades básicas de perfil do usuário

A permissão User.ReadBasic.All restringe o acesso do aplicativo à leitura de um conjunto limitado de propriedades para contas corporativas ou de estudante de outros usuários. Esse perfil básico inclui apenas as seguintes propriedades:

  • displayName
  • givenName
  • id
  • Email
  • photo
  • securityIdentifier
  • surname
  • userPrincipalName

Além disso, as seguintes permissões específicas do cenário também permitem que os aplicativos leiam o perfil de usuário básico, que contém principalmente propriedades relacionadas ao identificador:

  • User-Mail.ReadWrite.All
  • User-PasswordProfile.ReadWrite.All
  • User-Phone.ReadWrite.All
  • User-LifeCycleInfo.Read.All
  • User-LifeCycleInfo.ReadWrite.All

Ações confidenciais

As ações a seguir em relação ao objeto de usuário são consideradas confidenciais e podem ser bloqueadas apenas para administradores específicos. Todos os usuários podem ler as propriedades confidenciais.

Ação confidencial Nome da propriedade confidencial
Desabilitar ou habilitar usuários accountEnabled
Atualizar telefone comercial businessPhones
Atualizar o celular mobilePhone
Atualizar ID imutável local onPremisesImmutableId
Atualizar outros emails otherMails
Atualizar perfil de senha passwordProfile
Atualizar o nome UPN userPrincipalName
Excluir ou restaurar usuários Não aplicável

Quem pode executar ações confidenciais

Na tabela a seguir, as colunas listam as funções que podem executar ações confidenciais. As linhas listam as funções para as quais a ação confidencial pode ser executada.

A tabela a seguir é para funções atribuídas no escopo de um locatário. Para funções atribuídas no escopo de uma unidade administrativa, outras restrições se aplicam.

Função sobre a qual a ação confidencial pode ser executada Administração de Autenticação User Administração Privileged Auth Administração Administrador Global
Administração de Autenticação ✅   ✅ ✅
Leitores de Diretório ✅ ✅ ✅ ✅
Administrador Global     ✅ ✅
Administração de Grupos   ✅ ✅ ✅
Emissor de convites independente ✅ ✅ ✅ ✅
Helpdesk Administração   ✅ ✅ ✅
Leitor do Centro de Mensagens ✅ ✅ ✅ ✅
Administração de Senha ✅ ✅ ✅ ✅
Privileged Auth Administração     ✅ ✅
Função Privilegiada de Administração     ✅ ✅
Leitor de Relatórios ✅ ✅ ✅ ✅
Usuário
(sem função de administrador)		 ✅ ✅ ✅ ✅
Usuário
(sem função de administrador, mas membro ou proprietário de um grupo atribuível à função)		     ✅ ✅
Usuário com uma função com escopo para uma unidade administrativa de gerenciamento restrita     ✅ ✅
User Administração   ✅ ✅ ✅
Leitor de relatórios de resumo do uso ✅ ✅ ✅ ✅
Todas as funções personalizadas ✅ ✅

Quem pode redefinir senhas

Na tabela a seguir, as colunas listam as funções que podem redefinir senhas e invalidar tokens de atualização. As linhas listam as funções para as quais a senha do usuário pode ser redefinida. Por exemplo, um Administrador de Senhas pode redefinir a senha para Leitores de Diretório, Emissor de Convites para Convites a Convite, Administrador de Senhas e usuários sem função de administrador. Se um usuário for atribuído a qualquer outra função, o administrador da senha não poderá redefinir sua senha.

A tabela a seguir é para funções atribuídas no escopo de um locatário. Para funções atribuídas no escopo de uma unidade administrativa, outras restrições se aplicam.

Função que a senha pode ser redefinida Administração de Senha Helpdesk Administração Administração de Autenticação User Administração Privileged Auth Administração Administrador Global
Administração de Autenticação     ✅   ✅ ✅
Leitores de Diretório ✅ ✅ ✅ ✅ ✅ ✅
Administrador Global         ✅ ✅*
Administração de Grupos       ✅ ✅ ✅
Emissor de convites independente ✅ ✅ ✅ ✅ ✅ ✅
Helpdesk Administração   ✅   ✅ ✅ ✅
Leitor do Centro de Mensagens   ✅ ✅ ✅ ✅ ✅
Administração de Senha ✅ ✅ ✅ ✅ ✅ ✅
Privileged Auth Administração         ✅ ✅
Função Privilegiada de Administração         ✅ ✅
Leitor de Relatórios   ✅ ✅ ✅ ✅ ✅
Usuário
(sem função de administrador)		 ✅ ✅ ✅ ✅ ✅ ✅
Usuário
(sem função de administrador, mas membro ou proprietário de um grupo atribuível à função)		         ✅ ✅
Usuário com uma função com escopo para uma unidade administrativa de gerenciamento restrita         ✅ ✅
User Administração       ✅ ✅ ✅
Leitor de relatórios de resumo do uso   ✅ ✅ ✅ ✅ ✅
Todas as funções personalizadas ✅ ✅

A capacidade de redefinir uma senha inclui a atualização das seguintes propriedades confidenciais necessárias para a redefinição de senha de autoatendimento:

  • businessPhones
  • mobilePhone
  • otherMails

Propriedades comuns

✅ Aplica-se somente à v1.0.

A seguir representa o conjunto padrão de propriedades que são retornadas ao obter um usuário ou listar usuários na v1.0. Eles são um subconjunto de todas as propriedades disponíveis na v1.0. Para obter mais propriedades do usuário, use o parâmetro de consulta $select. Saiba como usar o parâmetro $selecionar consulta e consulte propriedades que dão suporte ao parâmetro $selecionar consulta.

Para obter detalhes e uma lista de todas as propriedades, consulte o objeto de usuário .

Propriedade Descrição
id O identificador exclusivo do usuário.
businessPhones Os números de telefone do usuário.
displayName O nome exibido no catálogo de endereços do usuário.
givenName O nome do usuário.
jobTitle O cargo do usuário.
email O endereço de email do usuário.
mobilePhone O número de telefone celular do usuário.
officeLocation O local do escritório físico do usuário.
preferredLanguage O idioma preferencial do usuário.
surname O sobrenome do usuário.
userPrincipalName O nome UPN do usuário.

Para obter detalhes e uma lista de todas as propriedades, confira o objeto user.

Limitações de pesquisa de usuário e grupo para convidados

Os recursos de pesquisa de usuário e grupo permitem que o aplicativo pesquise usuários ou grupos em um diretório da organização executando consultas no conjunto de recursos /users ou /groups (por exemplo, https://graph.microsoft.com/v1.0/users). Tanto os administradores quanto os usuários que são membros têm esse recurso; No entanto, os usuários convidados não.

Se o usuário conectado for um convidado, dependendo das permissões que recebeu um aplicativo, ele pode ler o perfil de um usuário específico ou grupo (por exemplo, https://graph.microsoft.com/v1.0/users/241f22af-f634-44c0-9a15-c8cd2cea5531). No entanto, o usuário não pode executar consultas no conjunto de recursos /users ou /groups que, potencialmente, retornam mais de um recurso.

Com as permissões apropriadas, o aplicativo pode ler os perfis de usuários ou grupos que ele obtém seguindo os links nas propriedades de navegação. Por exemplo, /users/{id}/directReports ou /groups/{id}/members.

Propriedades não retornadas por padrão

Algumas propriedades do objeto de usuário não são retornadas por padrão e devem ser especificadas em um $select parâmetro de consulta. Por exemplo, aniversário e habilidades. Consulte a tabela de propriedades da entidade de usuário para identificar propriedades que são retornadas somente quando você $select.

Propriedades armazenadas fora do repositório de dados principal

Embora os dados de recursos do usuário sejam armazenados principalmente no Microsoft Entra ID, algumas de suas propriedades, como habilidades, são armazenadas no SharePoint Online. Na maioria dos casos, você não pode especificar essas propriedades no mesmo corpo da solicitação Criar ou Atualizar que outras propriedades de usuário.

As propriedades armazenadas fora do repositório de dados principal também não têm suporte como parte do controle de alterações. Portanto, uma alteração em qualquer uma dessas propriedades não resulta em um objeto aparecendo na resposta de consulta delta.

As seguintes propriedades no objeto de usuário são armazenadas fora do armazenamento de dados principal: signInActivity, cloudLicensing, mailboxSettings, deviceEnrollmentLimit, print, aboutMe, birthday, hireDate, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills.

Conclusão

O Microsoft Graph fornece recursos poderosos para gerenciar e interagir com os dados do usuário. Ao entender as diferentes permissões, operações comuns de API e lidar com ações confidenciais, você pode criar aplicativos seguros e eficientes. Para obter mais informações, consulte os links de conteúdo e documentação relacionados.

Conteúdo relacionado

  • Last updated on