Gerir os métodos de autenticação dos utilizadores com o Microsoft Graph
Artigo
Os métodos de autenticação são as formas como os utilizadores se autenticam no Microsoft Entra ID. Os seguintes métodos de autenticação estão disponíveis no Microsoft Entra ID atualmente e são geríveis através do Microsoft Graph:
Windows Hello para Empresas
Microsoft Authenticator
Chave de segurança FIDO2
Autenticação baseada em certificados
Tokens de hardware OATH (pré-visualização)
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 pode fazer com as APIs dos métodos de autenticação?
Pode utilizar as APIs do método de autenticação para integrar nas suas aplicações para gerir os métodos de autenticação de um utilizador. 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 a utilização de APIs de métodos de autenticação para cenários em que tenha de iterar toda a população de utilizadores para fins de auditoria ou verificação de segurança. Para estes tipos de cenários, recomendamos que utilize o registo do método de autenticação e as APIs de relatórios de utilização (algumas APIs estão disponíveis apenas no beta ponto final).
Utilizar políticas para gerir métodos de autenticação no seu inquilino
Pode escolher que métodos de autenticação são permitidos para os utilizadores no seu inquilino ao configurar políticas de método de autenticação. Para cada política, configure se o método de autenticação está ativado, as respetivas definições e pode definir explicitamente os grupos de utilizadores que têm permissão ou não para utilizar o método .
Cenário de exemplo
Neste artigo, irá aprender a:
Autenticar no 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
Passo 1: Autenticar no Microsoft Entra ID com as funções e permissões certas
Inicie sessão num 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. Pode utilizar um inquilino de teste com dados de exemplo para experimentar as APIs.
Em seguida, conceda à aplicação a permissão UserAuthenticationMethod.ReadWrite.All . Precisa desta permissão para realizar as operações de leitura e escrita neste cenário.
Agora pode começar a utilizar as APIs. Neste cenário, vai utilizar as APIs para gerir 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 major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
//other-imports
)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
methods, err := graphClient.Users().ByUserId("user-id").Authentication().Methods().Get(context.Background(), nil)
// 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();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
result = await graph_client.users.by_user_id('user-id').authentication.methods.get()
Nesta resposta, a Cameron tem apenas o método de autenticação de palavra-passe ativado.
28c10230-6103-485e-b985-444c60001490 é o ID exclusivo global do método de autenticação de palavra-passe no 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
Neste passo, vai adicionar um novo número de telemóvel para a Cameron utilizar.
// 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);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewPhoneAuthenticationMethod()
phoneNumber := "+1 2065555555"
requestBody.SetPhoneNumber(&phoneNumber)
phoneType := graphmodels.MOBILE_AUTHENTICATIONPHONETYPE
requestBody.SetPhoneType(&phoneType)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
phoneMethods, err := graphClient.Users().ByUserId("user-id").Authentication().PhoneMethods().Post(context.Background(), requestBody, nil)
// 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);
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\PhoneAuthenticationMethod;
use Microsoft\Graph\Generated\Models\AuthenticationPhoneType;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new PhoneAuthenticationMethod();
$requestBody->setPhoneNumber('+1 2065555555');
$requestBody->setPhoneType(new AuthenticationPhoneType('mobile'));
$result = $graphServiceClient->users()->byUserId('user-id')->authentication()->phoneMethods()->post($requestBody)->wait();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.phone_authentication_method import PhoneAuthenticationMethod
from msgraph.generated.models.authentication_phone_type import AuthenticationPhoneType
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = PhoneAuthenticationMethod(
phone_number = "+1 2065555555",
phone_type = AuthenticationPhoneType.Mobile,
)
result = await graph_client.users.by_user_id('user-id').authentication.phone_methods.post(request_body)
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 major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
//other-imports
)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
methods, err := graphClient.Users().ByUserId("user-id").Authentication().Methods().Get(context.Background(), nil)
// 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();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
result = await graph_client.users.by_user_id('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. Os IDs dos diferentes tipos de número de telefone são globalmente os mesmos no ID do Microsoft Entra da seguinte forma:
b6332ec1-7057-4abe-9331-3d72feddfe41para o tipo de telefone alternateMobile
e37fc753-ff3b-4958-9484-eaa9425c82bcpara tipo de telefone de escritório
3179e48a-750b-4051-897c-87b9720928f7para o tipo de telemóvel
Passo 5: Remover um número de telefone do utilizador
O Cameron está agora a trabalhar a partir de casa, por isso tens de 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();
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
//other-imports
)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Users().ByUserId("user-id").Authentication().PhoneMethods().ByPhoneAuthenticationMethodId("phoneAuthenticationMethod-id").Delete(context.Background(), nil)
// 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();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
await graph_client.users.by_user_id('user-id').authentication.phone_methods.by_phone_authentication_method_id('phoneAuthenticationMethod-id').delete()
A solicitação retorna o código de resposta 204 No Content. Para verificar se o método office phone foi removido da conta de Cameron, execute novamente o pedido no Passo 4. A Cameron deverá agora ter apenas os métodos de autenticação de telemóvel e palavra-passe.
Passo 6: Repor a palavra-passe do utilizador
A Cameron esqueceu-se da palavra-passe e tens de a repor para eles. Pode repor a palavra-passe de um utilizador e especificar uma palavra-passe temporária ou permitir que o ID do Microsoft Entra gere uma palavra-passe temporária.
Em ambos os métodos, a resposta inclui um cabeçalho Localização com um URL que pode utilizar para verificar o estado da operação através de uma operação GET. A operação de reposição não é concluída imediatamente, uma vez que o Microsoft Entra ID tem de sincronizar a palavra-passe, incluindo o Active Directory na infraestrutura no local do inquilino (para utilizadores no local). O URL é válido durante 24 horas.
Opção 1: Repor a palavra-passe do utilizador e fornecer uma nova palavra-passe 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";
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestAadgdc := "AM4P"
requestAadgsu := "ssprprod-a"
requestParameters := &graphusers.ItemAuthenticationOperationsItemRequestBuilderGetQueryParameters{
Aadgdc: &requestAadgdc,
Aadgsu: &requestAadgsu,
}
configuration := &graphusers.ItemAuthenticationOperationsItemRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
operations, err := graphClient.Users().ByUserId("user-id").Authentication().Operations().ByLongRunningOperationId("longRunningOperation-id").Get(context.Background(), configuration)
// 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";
});
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.authentication.operations.item.long_running_operation_item_request_builder import LongRunningOperationItemRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = LongRunningOperationItemRequestBuilder.LongRunningOperationItemRequestBuilderGetQueryParameters(
aadgdc = "AM4P",
aadgsu = "ssprprod-a",
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.by_user_id('user-id').authentication.operations.by_long_running_operation_id('longRunningOperation-id').get(request_configuration = request_configuration)
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?