Compartir vía


Administración de tokens OATH de hardware en Microsoft Entra ID (versión preliminar)

En este tema se explica cómo administrar tokens de juramento de hardware en Microsoft Entra ID, incluidas las API de Microsoft Graph que puede usar para cargar, activar y asignar tokens OATH de hardware.

Habilitación de tokens OATH de hardware en la directiva de métodos de autenticación

Puede ver y habilitar tokens OATH de hardware en la directiva de métodos de autenticación mediante las API de Microsoft Graph o el Centro de administración de Microsoft Entra.

  • Para ver el estado de la directiva de tokens OATH de hardware mediante las API:

    GET https://graph.microsoft.com/beta/policies/authenticationMethodsPolicy/authenticationMethodConfigurations/hardwareOath
    
  • Para habilitar la directiva de tokens OATH de hardware mediante las API.

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

    En el cuerpo de la solicitud, agregue:

    {
      "state": "enabled"
    }
    

Para habilitar tokens OATH de hardware en el Centro de administración de Microsoft Entra:

  1. Inicie sesión en el Centro de administración de Microsoft Entra como Administrador de directivas de autenticación como mínimo.

  2. Vaya a Protección>Métodos de autenticación>Tokens OATH de hardware (versión preliminar).

  3. Seleccione Habilitar, elija los grupos de usuarios que se van a incluir en la directiva y haga clic en Guardar.

    Recorte de pantalla acerca de cómo habilitar tokens OATH de hardware en el Centro de administración de Microsoft Entra.

Se recomienda migrar a la directiva de métodos de autenticación para administrar tokens OATH de hardware. Si habilita tokens OATH en la directiva MFA heredada, vaya a la directiva en el Centro de administración de Microsoft Entra como administrador de directivas de autenticación: Protección>Multifactor de autenticación> Configuración adicional de autenticación multifactor basada en la nube. Desactive la casilla Código de verificación de la aplicación móvil o del token de hardware.

Escenario: el administrador crea, asigna y activa un token OATH de hardware

En este escenario se explica cómo crear, asignar y activar un token OATH de hardware como administrador, incluidas las llamadas API necesarias y los pasos de comprobación.

Nota:

Puede haber hasta un retraso de 20 minutos para la propagación de la directiva. Espere una hora para que la política se actualice antes de que los usuarios puedan iniciar sesión con su token OATH de hardware y verlo en su Información de seguridad.

Veamos un ejemplo en el que un administrador de directivas de autenticación crea un token y lo asigna a un usuario. Puede permitir la asignación sin activación.

Para el cuerpo de POST en este ejemplo, puede encontrar el valor serialNumber desde el dispositivo secretKey se le entrega.

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"}
}

La respuesta incluye el token identificadory el identificador de usuario al que se asigna el token:

{
    "@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"
    }
}

Este es el modo en que el administrador de directivas de autenticación puede activar el token. Reemplace el código de verificación en el cuerpo de la solicitud por el código del 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 que el token está activado, inicie sesión en Información de seguridad como usuario de prueba. Si se le pide que apruebe una solicitud de inicio de sesión de Microsoft Authenticator, seleccione Usar un código de verificación.

Puede obtener para enumerar los tokens:

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

En este ejemplo se crea un único token:

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

En el cuerpo de la solicitud, agregue:

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

La respuesta incluye el identificador del 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
}

Los administradores de directivas de autenticación o un usuario final pueden anular la asignación de un token:

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

En este ejemplo se muestra cómo eliminar un token con el identificador de token 3dee0e53-f50f-43ef-85c0-b44689f2d66d:

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

Escenario: el administrador crea y asigna un token oath de hardare que un usuario activa

En este escenario, un administrador de directivas de autenticación crea y asigna un token y a continuación, un usuario puede activarlo en su página Información de seguridad o mediante el Explorador de Microsoft Graph. Al asignar un token, puede compartir los pasos para que el usuario inicie sesión en Información de seguridad para activar su token. Pueden elegir Añadir método de inicio de sesión > Ficha de hardware. Deben proporcionar el número de serie del token de hardware, que normalmente se encuentra en la parte posterior del 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"}
}

La respuesta incluye un valor id para cada token. Un administrador de autenticación puede asignar el token a un usuario:

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

Estos son los pasos que un usuario puede seguir para activar automáticamente su token OATH de hardware en Información de seguridad:

  1. Inicie sesión en Información de seguridad.

  2. Haga clic en Agregar método de inicio de sesión y elija Token de hardware.

    Recorte de pantalla acerca de cómo agregar un nuevo método de inicio de sesión en Información de seguridad.

  3. Después de seleccionar Token de hardware, haga clic en Agregar.

    Recorte de pantalla de cómo agregar un token OATH de hardware en información de seguridad.

  4. Compruebe la parte posterior del dispositivo para el número de serie, escríbalo y haga clic en Siguiente.

    Recorte de pantalla de cómo agregar el número de serie de un token OATH de hardware.

  5. Cree un nombre amigable que le ayude a elegir este método para completar la autenticación multifactor y haga clic en Siguiente.

    Recorte de pantalla de cómo agregar un nombre descriptivo para un token OATH de hardware.

  6. Proporcione el código de verificación aleatorio que aparece al pulsar el botón en el dispositivo. Para un token que actualice su código cada 30 segundos, debe escribir el código y hacer clic en Siguiente en un minuto. Para un token que se actualiza cada 60 segundos, tiene dos minutos.

    Recorte de pantalla de cómo agregar un código de verificación para activar un token OATH de hardware.

  7. Cuando vea que el token OATH de hardware se ha agregado correctamente, haga clic en Listo.

    Recorte de pantalla de un token OATH de hardware después de agregarlo.

  8. El token OATH de hardware aparece en la lista de los métodos de autenticación disponibles.

    Recorte de pantalla de un token OATH de hardware en Información de seguridad.

Estos son los pasos que los usuarios pueden seguir para activar automáticamente su token OATH de hardware mediante el Explorador de Graph.

  1. Abra el Explorador de Microsoft Graph, inicie sesión y dé su consentimiento a los permisos necesarios.

  2. Asegúrese de que tiene los permisos necesarios. Para que un usuario pueda realizar las operaciones de API de autoservicio, se requiere el consentimiento del administrador para Directory.Read.All, User.Read.All, y User.ReadWrite.All.

  3. Obtenga una lista de tokens OATH de hardware asignados a su cuenta, pero aún no activados.

    GET https://graph.microsoft.com/beta/me/authentication/hardwareOathMethods
    
  4. Copie el identificador del dispositivo de token y agréguelo al final de la dirección URL seguida de /activate. Debe introducir el código de verificación en el cuerpo de la solicitud y enviar la llamada POST antes de que cambie el código.

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

    Cuerpo de la solicitud:

    {
       "verificationCode": "988659"
    }
    

Escenario: el administrador crea varios tokens OATH de hardware en lote que los usuarios se autoasignan y activan

En este escenario, un Administrador de autenticación crea tokens sin asignación, y los usuarios se autoasignan y activan los tokens. Puede cargar nuevos tokens en el inquilino de forma masiva. Los usuarios pueden iniciar sesión en Información de seguridad para activar su token. Pueden elegir Añadir método de inicio de sesión > Ficha de hardware. Deben proporcionar el número de serie del token de hardware, que normalmente se encuentra en la parte posterior del dispositivo.

Para mayor garantía de que el token solo está activado por un usuario específico, puede asignar el token al usuario y enviar el dispositivo a ellos para la activación automática.

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" 
        }
    ]          
} 

Solución de problemas de token OATH de hardware

En esta sección se tratan los temas comunes.

El usuario tiene dos tokens con el mismo número de serie

Un usuario puede tener dos instancias del mismo token OATH de hardware registrado como métodos de autenticación. Esto sucede si el token heredado no se quita de tokens OATH (versión preliminar) en el Centro de administración de Microsoft Entra después de cargarlo mediante Microsoft Graph.

Cuando esto sucede, ambas instancias del token se muestran como registradas para el usuario:

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

Ambas instancias del token también aparecen en tokens OATH (versión preliminar) en el Centro de administración de Microsoft Entra:

Recorte de pantalla de los tokens duplicados en el Centro de administración de Microsoft Entra.

Para identificar y quitar el token heredado.

  1. Enumere todos los tokens OATH de hardware en el usuario.

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

    Busque el identificador de los tokens y copie e valor serialNumber del token duplicado.

  2. Identifique el token heredado. Solo se devuelve un token en la respuesta del siguiente comando. Ese token se ha creado mediante Microsoft Graph.

    GET https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices?$filter=serialNumber eq '20033752'
    
  3. Quite la asignación de tokens heredada del usuario. Ahora que conoce el identificador del nuevo token, puede identificar el identificador del token heredado de la lista devuelta en el paso 1. Cree la dirección URL mediante el identificador de token heredado.

    DELETE https://graph.microsoft.com/beta/users/{user-upn-or-objectid}/authentication/hardwareOathMethods/{legacyHardwareOathMethodId}
    
  4. Elimine el token heredado mediante el identificador de token heredado en esta llamada.

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

Más información sobre OATH.