Gerenciar métodos de autenticação dos usuários usando o Microsoft Graph
Artigo
Os métodos de autenticação são as maneiras pelas quais os usuários se autenticam em Microsoft Entra ID. Os seguintes métodos de autenticação estão disponíveis no Microsoft Entra ID atualmente e são gerenciáveis por meio do Microsoft Graph:
Windows Hello para Empresas
Microsoft Authenticator
Chave de segurança FIDO2
Autenticação baseada em certificados
Tokens de hardware OATH (versão prévia)
Tokens de software OATH
Passe de Acesso Temporário (TAP)
SMS
Voz
Senha
Os métodos de autenticação são usados nas autenticações primária, de segundo fator e de step-up. Além disso, no processo de redefinição de senha de autoatendimento (SSPR).
O que você pode fazer com as APIs de métodos de autenticação?
Você pode usar as APIs do método de autenticação para integrar aos seus aplicativos para gerenciar os métodos de autenticação de um usuário. Por exemplo, você pode:
Adicionar um número de telefone para um usuário, que pode usar esse número para SMS e autenticação de chamada de voz, se estiverem habilitados para o uso pela política
Atualizar ou excluir o número de telefone atribuído a um usuário
Habilitar ou desabilitar o número para entrada de SMS
Redefinir a senha de um usuário
Importante
Não recomendamos usar as APIs de métodos de autenticação para cenários em que você precisa iterar sobre toda a população de usuários para fins de auditoria ou segurança marcar. Para esses tipos de cenários, recomendamos usar as APIs de registro e relatório de uso do método de autenticação (algumas APIs estão disponíveis apenas no beta ponto de extremidade).
Usar políticas para gerenciar métodos de autenticação em seu locatário
Você pode escolher quais métodos de autenticação são permitidos para usuários em seu locatário configurando políticas de método de autenticação. Para cada política, você configura se o método de autenticação está habilitado, suas configurações e pode definir explicitamente os grupos de usuários permitidos ou não para usar o método.
Cenário de exemplo
Neste artigo, você aprenderá a:
Autenticar para Microsoft Entra ID com as funções e permissões certas
Verificar os métodos de autenticação do usuário
Adicionar novos números de telefone para o usuário
Remover um número de telefone do usuário
Redefinir a senha do usuário
Etapa 1: Autenticar para Microsoft Entra ID com as funções e permissões certas
Entre em um cliente de API, como o Graph Explorer com uma conta que tenha pelo menos a função Administrador de Autenticação Privilegiada ou Administrador de AutenticaçãoMicrosoft Entra função. Você pode usar um locatário de teste com dados de exemplo para experimentar as APIs.
Em seguida, conceda ao aplicativo a permissão UserAuthenticationMethod.ReadWrite.All . Você precisa dessa permissão para executar as operações de leitura e gravação nesse cenário.
Agora você pode começar a usar as APIs. Nesse cenário, você usa as APIs para gerenciar os métodos de autenticação de Cameron White.
Etapa 2: Verificar os métodos de autenticação do usuário
GET https://graph.microsoft.com/v1.0/users/CameronW@Contoso.com/authentication/methods
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Authentication.Methods.GetAsync();
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
AuthenticationMethodCollectionResponse result = graphClient.users().byUserId("{user-id}").authentication().methods().get();
A partir dessa resposta, Cameron tem apenas o método de autenticação de senha habilitado. 28c10230-6103-485e-b985-444c60001490é a ID globalmente exclusiva do método de autenticação de senha em Microsoft Entra ID.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('CameronW%40contoso.com')/authentication/methods",
"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET users('<key>')/authentication/methods?$select=id",
"value": [
{
"@odata.type": "#microsoft.graph.passwordAuthenticationMethod",
"id": "28c10230-6103-485e-b985-444c60001490",
"password": null,
"createdDateTime": "2023-09-18T10:38:07Z"
}
]
}
Etapa 3: Adicionar novos números de telefone para o usuário
Nesta etapa, você adiciona um novo número de telefone celular para Cameron usar.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new PhoneAuthenticationMethod
{
PhoneNumber = "+1 2065555555",
PhoneType = AuthenticationPhoneType.Mobile,
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Authentication.PhoneMethods.PostAsync(requestBody);
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users authentication phone-methods create --user-id {user-id} --body '{\
"phoneNumber": "+1 2065555555",\
"phoneType": "mobile"\
}\
'
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
PhoneAuthenticationMethod phoneAuthenticationMethod = new PhoneAuthenticationMethod();
phoneAuthenticationMethod.setPhoneNumber("+1 2065555555");
phoneAuthenticationMethod.setPhoneType(AuthenticationPhoneType.Mobile);
PhoneAuthenticationMethod result = graphClient.users().byUserId("{user-id}").authentication().phoneMethods().post(phoneAuthenticationMethod);
GET https://graph.microsoft.com/v1.0/users/CameronW@Contoso.com/authentication/methods
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Authentication.Methods.GetAsync();
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
AuthenticationMethodCollectionResponse result = graphClient.users().byUserId("{user-id}").authentication().methods().get();
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('CameronW%40contoso.com')/authentication/methods",
"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET users('<key>')/authentication/methods?$select=id",
"value": [
{
"@odata.type": "#microsoft.graph.phoneAuthenticationMethod",
"id": "e37fc753-ff3b-4958-9484-eaa9425c82bc",
"phoneNumber": "+1 4255550199",
"phoneType": "office",
"smsSignInState": "notSupported"
},
{
"@odata.type": "#microsoft.graph.phoneAuthenticationMethod",
"id": "3179e48a-750b-4051-897c-87b9720928f7",
"phoneNumber": "+1 2065555555",
"phoneType": "mobile",
"smsSignInState": "notAllowedByPolicy"
},
{
"@odata.type": "#microsoft.graph.passwordAuthenticationMethod",
"id": "28c10230-6103-485e-b985-444c60001490",
"password": null,
"createdDateTime": "2023-09-18T10:38:07Z"
}
]
}
Confirme se você consegue ver os dois números conforme o esperado. As IDs dos diferentes tipos de número de telefone são globalmente as mesmas em Microsoft Entra ID da seguinte maneira:
b6332ec1-7057-4abe-9331-3d72feddfe41para o tipo de telefone alternateMobile
e37fc753-ff3b-4958-9484-eaa9425c82bcpara o tipo de telefone do office
3179e48a-750b-4051-897c-87b9720928f7para o tipo de telefone celular
Etapa 5: remover um número de telefone do usuário
Cameron está trabalhando em casa, então você precisa remover o número do escritório da conta dele.
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Users["{user-id}"].Authentication.PhoneMethods["{phoneAuthenticationMethod-id}"].DeleteAsync();
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users authentication phone-methods delete --user-id {user-id} --phone-authentication-method-id {phoneAuthenticationMethod-id}
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
graphClient.users().byUserId("{user-id}").authentication().phoneMethods().byPhoneAuthenticationMethodId("{phoneAuthenticationMethod-id}").delete();
<?php
use Microsoft\Graph\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$graphServiceClient->users()->byUserId('user-id')->authentication()->phoneMethods()->byPhoneAuthenticationMethodId('phoneAuthenticationMethod-id')->delete()->wait();
A solicitação retorna o código de resposta 204 No Content. Para verificar se o método de telefone do office foi removido da conta de Cameron, execute novamente a solicitação na Etapa 4. Cameron agora deve ter apenas os métodos de autenticação de celular e senha.
Etapa 6: redefinir a senha do usuário
Cameron esqueceu a senha deles e você precisa redefini-la para eles. Você pode redefinir a senha de um usuário e especificar uma senha temporária ou permitir que Microsoft Entra ID gere uma senha temporária.
Em ambos os métodos, a resposta inclui um cabeçalho Local com uma URL que você pode usar para marcar o status da operação por meio de uma operação GET. A operação de redefinição não é concluída imediatamente, pois Microsoft Entra ID precisa sincronizar a senha, inclusive até o Active Directory na infraestrutura local do locatário (para usuários locais). A URL é válida por 24 horas.
Opção 1: redefinir a senha do usuário e fornecer uma nova senha temporária
GET https://graph.microsoft.com/v1.0/users/a87cc624-b550-4559-b934-3bc0325a4808/authentication/operations/ba0c9a11-5163-4353-89ba-81501617ede0?aadgdc=AM4P&aadgsu=ssprprod-a
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Authentication.Operations["{longRunningOperation-id}"].GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Aadgdc = "AM4P";
requestConfiguration.QueryParameters.Aadgsu = "ssprprod-a";
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users authentication operations get --user-id {user-id} --long-running-operation-id {longRunningOperation-id}
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
LongRunningOperation result = graphClient.users().byUserId("{user-id}").authentication().operations().byLongRunningOperationId("{longRunningOperation-id}").get(requestConfiguration -> {
requestConfiguration.queryParameters.aadgdc = "AM4P";
requestConfiguration.queryParameters.aadgsu = "ssprprod-a";
});
HTTP/1.1 202 Accepted
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('a87cc624-b550-4559-b934-3bc0325a4808')/authentication/operations/$entity",
"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET users('<guid>')/authentication/operations('<guid>')?$select=createdDateTime,lastActionDateTime",
"id": "ba0c9a11-5163-4353-89ba-81501617ede0",
"createdDateTime": "2024-01-18T16:37:10Z",
"lastActionDateTime": "2024-01-18T16:37:10Z",
"status": "succeeded",
"statusDetail": "ResetSuccess",
"resourceLocation": "https://graph.microsoft.com/v1.0/users/a87cc624-b550-4559-b934-3bc0325a4808/authentication/methods/28c10230-6103-485e-b985-444c60001490"
}
Referência da API
Está procurando a referência de API para métodos de autenticação?
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.