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

2025-07-10

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.

Zarządzanie sprzętowymi tokenami OATH w zasadach metod uwierzytelniania (wersja zapoznawcza)

Tokeny sprzętowe OATH można wyświetlać i włączać w zasadach metod uwierzytelniania za pomocą interfejsów API programu Microsoft Graph lub centrum administracyjnego Microsoft Entra.

Aby wyświetlić stan zasad dotyczących sprzętowych tokenów OATH za pomocą interfejsów API:

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

Aby włączyć politykę sprzętowych tokenów OATH, korzystając z 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 Entra ID>Metody uwierzytelniania>Sprzętowe tokeny OATH (wersja zapoznawcza).
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 MFA, przejdź do zasad w centrum administracyjnym Microsoft Entra jako administrator zasad uwierzytelniania: Entra ID>Uwierzytelnianie wieloskładnikowe>Dodatkowe ustawienia uwierzytelniania wieloskładnikowego oparte na chmurze. Wyczyść pole wyboru kodu weryfikacyjnego z aplikacji mobilnej lub tokenu sprzętowego.

Zarządzanie tokenami OATH oprogramowania innej firmy

Tokeny OATH oprogramowania innych firm są domyślnie włączone do logowania. Administrator zasad uwierzytelniania może je wyłączyć, aby uniemożliwić użytkownikom logowanie się przy użyciu jednorazowego hasła od dostawcy tożsamości innej firmy.

Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako administrator zasad uwierzytelniania.
Przejdź do Entra ID>Metody uwierzytelniania>Tokeny OATH oprogramowania innej firmy.
Przesuń suwak kontrolki Włącz, aby uniemożliwić użytkownikom logowanie się przy użyciu tokenów OATH z oprogramowania firm trzecich.
Kliknij pozycję Potwierdzam, a następnie kliknij przycisk Zapisz.

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. Aby uzyskać więcej informacji na temat uprawnień wymaganych do wywoływania tych interfejsów API i sprawdzania przykładów odpowiedzi na żądanie, zobacz Create hardwareOathTokenAuthenticationMethodDevice.

Uwaga

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

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

Dla treści POST w tym przykładzie można znaleźć numer seryjny z urządzenia, a klucz tajny został dostarczony.

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 pobrać listę tokenów, możesz użyć metody GET:

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

W tym przykładzie administrator zasad uwierzytelniania tworzy 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 globalny 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ć 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"}
}

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 o zabezpieczeniach.
Wybierz pozycję Dodaj metodę logowania i wybierz pozycję Token sprzętowy.
Po wybraniu tokenu sprzętowego wybierz pozycję Dodaj.
Sprawdź z tyłu urządzenia numer seryjny, wprowadź go i wybierz przycisk Dalej.
Utwórz przyjazną nazwę, aby ułatwić wybór tej metody w celu ukończenia uwierzytelniania wieloskładnikowego, a następnie wybierz przycisk 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 pozycję 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 wyraź zgodę na wymagane uprawnienia.
Upewnij się, że masz wymagane uprawnienia. Aby użytkownik mógł wykonywać operacje interfejsu API samoobsługi, wymagana jest zgoda administratora dla Directory.Read.All, User.Read.All i 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 z tokenem i dodaj go na końcu adresu URL, następnie /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 zasad uwierzytelniania tworzy tokeny bez przypisania, a użytkownicy przypisują i aktywują tokeny. Można przesłać nowe tokeny do najemcy zbiorczo. Użytkownicy mogą zalogować się do informacji zabezpieczających , aby aktywować token. Mogą wybrać 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ń stare przypisanie tokenu dla 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, używając starszego tokena id.
```
DELETE https://graph.microsoft.com/beta/users/{user-upn-or-objectid}/authentication/hardwareOathMethods/{legacyHardwareOathMethodId}
```

Usuń starszy token używając id starszego tokenu w tym wywołaniu.

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

Dowiedz się więcej o tokenach OATH. Dowiedz się, jak utworzyć jeden lub więcej sprzętowych urządzeń OathTokenAuthenticationMethod.

Udostępnij za pośrednictwem