Jak zarządzać sprzętowymi tokenami OATH w usłudze Microsoft Entra ID (wersja zapoznawcza)

Artykuł
01/07/2025

W tym temacie opisano sposób zarządzania tokenami przysięgi sprzętowej w usłudze Microsoft Entra ID, w tym interfejsami API programu Microsoft Graph, których można użyć do przekazywania, aktywowania i przypisywania sprzętowych tokenów OATH.

Włączanie sprzętowych tokenów OATH w zasadach metod uwierzytelniania

Tokeny OATH sprzętu można wyświetlać i włączać w zasadach metod uwierzytelniania przy użyciu interfejsów API programu Microsoft Graph lub centrum administracyjnego firmy Microsoft Entra.

Aby wyświetlić stan zasad sprzętowych tokenów OATH przy użyciu interfejsów API:

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

Aby włączyć zasady sprzętowych tokenów OATH przy użyciu interfejsów API.

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

W treści żądania dodaj:

{
  "state": "enabled"
}

Aby włączyć sprzętowe tokeny OATH w centrum administracyjnym firmy Microsoft Entra:

Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako administrator zasad uwierzytelniania.
Przejdź do obszaru >
Wybierz pozycję Włącz, wybierz grupy użytkowników do uwzględnienia w zasadach, a następnie wybierz pozycję Zapisz.

Zalecamy przeprowadzenie migracji do zasad metod uwierzytelniania w celu zarządzania sprzętowymi tokenami OATH. Jeśli włączysz tokeny OATH w starszych zasadach uwierzytelniania wieloskładnikowego, przejdź do zasad w centrum administracyjnym firmy Microsoft Entra jako administrator zasad uwierzytelniania: Ochrona>uwierzytelniania wieloskładnikowego Dodatkowe ustawienia uwierzytelniania>wieloskładnikowego oparte na chmurze. Wyczyść pole wyboru Dla kodu weryfikacyjnego z aplikacji mobilnej lub tokenu sprzętowego.

Scenariusz: Administrator tworzy, przypisuje i aktywuje sprzętowy token OATH

W tym scenariuszu opisano sposób tworzenia, przypisywania i aktywowania sprzętowego tokenu OATH jako administratora, w tym niezbędnych wywołań interfejsu API i kroków weryfikacji.

Uwaga

Propagacja zasad może potrwać do 20 minut. Zezwalaj na godzinę aktualizacji zasad, zanim użytkownicy będą mogli zalogować się przy użyciu swojego sprzętowego tokenu OATH i zobaczyć je w informacjach zabezpieczających.

Przyjrzyjmy się przykładowi, w którym administrator zasad uwierzytelniania tworzy token i przypisuje go użytkownikowi. Możesz zezwolić na przypisanie bez aktywacji.

W treści wpisu w tym przykładzie można znaleźć numer seryjny z urządzenia, a klucz tajny jest dostarczany.

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

Odpowiedź zawiera identyfikator tokenu i identyfikator użytkownika, do którego przypisano 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"
    }
}

Oto jak administrator zasad uwierzytelniania może aktywować token. Zastąp kod weryfikacyjny w treści żądania kodem ze sprzętowego tokenu OATH.

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

{ 
    "verificationCode" : "903809" 
}

Aby sprawdzić, czy token został aktywowany, zaloguj się do strony Informacje zabezpieczające jako użytkownik testowy. Jeśli zostanie wyświetlony monit o zatwierdzenie żądania logowania z aplikacji Microsoft Authenticator, wybierz pozycję Użyj kodu weryfikacyjnego.

Aby wyświetlić listę tokenów, możesz uzyskać dostęp:

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

W tym przykładzie jest tworzony pojedynczy token:

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

W treści żądania dodaj:

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

Odpowiedź zawiera identyfikator tokenu.

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

Administratorzy zasad uwierzytelniania lub użytkownik końcowy mogą nieprzypisać tokenu:

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

W tym przykładzie pokazano, jak usunąć token o identyfikatorze tokenu 3dee0e53-f50f-43ef-85c0-b44689f2d66d:

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

Scenariusz: Administrator tworzy i przypisuje sprzętowy token OATH aktywowany przez użytkownika

W tym scenariuszu administrator zasad uwierzytelniania tworzy i przypisuje token, a następnie użytkownik może aktywować go na stronie Informacje o zabezpieczeniach lub przy użyciu Eksploratora programu Microsoft Graph. Po przypisaniu tokenu możesz udostępnić użytkownikowi kroki logowania się do informacji zabezpieczających w celu aktywowania tokenu. Mogą wybrać pozycję Dodaj metodę>logowania Token sprzętowy. Muszą podać numer seryjny tokenu sprzętowego, który zazwyczaj znajduje się z tyłu urządzenia.

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

Odpowiedź zawiera wartość identyfikatora dla każdego tokenu. Administrator uwierzytelniania może przypisać token do użytkownika:

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

Poniżej przedstawiono kroki, które użytkownik może wykonać, aby samodzielnie aktywować swój sprzętowy token OATH w informacjach zabezpieczających:

Zaloguj się do informacji zabezpieczających.
Wybierz Dodaj metodę logowania i wybierz Token sprzętowy.
Po wybraniu tokenu sprzętowegowybierz pozycję Dodaj.
Sprawdź z tyłu urządzenia numer seryjny, wprowadź go i wybierz pozycję Dalej.
Utwórz przyjazną nazwę, aby ułatwić wybranie tej metody w celu ukończenia uwierzytelniania wieloskładnikowego, a następnie wybierz pozycję Dalej.
Podaj losowy kod weryfikacyjny wyświetlany po naciśnięciu przycisku na urządzeniu. W przypadku tokenu, który odświeża kod co 30 sekund, musisz wprowadzić kod i wybrać pozycję Dalej w ciągu jednej minuty. W przypadku tokenu odświeżanego co 60 sekund masz dwie minuty.
Po pomyślnym dodaniu sprzętowego tokenu OATH wybierz Gotowe.
Token OATH sprzętu jest wyświetlany na liście dostępnych metod uwierzytelniania.

Poniżej przedstawiono kroki, które użytkownicy mogą wykonać, aby samodzielnie aktywować swój sprzętowy token OATH przy użyciu Eksploratora programu Graph.

Otwórz Eksploratora programu Microsoft Graph, zaloguj się i wyrazić zgodę na wymagane uprawnienia.
Upewnij się, że masz wymagane uprawnienia. Aby użytkownik mógł wykonywać operacje samoobsługowego interfejsu API, wymagana jest zgoda administratora dla Directory.Read.Allelementów , User.Read.Alli User.ReadWrite.All.
Pobierz listę sprzętowych tokenów OATH przypisanych do konta, ale jeszcze nie aktywowanych.
```
GET https://graph.microsoft.com/beta/me/authentication/hardwareOathMethods
```
Skopiuj identyfikator urządzenia tokenu i dodaj go na końcu adresu URL, po którym następuje /activate. Musisz wprowadzić kod weryfikacyjny w treści żądania i przesłać wywołanie POST przed zmianami kodu.
```
POST https://graph.microsoft.com/beta/me/authentication/hardwareOathMethods/b65fd538-b75e-4c88-bd08-682c9ce98eca/activate
```
Treść żądania:
```
{
   "verificationCode": "988659"
}
```

Scenariusz: Administrator tworzy zbiorczo wiele sprzętowych tokenów OATH, które użytkownicy samodzielnie przypisują i aktywują

W tym scenariuszu administrator uwierzytelniania tworzy tokeny bez przypisania, a użytkownicy przypisują i aktywują tokeny. Nowe tokeny można przekazać do dzierżawy zbiorczo. Użytkownicy mogą zalogować się do informacji zabezpieczających , aby aktywować token. Mogą wybrać pozycję Dodaj metodę>logowania Token sprzętowy. Muszą podać numer seryjny tokenu sprzętowego, który zazwyczaj znajduje się z tyłu urządzenia.

Aby zapewnić większą pewność, że token jest aktywowany tylko przez określonego użytkownika, możesz przypisać token do użytkownika i wysłać do niego urządzenie w celu samodzielnej aktywacji.

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

Rozwiązywanie problemów ze sprzętowymi tokenami OATH

W tej sekcji opisano typowe zagadnienia

Użytkownik ma dwa tokeny z tym samym numerem seryjnym

Użytkownik może mieć dwa wystąpienia tego samego sprzętowego tokenu OATH zarejestrowanego jako metody uwierzytelniania. Dzieje się tak, jeśli starszy token nie zostanie usunięty z tokenów OATH (wersja zapoznawcza) w centrum administracyjnym firmy Microsoft Entra po przekazaniu go przy użyciu programu Microsoft Graph.

W takim przypadku oba wystąpienia tokenu są wyświetlane jako zarejestrowane dla użytkownika:

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

Oba wystąpienia tokenu są również wymienione w tokenach OATH (wersja zapoznawcza) w centrum administracyjnym firmy Microsoft Entra:

Zrzut ekranu przedstawiający zduplikowane tokeny w centrum administracyjnym firmy Microsoft.

Aby zidentyfikować i usunąć starszy token.

Wyświetl listę wszystkich sprzętowych tokenów OATH dla użytkownika.
```
GET https://graph.microsoft.com/beta/users/{user-upn-or-objectid}/authentication/hardwareOathMethods
```
Znajdź identyfikator obu tokenów i skopiuj numer seryjny zduplikowanego tokenu.
Zidentyfikuj starszy token. W odpowiedzi następującego polecenia zwracany jest tylko jeden token. Ten token został utworzony przy użyciu programu Microsoft Graph.
```
GET https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices?$filter=serialNumber eq '20033752'
```
Usuń starsze przypisanie tokenu od użytkownika. Teraz, gdy znasz identyfikator nowego tokenu, możesz zidentyfikować identyfikator starszego tokenu z listy zwróconej w kroku 1. Utwórz adres URL przy użyciu starszego identyfikatora tokenu.
```
DELETE https://graph.microsoft.com/beta/users/{user-upn-or-objectid}/authentication/hardwareOathMethods/{legacyHardwareOathMethodId}
```

Usuń starszy token przy użyciu starszego identyfikatora tokenu w tym wywołaniu.

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

Dowiedz się więcej o tokenach OATH.

Udostępnij za pośrednictwem

Jak zarządzać sprzętowymi tokenami OATH w usłudze Microsoft Entra ID (wersja zapoznawcza)

Włączanie sprzętowych tokenów OATH w zasadach metod uwierzytelniania

Scenariusz: Administrator tworzy, przypisuje i aktywuje sprzętowy token OATH

Scenariusz: Administrator tworzy i przypisuje sprzętowy token OATH aktywowany przez użytkownika

Scenariusz: Administrator tworzy zbiorczo wiele sprzętowych tokenów OATH, które użytkownicy samodzielnie przypisują i aktywują

Rozwiązywanie problemów ze sprzętowymi tokenami OATH

Użytkownik ma dwa tokeny z tym samym numerem seryjnym

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Jak zarządzać sprzętowymi tokenami OATH w usłudze Microsoft Entra ID (wersja zapoznawcza)

Włączanie sprzętowych tokenów OATH w zasadach metod uwierzytelniania

Scenariusz: Administrator tworzy, przypisuje i aktywuje sprzętowy token OATH

Scenariusz: Administrator tworzy i przypisuje sprzętowy token OATH aktywowany przez użytkownika

Scenariusz: Administrator tworzy zbiorczo wiele sprzętowych tokenów OATH, które użytkownicy samodzielnie przypisują i aktywują

Rozwiązywanie problemów ze sprzętowymi tokenami OATH

Użytkownik ma dwa tokeny z tym samym numerem seryjnym

Powiązana zawartość

Opinia

Dodatkowe zasoby