Microsoft Graph 認証方法 API の使用を開始する

[アーティクル]
03/26/2023

認証方法は、Azure Active Directory (Azure AD) でユーザーを認証する方法です。 Azure AD の認証方法には、今日の Microsoft Graph で管理可能なパスワードと電話 (SMS や音声通話など) が含まれ、他にも FIDO2 セキュリティキーや Microsoft Authenticator アプリなど、多くの方法があります。認証方法は、プライマリ、セカンドファクター、およびステップアップ認証で使用され、セルフサービスパスワードリセット (SSPR) プロセスでも使用されます。

認証方法の API を使用して、ユーザーの認証方法を管理できます。たとえば、次のようなことが可能です。

ユーザーの電話番号を追加します。ユーザーは、その番号をポリシーで使用できるようになっている場合、その番号をSMSと音声通話の認証に使用できます。
ユーザーに割り当てられた電話番号を更新または削除する
SMS サインイン用の番号を有効または無効にする
ユーザーのパスワードを再設定します

API は、ユーザーの認証方法を管理するための重要なツールです。

このチュートリアルでは、次の方法について学ぶことができます。

適切な役割と権限を使用して Azure AD を認証する
ユーザーの認証方法を確認する
ユーザーの新しい電話番号を追加する
ユーザー情報から電話番号を削除する
ユーザーのパスワードをリセットする

ステップ 1: 適切な役割と権限を使用して Azure AD を認証する

Microsoft Graph を操作するためのお気に入りのツールを使用して、次のいずれかの役割を持つアカウントを使用してサインインします。

グローバル管理者
特権認証管理者
認証管理者

次に、アクセス許可を変更します。このチュートリアルでは UserAuthenticationMethod.ReadWrite.All を使用するため、Graph Explorer またはアプリで有効になっていることを確認してください。

スコープを割り当てて同意すると、API の使用を開始できます。ここの例では、Avery Howard という名前の標準ユーザーを使用します。既存のテストアカウントを使用するか、次の手順に従って新しいアカウントを作成してください。これらの API は実際に存在するので、実際のユーザーにはテストしないでください。

ステップ 2: ユーザーの認証方法を確認する

電話をかけて、ユーザーの認証方法を確認します。 URLを取得してユーザーのプロファイルを表示し、以下のように /authentication/methods を追加します。

要求

GET https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/methods

応答

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('avery.howard%40wingtiptoysonline.com')/authentication/methods",
    "value": [
        {
            "@odata.type": "#microsoft.graph.passwordAuthenticationMethod",
            "id": "28c10230-6103-485e-b985-444c60001490",
            "password": null,
            "creationDateTime": null
        }
    ]
}

ステップ 3: ユーザーの新しい電話番号を追加する

前の手順から、新しいユーザー (Avery) にはパスワードのみが登録されています。 Avery が使用する新しい電話番号を割り当てるには、本文に電話のタイプと番号を指定してPOSTリクエストを送信します。電話番号が追加されていることをシステムに通知するには、URLの末尾を methods から phoneMethods に変更する必要もあります。

要求

POST https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/phoneMethods
Content-Type: application/json

{
    "phoneType": "mobile",
    "phoneNumber": "+1 2065550123"
}

応答

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('avery.howard%40wingtiptoysonline.com')/authentication/phoneMethods/$entity",
    "id": "3179e48a-750b-4051-897c-87b9720928f7",
    "phoneNumber": "+1 2065550123",
    "phoneType": "mobile",
    "smsSignInState": "ready"
}

Avery のオフィス番号を追加するには、同じURLに POST 再度アクセスし、電話のタイプと番号を更新します。

要求

POST https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/phoneMethods
Content-Type: application/json

{
    "phoneType": "office",
    "phoneNumber": "+1 4255550199"
}

応答

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('avery.howard%40wingtiptoysonline.com')/authentication/phoneMethods/$entity",
    "id": "e37fc753-ff3b-4958-9484-eaa9425c82bc",
    "phoneNumber": "+1 4255550199",
    "phoneType": "office",
    "smsSignInState": "notSupported"
}

Avery の電話番号をすべて表示するには、電話の方法の URL に関する GET をもう一度実行してください。

要求

GET https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/phoneMethods

応答

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('avery.howard%40wingtiptoysonline.com')/authentication/phoneMethods",
    "value": [
        {
            "id": "e37fc753-ff3b-4958-9484-eaa9425c82bc",
            "phoneNumber": "+1 4255550199",
            "phoneType": "office",
            "smsSignInState": "notSupported"
        },
        {
            "id": "3179e48a-750b-4051-897c-87b9720928f7",
            "phoneNumber": "+1 2065550123",
            "phoneType": "mobile",
            "smsSignInState": "ready"
        }
    ]
}

両方の数値が正しく表示されることを確認します。

ステップ 4: ユーザー情報から電話番号を削除する

このシナリオでは、Avery が自宅で作業しているため、アカウントからオフィス番号を削除しなければなりません。 "オフィスの電話の URL で DELETE を呼び出す必要があります。これは、オフィスの電話の ID を電話メソッドの URL に追加して作成できます。上記の Avery の電話のリストを見てください。オフィスの電話 ID は "e37f" で始まります。

要求

DELETE https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/phoneMethods/e37fc753-ff3b-4958-9484-eaa9425c82bc

意図したとおりのオフィス電話がないため、応答データはありません。以前に作成されたのと同じ GET である Avery のすべてのメソッドを調べることによって、それがなくなったことを確認できます。

要求

GET https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/methods

応答

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('avery.howard%40wingtiptoysonline.com')/authentication/methods",
    "value": [
        {
            "@odata.type": "#microsoft.graph.phoneAuthenticationMethod",
            "id": "3179e48a-750b-4051-897c-87b9720928f7",
            "phoneNumber": "+1 2065550123",
            "phoneType": "mobile",
            "smsSignInState": "ready"
        },
        {
            "@odata.type": "#microsoft.graph.passwordAuthenticationMethod",
            "id": "28c10230-6103-485e-b985-444c60001490",
            "password": null,
            "creationDateTime": null
        }
    ]
}

予想通り、ユーザーは 1 つの携帯電話と 1 つのパスワードだけを持つようになりました。

ステップ 5: ユーザーのパスワードをリセットする

このシナリオでは、Avery はパスワードを忘れてしまったため、リセットする必要があります。リセットするには、"resetPassword" アクションを指定して、パスワードの URL (Avery の認証方法のリストの "28c1" で始まる ID を参照) に POST を作成します。リクエストの本文に新しいパスワードを入力します。

要求

POST https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/passwordMethods/28c10230-6103-485e-b985-444c60001490/resetPassword
Content-Type: application/json

{
    "newPassword": "29sdjfw#fajsdA_a_3an3223"
}

応答

Location: https://graph.microsoft.com/beta/users/ed178e23-7447-4892-baf8-fc46f8af26ce/authentication/operations/74bfa1a6-c0e0-4957-8c37-f91048f4959e?aadgdc=BY01P&aadgsu=ssprprod-a

テナントのオンプレミスインフラストラクチャの Active Directory にパスワードを同期するのに数分かかる場合があるため、完了したかどうかを確認できるアドレスが用意されています。このアドレスは応答のロケーションのヘッダーにあり、ステータスを確認するには、その URL で GET を実行します。

要求

GET https://graph.microsoft.com/beta/users/ed178e23-7447-4892-baf8-fc46f8af26ce/authentication/operations/74bfa1a6-c0e0-4957-8c37-f91048f4959e?aadgdc=BY01P&aadgsu=ssprprod-a

応答

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('ed178e23-7447-4892-baf8-fc46f8af26ce')/authentication/operations/$entity",
    "id": "74bfa1a6-c0e0-4957-8c37-f91048f4959e",
    "createdDateTime": "2020-05-14T00:23:40Z",
    "lastActionDateTime": "2020-05-14T00:23:41Z",
    "status": "succeeded",
    "statusDetail": "ResetSuccess",
    "resourceLocation": "https://graph.microsoft.com/beta/users/ed178e23-7447-4892-baf8-fc46f8af26ce/authentication/methods/28c10230-6103-485e-b985-444c60001490"
}

成功しました! ユーザーのプロファイル、認証方法、電話番号の追加と削除、パスワードのリセットについて説明しました。これで、独自のユーザーのメソッドを管理する準備が整いました。

API リファレンス

認証方法の API リファレンスをお探しですか?

[Azure AD の認証方法 API の概要] を参照してください

次の手順

Azure AD を使用して Microsoft Graph の認証を実行する。
Azure AD サインインをアプリまたは Web サイトに統合する
Azure AD API の最新情報については、Changelog を参照してください。
Microsoft Graph の使用方法についてのさらに多くのアイデアについては、サンプルを参照してください。