Compartilhar via

Como gerenciar tokens OATH no Microsoft Entra ID (versão prévia)

Esse tópico aborda como gerenciar tokens OATH de hardware no Microsoft Entra ID, incluindo APIs do Microsoft Graph que você pode usar para carregar, ativar e atribuir tokens OATH.

Gerenciar tokens OATH de hardware na política de métodos de autenticação (versão prévia)

Você pode exibir e habilitar tokens OATH de hardware na política de métodos de autenticação usando as APIs do Microsoft Graph ou o Centro de administração do Microsoft Entra.

  • Para exibir o status da política de tokens OATH de hardware usando as APIs:

    GET https://graph.microsoft.com/beta/policies/authenticationMethodsPolicy/authenticationMethodConfigurations/hardwareOath

  • Para habilitar o status da política de tokens OATH de hardware usando as APIs.

    PATCH https://graph.microsoft.com/beta/policies/authenticationMethodsPolicy/authenticationMethodConfigurations/hardwareOath

    No corpo da solicitação, adicione:

    {
  "state": "enabled"
}

Para habilitar tokens OATH de hardware no Centro de administração do Microsoft Entra:

  1. Entre no Centro de administração do Microsoft Entra como pelo menos um Administrador de Política de Autenticação.

  2. Navegue até Entra ID>métodos de autenticação>tokens OATH de hardware (versão prévia).

  3. Selecione Habilitar, escolha quais grupos de usuários incluir na política e selecione Salvar.

    Captura de tela de como habilitar tokens OATH de hardware no Centro de administração do Microsoft Entra.

Recomendamos que você migre para a política de métodos de autenticação para gerenciar tokens OATH de hardware. Se você habilitar tokens OATH na política de MFA herdada, navegue até a política no Centro de administração do Microsoft Entra como administrador de política de autenticação: Entra ID>Autenticação multifator>Configurações adicionais de autenticação multifator baseada em nuvem. Limpe a caixa de seleção Código de verificação do aplicativo móvel ou token de hardware.

Gerenciar tokens OATH de software de terceiros

Tokens OATH de software de terceiros estão habilitados para autenticação por padrão. Um Administrador de Política de Autenticação pode desabilitá-los para impedir que os usuários entrem com uma senha única de um Provedor de Identidade de terceiros.

  1. Entre no Centro de administração do Microsoft Entra como pelo menos um Administrador de Política de Autenticação.
  2. Navegue até Entra ID>métodos de autenticação>tokens OATH de software de terceiros.
  3. Mova o controle deslizante para o controle Habilitar para impedir que os usuários entrem com tokens OATH de software de terceiros.
  4. Clique em Reconhecer e, em seguida, clique em Salvar.

Cenário: o administrador cria, atribui e ativa um token OATH de hardware

Esse cenário aborda como criar, atribuir e ativar um token OATH de hardware como administrador, incluindo as chamadas à API necessárias e as etapas de verificação. Para obter mais informações sobre as permissões necessárias para invocar essas APIs e inspecionar os exemplos de solicitação-resposta, consulte Create hardwareOathTokenAuthenticationMethodDevice.

Observação

Pode haver um atraso de até 20 minutos para a propagação da política. Permita uma hora para que a política seja atualizada antes que os usuários possam entrar com seu token OATH de hardware e vê-lo em suas informações de segurança.

Vamos examinar um exemplo em que um Administrador de Política de Autenticação cria um token e o atribui a um usuário. Você pode permitir a atribuição sem ativação.

Para o corpo do POST neste exemplo, você pode encontrar o serialNumber do seu dispositivo e secretKey é entregue a você.

POST https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices
{ 
"serialNumber": "GALT11420104", 
"manufacturer": "Thales", 
"model": "OTP 110 Token", 
"secretKey": "C2dE3fH4iJ5kL6mN7oP1qR2sT3uV4w", 
"timeIntervalInSeconds": 30, 
"assignTo": {"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"}
}

A resposta inclui a ID do token e a ID do usuário à qual o token é atribuído:

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#directory/authenticationMethodDevices/hardwareOathDevices/$entity",
    "id": "3dee0e53-f50f-43ef-85c0-b44689f2d66d",
    "displayName": null,
    "serialNumber": "GALT11420104",
    "manufacturer": "Thales",
    "model": "OTP 110 Token",
    "secretKey": null,
    "timeIntervalInSeconds": 30,
    "status": "available",
    "lastUsedDateTime": null,
    "hashFunction": "hmacsha1",
    "assignedTo": {
        "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "displayName": "Test User"
    }
}

Veja como o Administrador de política de autenticação pode ativar o token. Substitua o código de verificação no Corpo da solicitação pelo código do token OATH de hardware.

POST https://graph.microsoft.com/beta/users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee/authentication/hardwareOathMethods/3dee0e53-f50f-43ef-85c0-b44689f2d66d/activate

{ 
    "verificationCode" : "903809" 
}

Para validar se o token está ativado, entre nas informações de segurança como o usuário de teste. Se for solicitado que você aprove uma solicitação de entrada do Microsoft Authenticator, selecione Usar um código de verificação.

Você pode usar GET para listar tokens:

GET https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices

Este exemplo cria um único token:

POST https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices

No corpo da solicitação, adicione:

{ 
"serialNumber": "GALT11420104", 
"manufacturer": "Thales", 
"model": "OTP 110 Token", 
"secretKey": "abcdef2234567abcdef2234567", 
"timeIntervalInSeconds": 30, 
"hashFunction": "hmacsha1" 
}

A resposta inclui a ID de token.

#### Response
{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#directory/authenticationMethodDevices/hardwareOathDevices/$entity",
    "id": "3dee0e53-f50f-43ef-85c0-b44689f2d66d",
    "displayName": null,
    "serialNumber": "GALT11420104",
    "manufacturer": "Thales",
    "model": "OTP 110 Token",
    "secretKey": null,
    "timeIntervalInSeconds": 30,
    "status": "available",
    "lastUsedDateTime": null,
    "hashFunction": "hmacsha1",
    "assignedTo": null
}

Os Administradores de política de autenticação ou um usuário final podem cancelar a atribuição de um token:

DELETE https://graph.microsoft.com/beta/users/66aa66aa-bb77-cc88-dd99-00ee00ee00ee/authentication/hardwareoathmethods/6c0272a7-8a5e-490c-bc45-9fe7a42fc4e0

Este exemplo mostra como excluir um token com a ID do token 3dee0e53-f50f-43ef-85c0-b44689f2d66d:

DELETE https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices/3dee0e53-f50f-43ef-85c0-b44689f2d66d

Cenário: o administrador cria e atribui um token OATH de hardware que um usuário ativa

Nesse cenário, um Administrador de política de autenticação cria e atribui um token e, em seguida, um usuário pode ativá-lo na página de Informações de segurança ou usando o Explorador do Microsoft Graph. Ao atribuir um token, você pode compartilhar etapas para que o usuário entre nas informações de segurança para ativar o token. Eles podem escolher Adicionar método de entrada>token de hardware. Eles precisam fornecer o número de série do token de hardware, que normalmente está na parte de trás do dispositivo.

POST https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices
{ 
"serialNumber": "GALT11420104", 
"manufacturer": "Thales", 
"model": "OTP 110 Token", 
"secretKey": "C2dE3fH4iJ5kL6mN7oP1qR2sT3uV4w", 
"timeIntervalInSeconds": 30, 
"assignTo": {"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"}
}

A resposta inclui um valor de ID para cada token. Um Administrador de Autenticação pode atribuir o token a um usuário:

POST https://graph.microsoft.com/beta/users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee/authentication/hardwareOathMethods
{
    "device": 
    {
        "id": "6c0272a7-8a5e-490c-bc45-9fe7a42fc4e0" 
    }
}

Aqui estão as etapas que um usuário pode seguir para ativar automaticamente o token OATH de hardware nas Informações de segurança:

  1. Entre nas informações de segurança.

  2. Selecione Adicionar método de entrada e escolha o token de hardware.

    Captura de tela de como adicionar um novo método de entrada nas informações de segurança.

  3. Depois de selecionar o token de hardware, selecione Adicionar.

    Captura de tela de como adicionar um token OATH de hardware nas informações de segurança.

  4. Verifique na parte de trás do dispositivo o número de série, insira-o e selecione Avançar.

    Captura de tela de como adicionar o número de série de um token OATH de hardware.

  5. Crie um nome amigável para ajudá-lo a escolher esse método para concluir a autenticação multifator e selecione Avançar.

    Captura de tela de como adicionar um nome amigável a um token OATH de hardware.

  6. Forneça o código de verificação aleatório que aparece quando você toca no botão no dispositivo. Para um token que atualiza seu código a cada 30 segundos, você precisa inserir o código e selecionar Avançar dentro de um minuto. Para um token que é atualizado a cada 60 segundos, você tem dois minutos.

    Captura de tela de como adicionar um código de verificação para ativar um token OATH de hardware.

  7. Quando você vir que o token OATH de hardware foi adicionado com êxito, selecione Concluído.

    Captura de tela de um token OATH de hardware depois que ele é adicionado.

  8. O token OATH de hardware aparece na lista de seus métodos de autenticação disponíveis.

    Captura de tela de um token OATH de hardware nas Informações de segurança.

Aqui estão as etapas que os usuários podem seguir para ativar automaticamente o token OATH de hardware usando o Explorador do Graph.

  1. Abra o Explorador do Microsoft Graph, entre e adicione o consentimento para as permissões necessárias.

  2. Certifique-se de ter as permissões necessárias. Para que um usuário possa fazer as operações de API de autoatendimento, o consentimento do administrador é necessário para Directory.Read.All, User.Read.All e User.ReadWrite.All.

  3. Obtenha uma lista de tokens OATH de hardware atribuídos à sua conta, mas que ainda não estão ativados.

    GET https://graph.microsoft.com/beta/me/authentication/hardwareOathMethods

  4. Copie a ID do dispositivo de token e adicione-a ao final da URL seguida de /activate. Você precisa inserir o código de verificação no corpo da solicitação e enviar a chamada POST antes que o código seja alterado.

    POST https://graph.microsoft.com/beta/me/authentication/hardwareOathMethods/b65fd538-b75e-4c88-bd08-682c9ce98eca/activate

    Corpo da solicitação:

    {
   "verificationCode": "988659"
}

Cenário: o administrador cria vários tokens OATH de hardware em massa que os usuários atribuem e ativam por conta própria

Nesse cenário, um Administrador de autenticação cria tokens sem atribuição e os usuários automaticamente atribuem e ativam os tokens. Você pode carregar novos tokens para o locatário em massa. Os usuários podem entrar nas informações de segurança para ativar o token. Eles podem escolher Adicionar método de entrada>token de hardware. Eles precisam fornecer o número de série do token de hardware, que normalmente está na parte de trás do dispositivo.

Para maior garantia de que o token só é ativado por um usuário específico, você pode atribuir o token ao usuário e enviar o dispositivo a ele para autoativação.

PATCH https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices
{
"@context":"#$delta", 
"value": [ 
    { 
        "@contentId": "1", 
        "serialNumber": "GALT11420108", 
        "manufacturer": "Thales", 
        "model": "OTP 110 Token", 
        "secretKey": "abcdef2234567abcdef2234567", 
        "timeIntervalInSeconds": 30, 
        "hashFunction": "hmacsha1" 
        },
    { 
        "@contentId": "2", 
        "serialNumber": "GALT11420112", 
        "manufacturer": "Thales", 
        "model": "OTP 110 Token", 
        "secretKey": "2234567abcdef2234567abcdef", 
        "timeIntervalInSeconds": 30, 
        "hashFunction": "hmacsha1" 
        }
    ]          
}

Solução de problemas de tokens OATH de hardware

Esta seção aborda

O usuário tem dois tokens com o mesmo número de série

Um usuário pode ter duas instâncias do mesmo token OATH de hardware registradas como métodos de autenticação. Isso acontece se o token herdado não for removido de Tokens OATH (versão prévia) no Centro de administração do Microsoft Entra depois de ser carregado usando o Microsoft Graph.

Quando isso acontece, ambas as instâncias do token são listadas como registradas para o usuário:

GET https://graph.microsoft.com/beta/users/{user-upn-or-objectid}/authentication/hardwareOathMethods

Ambas as instâncias do token também estão listadas em tokens OATH (versão prévia) no Centro de administração do Microsoft Entra:

Captura de tela de tokens duplicados no Centro de administração do Microsoft Entra.

Para identificar e remover o token herdado.

  1. Liste todos os tokens OATH de hardware no usuário.

    GET https://graph.microsoft.com/beta/users/{user-upn-or-objectid}/authentication/hardwareOathMethods

    Localize a id de ambos os tokens e copie o serialNumber do token duplicado.

  2. Identifique o token herdado. Apenas um token é retornado na resposta do comando a seguir. Esse token foi criado usando o Microsoft Graph.

    GET https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices?$filter=serialNumber eq '20033752'

  3. Remova a atribuição do token herdado do usuário. Agora que você conhece a ID do novo token, pode identificar a ID do token herdado da lista retornada na etapa 1. Crie a URL usando a ID do token herdado.

    DELETE https://graph.microsoft.com/beta/users/{user-upn-or-objectid}/authentication/hardwareOathMethods/{legacyHardwareOathMethodId}

  4. Exclua o token herdado usando a id do token herdado nessa chamada.

    DELETE https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices/{legacyHardwareOathMethodId}

Conteúdo relacionado

Saiba mais sobre tokens OATH. Saiba como criar um ou mais hardwareOathTokenAuthenticationMethodDevices.