Condividi tramite

Come gestire i token OATH hardware in Microsoft Entra ID (anteprima)

  • Articolo

Questo argomento illustra come gestire i token di oath hardware in Microsoft Entra ID, incluse le API Microsoft Graph che è possibile usare per caricare, attivare e assegnare token OATH hardware.

Abilitare i token OATH hardware nei criteri metodi di autenticazione

È possibile visualizzare e abilitare i token OATH hardware nei criteri dei metodi di autenticazione usando le API Microsoft Graph o l'interfaccia di amministrazione di Microsoft Entra.

  • Per visualizzare lo stato dei criteri dei token OATH hardware usando le API:

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

  • Per abilitare i criteri dei token OATH hardware usando le API.

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

    Nel corpo della richiesta aggiungere:

    {
  "state": "enabled"
}

Per abilitare i token OATH hardware nell'interfaccia di amministrazione di Microsoft Entra:

  1. Accedere all'Interfaccia di amministrazione di Microsoft Entra almeno come Amministratore dei criteri di autenticazione.

  2. Passare a Metodi di autenticazione>>OATH hardware (anteprima).

  3. Selezionare Abilita, scegliere i gruppi di utenti da includere nei criteri e fare clic su Salva.

    Screenshot di come abilitare i token OATH hardware nell'interfaccia di amministrazione di Microsoft Entra.

È consigliabile eseguire la migrazione ai criteri metodi di autenticazione per gestire i token OATH hardware. Se si abilitano i token OATH nei criteri di autenticazione a più fattori legacy, passare al criterio nell'interfaccia di amministrazione di Microsoft Entra come amministratore dei criteri di autenticazione: Protezione>>a più fattori Impostazioni di autenticazione a più fattori Aggiuntive basate sul cloud. Deselezionare la casella di controllo Codice di verifica dall'app per dispositivi mobili o dal token hardware.

Scenario: l'amministratore crea, assegna e attiva un token OATH hardware

Questo scenario illustra come creare, assegnare e attivare un token OATH hardware come amministratore, incluse le chiamate API e i passaggi di verifica necessari.

Nota

La propagazione dei criteri potrebbe richiedere fino a 20 minuti. Attendere un'ora per l'aggiornamento dei criteri prima che gli utenti possano accedere con il token OATH hardware e visualizzarlo nelle informazioni di sicurezza.

Di seguito viene illustrato un esempio in cui un amministratore dei criteri di autenticazione crea un token e lo assegna a un utente. È possibile consentire l'assegnazione senza attivazione.

Per il corpo di POST in questo esempio, è possibile trovare serialNumber dal dispositivo e secretKey viene recapitato all'utente.

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 risposta include l'ID del token e l'ID utente a cui è assegnato il 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"
    }
}

Ecco come l'amministratore dei criteri di autenticazione può attivare il token. Sostituire il codice di verifica nel corpo della richiesta con il codice del token OATH hardware.

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

{ 
    "verificationCode" : "903809" 
}

Per convalidare l'attivazione del token, accedere a Informazioni di sicurezza come utente di test. Se viene richiesto di approvare una richiesta di accesso da Microsoft Authenticator, selezionare Usa un codice di verifica.

È possibile OTTENERE per elencare i token:

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

Questo esempio crea un singolo token:

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

Nel corpo della richiesta aggiungere:

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

La risposta include l'ID 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
}

Gli amministratori dei criteri di autenticazione o un utente finale possono annullare l'assegnazione di un token:

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

Questo esempio illustra come eliminare un token con ID token 3dee0e53-f50f-43ef-85c0-b44689f2d66d:

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

Scenario: un amministratore crea e assegna un token OATH hardware che un utente attiva

In questo scenario, un amministratore dei criteri di autenticazione crea e assegna un token e quindi un utente può attivarlo nella pagina Informazioni di sicurezza o tramite Microsoft Graph Explorer. Quando si assegna un token, è possibile condividere i passaggi per consentire all'utente di accedere alle informazioni di sicurezza per attivare il token. Possono scegliere Add sign-in method>Hardware token (Token hardware). Devono fornire il numero di serie del token hardware, che in genere si trova sul retro 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 risposta include un valore ID per ogni token. Un amministratore di autenticazione può assegnare il token a un utente:

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

Ecco i passaggi che un utente può seguire per attivare automaticamente il token OATH hardware in Informazioni di sicurezza:

  1. Accedere a Informazioni di sicurezza.

  2. Fare clic su Aggiungi metodo di accesso e scegliere Token hardware.

    Screenshot di come aggiungere un nuovo metodo di accesso in Informazioni di sicurezza.

  3. Dopo aver selezionato Token hardware, fare clic su Aggiungi.

    Screenshot di come aggiungere un token OATH hardware in Informazioni di sicurezza.

  4. Controllare la parte posteriore del dispositivo per il numero di serie, immetterlo e fare clic su Avanti.

    Screenshot di come aggiungere il numero di serie di un token OATH hardware.

  5. Creare un nome descrittivo per scegliere questo metodo per completare l'autenticazione a più fattori e fare clic su Avanti.

    Screenshot di come aggiungere un nome descrittivo per un token OATH hardware.

  6. Specificare il codice di verifica casuale visualizzato quando si tocca il pulsante nel dispositivo. Per un token che aggiorna il codice ogni 30 secondi, è necessario immettere il codice e fare clic su Avanti entro un minuto. Per un token che viene aggiornato ogni 60 secondi, sono necessari due minuti.

    Screenshot di come aggiungere un codice di verifica per attivare un token OATH hardware.

  7. Quando viene visualizzato che il token OATH hardware viene aggiunto correttamente, fare clic su Fine.

    Screenshot di un token OATH hardware dopo l'aggiunta.

  8. Il token OATH hardware viene visualizzato nell'elenco dei metodi di autenticazione disponibili.

    Screenshot di un token OATH hardware in Informazioni di sicurezza.

Ecco i passaggi che gli utenti possono seguire per attivare automaticamente il token OATH hardware usando Graph Explorer.

  1. Aprire Microsoft Graph Explorer, accedere e fornire il consenso per le autorizzazioni necessarie.

  2. Assicurarsi di avere le autorizzazioni necessarie. Per consentire a un utente di eseguire le operazioni api self-service, è necessario il consenso amministratore per Directory.Read.All, User.Read.Alle User.ReadWrite.All.

  3. Ottenere un elenco di token OATH hardware assegnati all'account, ma non ancora attivati.

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

  4. Copiare l'ID del dispositivo token e aggiungerlo alla fine dell'URL seguito da /activate. È necessario immettere il codice di verifica nel corpo della richiesta e inviare la chiamata POST prima che il codice venga modificato.

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

    Corpo della richiesta:

    {
   "verificationCode": "988659"
}

Scenario: l'amministratore crea più token OATH hardware in blocco che gli utenti assegnano e attivano automaticamente

In questo scenario, un amministratore di autenticazione crea token senza assegnazione e gli utenti si autoassegnare e attivare i token. È possibile caricare nuovi token nel tenant in blocco. Gli utenti possono accedere a Informazioni di sicurezza per attivare il token. Possono scegliere Add sign-in method>Hardware token (Token hardware). Devono fornire il numero di serie del token hardware, che in genere si trova sul retro del dispositivo.

Per maggiore garanzia che il token sia attivato solo da un utente specifico, è possibile assegnare il token all'utente e inviare il dispositivo a tali token per l'attivazione automatica.

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

Risoluzione dei problemi relativi al token OATH hardware

Questa sezione copre aspetti comuni

L'utente ha due token con lo stesso numero di serie

Un utente potrebbe avere due istanze dello stesso token OATH hardware registrato come metodi di autenticazione. Ciò si verifica se il token legacy non viene rimosso dai token OATH (anteprima) nell'interfaccia di amministrazione di Microsoft Entra dopo il caricamento tramite Microsoft Graph.

In questo caso, entrambe le istanze del token vengono elencate come registrate per l'utente:

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

Entrambe le istanze del token sono elencate anche nei token OATH (anteprima) nell'interfaccia di amministrazione di Microsoft Entra:

Screenshot dei token duplicati nell'interfaccia di amministrazione di Microsoft Entra.

Per identificare e rimuovere il token legacy.

  1. Elencare tutti i token OATH hardware sull'utente.

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

    Trovare l'ID di entrambi i token e copiare il valore serialNumber del token duplicato.

  2. Identificare il token legacy. Nella risposta del comando seguente viene restituito un solo token. Il token è stato creato usando Microsoft Graph.

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

  3. Rimuovere l'assegnazione di token legacy dall'utente. Ora che si conosce l'ID del nuovo token, è possibile identificare l'ID del token legacy dall'elenco restituito nel passaggio 1. Creare l'URL usando l'ID token legacy.

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

  4. Eliminare il token legacy usando l'ID token legacy in questa chiamata.

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

Contenuto correlato

Altre informazioni sui token OATH.