Trabalhar com usuários no Microsoft Graph
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. |
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.