Trabalhar com usuários no Microsoft Graph

  • Artigo

Você pode usar o Microsoft Graph para criar experiências de aplicativo atraentes com base nos usuários e em suas relações com outros objetos. Por exemplo, suas relações com outros usuários e grupos, associações de grupo e os recursos que acessam, como seus emails, calendários, arquivos e funções administrativas.

Você pode acessar usuários pelo 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

Caminho Descrição
/me Obtenha 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.

Autorização e privilégios

O Microsoft Graph dá suporte ao uso de permissões delegadas e de aplicativos para gerenciar operações de usuário. Para obter mais informações, consulte Permissões Delegadas vs Aplicativo e a documentação de referência da API correspondente para as permissões necessárias para cada operação.

Algumas operações de usuário podem ser executadas pelo usuário conectado em relação aos seus próprios detalhes. Para essas operações, o usuário pode conceder ao aplicativo as 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 outras permissões do Microsoft Graph e Microsoft Entra funções. Além disso, algumas operações são consideradas confidenciais e apenas administradores limitados podem executá-las. Para obter mais informações, consulte Quem pode redefinir senhas e Quem pode atualizar seções de atributos confidenciais .

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

Há dois tipos de usuários no Microsoft Entra ID - membros e convidados. Inicialmente, os usuários membros são criados nativamente no locatário. Os usuários convidados ingressam no locatário resgatando seu convite e acessam o locatário como convidados de colaboração comercial para empresas (B2B).

O conjunto de permissões padrão depende se o usuário é um membro ou um usuário convidado. Para obter mais informações sobre o que 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 de clientes

Há também permissões padrão para clientes em Microsoft Entra ID para clientes. A tabela a seguir indica as operações de API que permitem que os clientes gerenciem seu próprio perfil.

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

Operação do usuário Operação de API Permissões obrigatórias
Perfil de leitura 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 updatable: city, country, displayName, givenName, jobTitle, postalCode, state, streetAddress, sobrenome e preferredLanguage		 User.ReadWrite
Alterar senha POST /me/changePassword Directory.AccessAsUser.All

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 pode ser redefinida. Por exemplo, um Administrador de Senhas pode redefinir a senha para leitores de diretório, convidado, administrador de senha e usuários sem função de administrador. Se um usuário receber qualquer outra função, o Administrador de Senhas 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 Auth Administração Administração de usuário Privileged Auth Administração Administrador Global
Auth Administração     ✅   ✅ ✅
Leitores de Diretório ✅ ✅ ✅ ✅ ✅ ✅
Administrador Global         ✅ ✅*
Grupos Administração       ✅ ✅ ✅
Convidado ✅ ✅ ✅ ✅ ✅ ✅
Helpdesk Administração   ✅   ✅ ✅ ✅
Leitor do Centro de Mensagens   ✅ ✅ ✅ ✅ ✅
Administração de senha ✅ ✅ ✅ ✅ ✅ ✅
Privileged Auth Administração         ✅ ✅
Administração de função privilegiada         ✅ ✅
Leitor de Relatórios   ✅ ✅ ✅ ✅ ✅
Usuário
(sem função de administrador)		 ✅ ✅ ✅ ✅ ✅ ✅
Usuário
(nenhuma função de administrador, mas membro ou proprietário de um grupo atribuível a função		         ✅ ✅
Usuário com uma função com escopo para uma unidade administrativa de gerenciamento restrito         ✅ ✅
Administração de usuário       ✅ ✅ ✅
Leitor de relatórios de resumo do uso   ✅ ✅ ✅ ✅ ✅
Todas as funções personalizadas ✅ ✅

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

  • businessPhones
  • mobilePhone
  • otherMails

Quem pode executar ações confidenciais

Alguns administradores podem executar as seguintes ações confidenciais para alguns usuários. 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 A ID imutável local onPremisesImmutableId
Atualizar outros emails otherMails
Atualizar perfil de senha passwordProfile
Atualizar o nome da entidade de usuário userPrincipalName
Excluir ou restaurar usuários Não aplicável

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 na qual a ação confidencial pode ser executada Auth Administração Administração de usuário Privileged Auth Administração Administrador Global
Auth Administração ✅   ✅ ✅
Leitores de Diretório ✅ ✅ ✅ ✅
Administrador Global     ✅ ✅
Grupos Administração   ✅ ✅ ✅
Convidado ✅ ✅ ✅ ✅
Helpdesk Administração   ✅ ✅ ✅
Leitor do Centro de Mensagens ✅ ✅ ✅ ✅
Administração de senha ✅ ✅ ✅ ✅
Privileged Auth Administração     ✅ ✅
Administração de função privilegiada     ✅ ✅
Leitor de Relatórios ✅ ✅ ✅ ✅
Usuário
(sem função de administrador)		 ✅ ✅ ✅ ✅
Usuário
(nenhuma função de administrador, mas membro ou proprietário de um grupo atribuível a função)		     ✅ ✅
Usuário com uma função com escopo para uma unidade administrativa de gerenciamento restrito     ✅ ✅
Administração de usuário   ✅ ✅ ✅
Leitor de relatórios de resumo do uso ✅ ✅ ✅ ✅
Todas as funções personalizadas ✅ ✅

Propriedades comuns

O item a seguir representa o conjunto padrão de propriedades que serão retornadas ao se obter um usuário ou listar usuários. Este é um subconjunto de todas as propriedades disponíveis. 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.

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 usuários convidados em organizações

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). Administradores e usuários que são membros têm essa funcionalidade; 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 parâmetro de $select consulta. Por exemplo, aniversário e habilidades. Consulte a tabela de propriedades da entidade de usuário para identificar propriedades retornadas somente quando você $select.

Propriedades armazenadas fora do armazenamento de dados main

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

As propriedades armazenadas fora do armazenamento de dados main 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.

Conteúdo relacionado