エクスポート (0) 印刷
すべて展開

Graph API を使用した Azure AD のクエリ

更新日: 2015年1月

概要

noteメモ
注:このサンプルは有効期限が切れています。テクノロジ、メソッド、またはインターフェイスの命令、あるいはこれらがすべて新しい機能に置き換えられています。類似したアプリケーションを構築する更新済みのサンプルについては、「WebApp-GraphAPI-DotNet」を参照してください。

このサンプル アプリケーションでは、Windows Azure Active Directory (Windows Azure AD) に対して、既存のアプリケーションへの追加や新しいアプリケーションの作成を行う .NET 開発者を対象としています。このチュートリアルは、Windows Azure AD ユーザーに対して Web シングル サインオン ユーザー エクスペリエンスを提供する方法を説明するサンプル アプリを生成する Azure AD を使用してサインオンを Web アプリケーションに追加 に基づいています。このチュートリアルでは、Windows Azure AD Graph API を使って、ディレクトリ データを読み込む方法を説明します。Graph API は、アプリケーションがユーザーの Azure ディレクトリ データにアクセスできる REST ベースの API です。

アプリケーションは、次のようなさまざまなシナリオでディレクトリ データにアクセスする必要があります。

  • ユーザー/グループの選択のユーザー、グループ、および連絡先の一覧の取得

  • テナント、ユーザー、およびグループの詳細情報の読み取り

  • グループ メンバーシップの確認

  • ユーザー、グループ、およびグループ メンバーシップの変更

  • ユーザー パスワードの更新

  • ユーザー アカウントの無効化

noteメモ
マルチテナント アプリケーションが、最近そのアプリケーションに同意した Azure AD テナント用の Graph API にアクセスするためのトークンを取得しようとすると、トークン要求が ACS50012 エラーで失敗する場合があります。この問題を解決するには、数分待ってからやり直してください。または、同意した後、同意を提供したテナント管理者がアプリケーションにログオンしてください。詳細については、「ACS エラー コード」を参照してください。

セクションの概要

このドキュメントは以下のセクションで構成されています。

前提条件

このチュートリアルを完了するには、次の前提条件を満たす必要があります。

ソリューション アーキテクチャ

このチュートリアルの最後に、Azure AD テナントからデータを読み込むように構成されたアプリケーションが入手できます。このアプリケーションは、次のディレクトリ エンティティを読み込むことができます:ユーザー、グループ、連絡先、会社情報、ライセンス、およびロール。アプリケーションに書き込み権限が付与されている場合、エンティティを更新することもできます。

このサンプル アプリケーションでは、Azure AD 社からディレクトリ データを読み込む方法を確認します。高度な追加トピック:

  • 完全なユーザー詳細の取得

  • ユーザーの作成と更新

  • グループ一覧の取得

  • グループ メンバーシップの更新

Graph API の認証とアクセス

シングル サインオン エクスペリエンスは、このアプリケーションを更新した後でも同じ状態が維持されるため、Graph API にアクセスできます。ユーザー認証が正常に実行された後、アプリケーションは Azure AD 認証エンドポイントからのトークンを要求します。トークンの取得が正常に実行されると、アプリは Graph API への呼び出しでトークンを使って、テナントからすべてのユーザーを取得します。アプリケーションはユーザー一覧を表示し、Display NamesUser Principal Names を表示します。

ソリューション アーキテクチャ

Graph API のアプリケーション認証と承認

このチュートリアルでは、OAuth 2.0 Client Credential フローを使って、アプリケーションを認証します。Graph API エンドポイントにアクセスする前に、アプリケーションはまず Azure AD の認証エンドポイントから有効なトークンを取得する必要があります。これは、有効なアプリケーション資格情報 (クライアント ID とシークレット) を提示することで実行されます。資格情報の検証が終了すると、署名されたトークンがアプリケーションに返されます。以降、アプリケーションから Graph API への呼び出しの承認ヘッダーにはトークンが含まれます。Graph API サービスは、受信する要求に対するトークンを検証し、検証にパスした場合、次に承認チェックが発生します。

アプリケーションの承認は Graph API とそのロールベースのアクセス制御 (RBAC) サービスによって検証されます。Graph API への呼び出しは、アプリケーションの権限によって制限されます。認証と承認にパスすると、データがアプリケーションに返されます。

Graph API のアプリケーション認証と承認の構成

アプリケーションの認証と承認の構成は、テナント ディレクトリに保存されている Service Principal オブジェクトを使って、Azure AD に保存されます。Azure AD の場合、アプリケーションは、一意の ID、資格情報、および権限を持つ Service Principal オブジェクトとして表されます。これは、おのおのが一意の ID、資格情報、および権限を持つユーザーを表す、Active Directory の User Principal オブジェクトに似ています。

アプリケーションの Service Principal には、認証に使われる一意の ID とシークレットがあります。承認は、アプリケーションのサービス プリンシパルを、必要な権限を持つロールに追加することで管理します。テナント管理者はアプリケーションのサービス プリンシパルを作成し、Azure AD 管理ポータルのロールに追加できます。テナント管理者はオプションで Windows PowerShell を使って、サービス プリンシパルを管理することもできます。詳細については、「Windows PowerShell を使用した Azure AD の管理」を参照してください。

Azure AD を使用してサインオンを Web アプリケーションに追加 チュートリアルでは、Azure AD 管理ポータルのアプリ権限を構成することで、アプリケーションを承認し、Azure AD ユーザー資格情報を使ってシングル サインオンを使用できるようにしました。これでアプリケーション構成を更新して Expense Reporting アプリケーションを有効にし、Graph API への呼び出しを認証および承認できます。次の手順を実行します。

  • 承認:ディレクトリへの読み書きができるように、アプリケーションの権限を構成します。

  • 認証:アプリケーション キー (アプリケーションのパスワード) を取得します。このキーは、Graph API に対するアプリケーションの認証に使われます。

承認 - アプリケーションに対する読み書き権限を構成

  1. Microsoft Azure 管理ポータル (https://manage.WindowsAzure.com) に移動してサインインし、[Active Directory] をクリックします。(トラブルシューティングのヒント:"Active Directory" 項目が見つからないか、使用できません)

  2. ディレクトリをクリックして選択し、[アプリケーション] をクリックします。シングル サインオンのチュートリアルで作成した Expense Reporting サンプル アプリケーションをクリックします。



    外部アクセス

  3. ページの下部の [アクセスの管理] をクリックします。

  4. [このアプリケーションのディレクトリ アクセスの変更] をクリックします。



    作業内容
  5. [シングル サインオン、ディレクトリ データの読み込み] を選択します。次にチェックマークをクリックして変更を保存します。



    ディレクトリ アクセス

認証 - アプリケーション キーを構成

  1. [Expense Reporting] アプリケーション ページで、[ディレクトリ データを読み書きできるように、アプリケーションを有効にする] を展開します。[キーの作成] セクションで、[キーの構成] を選択します。



    キーの構成

  2. キーを追加するには、[構成] ページの [キー] セクションで、キーの有効期間 (既定では 1 年) を選択し、画面下部の [保存] をクリックします。これにより、アプリケーションのパスワードとなるキー値が生成されます。

    Warning警告
    キー値は、キーの生成後に表示されますが、後から取得することはcannot。したがって、キー値を直ちにコピーして、将来参照できるように安全な場所に保存してください。また、アプリケーションに複数のキーが存在する場合があります。テストと実稼働を 1 つ以上実行する場合などです。



    グラフ キー

この時点で、クライアント ID (アプリケーション ID) とアプリケーション キー (キー値) が存在し、アプリケーション用に読み取り権限が構成されています。

noteメモ
このチュートリアルのサンプル アプリケーションでは、パスワードとしてキー値を使用してアプリケーションを認証します。OAuth 2.0 の用語では Client Credentials Grant フローが grant_type=client_credentials に使われています。

MVC 4 シングル サインオン アプリケーションへの Graph API アクセスの追加

Visual Studio を開いて、以前作成したシングル サインオン チュートリアル プロジェクトの "Expense Reporting" を開きます。次の手順で、シングル サインオン チュートリアル アプリケーションを変更します:

  1. Graph Helper クラス プロジェクトの追加

  2. WCF Datservice 5.3 以上への更新

  3. Web.config ファイルの更新

  4. HomeController の変更

  5. ユーザー用の新しいビューを追加する

  6. 共通する _Layout ビューの更新

シングル サインオン チュートリアル アプリケーションへの Graph Helper クラス オブジェクトの追加

Azure AD Graph API Helper ライブラリ をダウンロードします。Graph Helper クラス オブジェクトには、Graph API の認証と呼び出しを容易にするライブラリとクラスが含まれています。このプロジェクトにはソース コードが含まれていて、このウォークスルーの一部としてインクルードと作成を行う必要があります。

  1. Graph Helper を Expense Reporting プロジェクトに追加するには、[ソリューション 'ExpenseReport'] ソリューションを右クリックして [追加] をクリックし、[既存のプロジェクト] をクリックします。

  2. [既存のプロジェクトを追加] ダイアログから、Graph Helper パスに移動し、Microsoft.WindowsAzure.ActiveDirectory.GraphHelper.csproj プロジェクト ファイルを開きます。

これで Graph Helper プロジェクトが ExpenseReport ソリューションに追加されます。

既存のシングル サインオン アプリケーションの Web.config ファイルの更新

Web.config ファイルの appSettings セクションには、アプリケーション固有の構成情報があります。ClientIdPassword のキー値ペアをアプリケーションの Web.config ファイルに追加します。

  • ClientId: Azure AD 管理ポータル アプリケーション管理ページのクライアント ID と同じです。

  • パスワード:Azure AD 管理ポータル アプリケーション管理ページのアプリケーション キー値と同じです。この値は、以前実行したキーの作成時に記録したものです。この値は再取得できないという点に注意してください。前のキーを忘れたり、紛失したりした場合は、同じアプリケーションで別のキーを作成してください。

<appSettings>
    <add key="ClientId" value="<insert your ClientId here>"/>
    <add key="Password" value="<insert your Application Key here>"/>
    ...

変更実行後、Web.config ファイルを保存します。

プロジェクトのリファレンスの更新

  1. Visual Studio で Expense Reporting プロジェクトの References フォルダーを右クリックし、[参照の追加] をクリックします。

  2. [参照マネージャー] ダイアログで [拡張機能] をクリックし、Microsoft.Data.OData バージョン 5.3.0.0 アセンブリと Microsoft.Data.Services.Client バージョン 5.3.0.0 アセンブリを選択します。



    OData 参照
  3. 同じ [参照マネージャー] ダイアログで左側の [ソリューション] メニューを展開し、Microsoft.WindowsAzure.ActiveDirectory.GraphHelper のチェック ボックスをオンにします。[OK] を押すと、プロジェクトにリファレンスが追加されます。



    グラフ ヘルパー参照の追加

HomeController の更新

Controllers フォルダー内の HomeController.cs ファイルを開きます。次のアセンブリをファイルに追加して、ファイルを保存します。

using System.Configuration;
using System.Security.Claims;
using System.Data.Services.Client;
using Microsoft.WindowsAzure.ActiveDirectory;
using Microsoft.WindowsAzure.ActiveDirectory.GraphHelper;

HomeController.cs ファイルで HomeController クラスを探します。既存の ActionResults は (Index, About, Contact) に存在します。次のように、Users という新しい ActionResult を追加します:

       public ActionResult Users()
       {
            //get the tenantName
            string tenantName = ClaimsPrincipal.Current.FindFirst("http://schemas.microsoft.com/identity/claims/tenantid").Value;



            // retrieve the clientId and password values from the Web.config file
            string clientId = ConfigurationManager.AppSettings["ClientId"];
            string password = ConfigurationManager.AppSettings["Password"];



            // get a token using the helper
            AADJWTToken token = DirectoryDataServiceAuthorizationHelper.GetAuthorizationToken(tenantName, clientId, password);

            // initialize a graphService instance using the token acquired from previous step
            DirectoryDataService graphService = new DirectoryDataService(tenantName, token);

            //  get Users
            //
            var users = graphService.users;
            QueryOperationResponse<User> response;
            response = users.Execute() as QueryOperationResponse<User>;
            List<User> userList = response.ToList();
            ViewBag.userList = userList;


            //  For subsequent Graph Calls, the existing token should be used.
            //  The following checks to see if the existing token is expired or about to expire in 2 mins
            //  if true, then get a new token and refresh the graphService
            //
            int tokenMins = 2;
            if (token.IsExpired || token.WillExpireIn(tokenMins))
            {
                AADJWTToken newToken = DirectoryDataServiceAuthorizationHelper.GetAuthorizationToken(tenantName, clientId, password);
                token = newToken;
                graphService = new DirectoryDataService(tenantName, token);
            }

            //  get tenant information
            //
            var tenant = graphService.tenantDetails;
            QueryOperationResponse<TenantDetail> responseTenantQuery;
            responseTenantQuery = tenant.Execute() as QueryOperationResponse<TenantDetail>;
            List<TenantDetail> tenantInfo = responseTenantQuery.ToList();
            ViewBag.OtherMessage = "User List from tenant: " + tenantInfo[0].displayName;


            return View(userList);
       }

ユーザー用の新しいビューを追加する

Users.cshtml という新しいビューを Views/Home フォルダーの下に作成し、次のコードを追加します:

@model IEnumerable<Microsoft.WindowsAzure.ActiveDirectory.User> 
@{
    ViewBag.Title = "Users";
}

<h1>@ViewBag.Message</h1>
<h2>@ViewBag.OtherMessage</h2>
<table>
    <tr>
        <th>
            DisplayName
        </th>
        <th>
            UPN
        </th>
        <th></th>
    </tr>

@if (User.Identity.IsAuthenticated)
{

  foreach (var user in Model) {
    <tr>
        <td>
         @Html.DisplayFor(modelItem => user.displayName)    
        </td>
        <td>
         @Html.DisplayFor(modelItem => user.userPrincipalName)
        </td>
   </tr>
  }
}
</table>

_Layout.cshtml ビューの更新

Views/Shared フォルダーで _Layout.cshtml ファイルを開きます。ファイルの <header> セクションの <nav> 要素で、新しい一覧項目を追加します:"<li>@Html.ActionLink("Users", "Users", "Home")</li>".次にファイルを保存します。

               <nav>
                        <ul id="menu">
                            <li>@Html.ActionLink("Home", "Index", "Home")</li>
                            <li>@Html.ActionLink("About", "About", "Home")</li>
                            <li>@Html.ActionLink("Contact", "Contact", "Home")</li>
                            <li>@Html.ActionLink("Users", "Users", "Home")</li>
                        </ul>
                    </nav>

アプリケーションを実行する

アプリケーションを実行するには、F5 を押します。プロンプトが表示されたら、Azure AD ディレクトリのユーザー (ディレクトリのドメイン内で組織アカウントを持つユーザー) の資格情報を使ってサインインします。

シングル サインオン エクスペリエンスは以前のチュートリアルと同じで、Azure AD 資格情報を使った認証が必要です。アプリケーションを Web サイトに公開した場合、このチュートリアルからの更新を使って更新する必要があります。ユーザー認証が正常に終了した後、右上のメニューから [ユーザー] タブを選択します。

ユーザーの表示

アプリケーションは、まず Azure AD 認証エンドポイントからトークンを要求することで、Graph API の呼び出しプロセスを開始します。これが正常に実行されると、以降の Graph 呼び出しでトークンを使用し、テナントからすべてのユーザーを取得します。次にアプリケーションはユーザー一覧を表示し、Display NamesUser Principal Names を表示します。

最後に Graph API チュートリアル アプリケーションのコーディングが表示されます。次のセクションでは、より詳細な情報と、追加の読み書き動作が行われる、より高度な Graph API サンプル アプリケーションへのリンクを示します。

高度なトピックのセクション

アプリケーションの実行

シングル サインオンが正常に実行された後、アプリケーションは認証対象のテナント名 (サインオンしたユーザーのテナント ID 要求から取得)、クライアント ID、およびパスワードを使って、Azure AD 承認エンドポイントからトークンを要求します。トークン取得をサポートするメソッドの詳細は、同じ名前のファイル内にある DirectoryDataServiceAuthorizationHelper クラスを参照してください。GetAuthorization メソッドは、有効なテナント名 (テナントが所有する検証済みドメイン)、クライアント ID、およびパスワードを提供することで、Azure AD 認証からの JSON Web Token (JWT) トークンの取得を管理します。

要求に成功すると、Graph API の呼び出しで使われる JWT トークンが返されます。このトークンは、以降の要求の承認ヘッダーに挿入されます。すべてのユーザーを取得する Graph API 呼び出しは、以下のヘッダーを含む HTTP GET 要求です:

Content-Type: application/json; odata=minimalmetadata
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1T….

以降の呼び出しで使用できるように、JWT トークンはアプリケーションでキャッシュすることをお勧めします。サンプル アプリケーションでは、2 回目の Graph API 呼び出しの前に JWT トークンの有効期限切れがチェックされます。トークンの有効期間が切れていた場合、新しいトークンが取得されます。有効期限切れのトークンを使って Graph API が呼び出された場合、次のエラー応答が返され、クライアントは新しいトークンを要求します。

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="contoso.com", error="invalid_token", error_description="Your access token has expired. Please renew it before submitting the request.", 

noteメモ
現在、Azure AD 認証トークンの取得を管理する Azure 認証ライブラリ (AAL) のプレビューが存在します。AAL がリリースされた場合、AAL を使用するサンプル アプリケーションとドキュメントを更新します。AAL プレビューのドキュメントはこちらから参照できます

その他の高度なトピック

読み書きメソッドなど、その他の REST 呼び出しは、こちらからダウンロード可能な別の MVC4 サンプル アプリケーションを参照してください。

このサンプルは、次のようなその他の REST 機能をデモンストレーションします。

  • ユーザー詳細 (サムネール写真など) の取得と設定

  • グループの作成と更新

  • グループ メンバーシップの更新

  • 返された多数のオブジェクトの処理のページング

コミュニティの追加

表示:
© 2015 Microsoft