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

Artigo
12/11/2024

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.

Habilitar tokens OATH de hardware na política de métodos de autenticação

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:

Entre no Centro de administração do Microsoft Entra pelo menos como um Administrador de Política de Autenticação.
Navegue até Proteção>Métodos de autenticação>Tokens OATH de hardware (versão prévia).
Selecione Habilitar, escolha quais grupos de usuários incluir na política e clique em Salvar.

Recomendamos migrar 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 autenticação multifator herdada, navegue até a política no Centro de administração do Microsoft Entra como Administrador de política de autenticação: Proteção>Autenticação multifator>Configurações adicionais de autenticação multifator baseadas em nuvem. Limpe a caixa de seleção Código de verificação do aplicativo móvel ou token de hardware.

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.

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 ao qual o token foi 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 foi 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 do 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 hardare 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 em 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:

Entre nas Informações de segurança.
Clique em Adicionar método de entrada e escolha Token de hardware.
Depois de selecionar Token de hardware, clique em Adicionar.
Verifique o número de série na parte de trás do dispositivo, insira-o e clique em Avançar.
Crie um nome amigável para ajudá-lo a escolher esse método para concluir a autenticação multifator e clique em Avançar.
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 clicar em Avançar em um minuto. Para um token que é atualizado a cada 60 segundos, você tem dois minutos.
Quando você vir que o token OATH de hardware foi adicionado com sucesso, clique em Concluído.
O token OATH de hardware aparece na lista de seus métodos de autenticação disponíveis.

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

Abra o Explorador do Microsoft Graph, entre e adicione o consentimento para as permissões necessárias.
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.
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
```
Copie a id do dispositivo do token e adicione-a ao final da URL seguido 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 automaticamente

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 seu 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 token OATH de hardware

Esta seção aborda o comum

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 sã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.

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.
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'
```
Remova a atribuição do token herdado do usuário. Agora que você sabe a id do novo token, poderá 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}
```

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

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

Saiba mais sobre Tokens OATH.

Compartilhar via

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

Habilitar tokens OATH de hardware na política de métodos de autenticação

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

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

Cenário: o administrador cria vários tokens OATH de hardware em massa que os usuários atribuem e ativam automaticamente

Solução de problemas de token OATH de hardware

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

Comentários

Recursos adicionais

Compartilhar via

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

Habilitar tokens OATH de hardware na política de métodos de autenticação

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

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

Cenário: o administrador cria vários tokens OATH de hardware em massa que os usuários atribuem e ativam automaticamente

Solução de problemas de token OATH de hardware

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

Conteúdo relacionado

Comentários

Recursos adicionais