Partilhar via


Gerir os métodos de autenticação dos utilizadores com o Microsoft Graph

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

Solicitação

GET https://graph.microsoft.com/v1.0/users/CameronW@Contoso.com/authentication/methods

Resposta

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.

Solicitação

POST https://graph.microsoft.com/v1.0/users/CameronW@Contoso.com/authentication/phoneMethods
Content-Type: application/json

{
    "phoneNumber": "+1 2065555555",
    "phoneType": "mobile"
}

Resposta

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('CameronW%40contoso.com')/authentication/phoneMethods/$entity",
    "id": "3179e48a-750b-4051-897c-87b9720928f7",
    "phoneNumber": "+1 2065555555",
    "phoneType": "mobile",
    "smsSignInState": "notAllowedByPolicy"
}

Execute o mesmo pedido, adicionando um office phoneType.

Passo 4: Verificar os métodos de autenticação do utilizador

Solicitação

GET https://graph.microsoft.com/v1.0/users/CameronW@Contoso.com/authentication/methods

Resposta

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.

DELETE https://graph.microsoft.com/v1.0/users/CameronW@Contoso.com/authentication/phoneMethods/e37fc753-ff3b-4958-9484-eaa9425c82bc

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

Solicitação

POST https://graph.microsoft.com/v1.0/users/CameronW@Contoso.com/authentication/passwordMethods/28c10230-6103-485e-b985-444c60001490/resetPassword
Content-Type: application/json

{
    "newPassword": "29sdjfw#fajsdA_a_3an3223"
}

Resposta

HTTP/1.1 202 Accepted

Location: https://graph.microsoft.com/v1.0/users/a87cc624-b550-4559-b934-3bc0325a4808/authentication/operations/cc8e9b0e-7495-47f2-ad4a-3daa966543c6?aadgdc=DUB02P&aadgsu=ssprprod-a

Opção 2: Repor a palavra-passe do utilizador e permitir que o ID do Microsoft Entra gere uma nova palavra-passe temporária

Neste pedido, não fornece uma nova palavra-passe e, em vez disso, permite que o Microsoft Entra ID gere uma palavra-passe e devolva-a na resposta.

POST https://graph.microsoft.com/v1.0/users/CameronW@Contoso.com/authentication/passwordMethods/28c10230-6103-485e-b985-444c60001490/resetPassword

Resposta

HTTP/1.1 202 Accepted

Location: https://graph.microsoft.com/v1.0/users/a87cc624-b550-4559-b934-3bc0325a4808/authentication/operations/ba0c9a11-5163-4353-89ba-81501617ede0?aadgdc=AM4P&aadgsu=ssprprod-a
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.passwordResetResponse",
    "newPassword": "Hopu0277"
}

Verificar o estado da operação de reposição de palavra-passe

Solicitação

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

Resposta

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?