Azure Active Directory でセキュリティ保護された API への接続Connect to API secured with Azure Active Directory

SharePoint Framework ソリューションを構築する場合は、カスタム API に接続してデータを取得するか、または基幹業務アプリケーションと通信する必要があります。When building SharePoint Framework solutions, you might need to connect to your custom API to retrieve some data or to communicate with line of business applications. カスタム API を Microsoft Azure Active Directory (Azure AD) でセキュリティ保護することにより、多くのメリットを受けることができ、また、そのセキュリティ保護はさまざまな方法で行うことができます。Securing custom APIs with Microsoft Azure Active Directory (Azure AD) offers you many benefits and can be done in a number of ways. API を構築した後にこれにアクセスするには、いくつかの方法があります。After you have built the API, there are several ways in which you can access it. これらの方法の複雑さはそれぞれ異なっており、いずれも特定の考慮事項があります。These ways vary in complexity and each have their specific considerations.

この記事ではさまざまな方法について検討し、Azure AD でセキュリティ保護された API を構築し、接続するプロセスについて段階的に説明します。This article discusses the different approaches and describes the step-by-step process of building and connecting to an API secured with Azure AD.

重要

Azure AD で保護された API へ接続する場合、GraphHttpClient クラスまたは AadHttpClient を使用することをお勧めします。When connecting to Azure AD-secured APIs, we recommend that you use the GraphHttpClient or AadHttpClient classes. これらは現在、プレビュー段階で、2018 年春に一般リリースされる予定の新機能です。These are new capabilities that are currently in preview and planned to be generally released during spring 2018. 推奨されるモデルの詳細については、「MSGraphClient を使って Microsoft Graph に接続する」を参照してください。For more information about recommended models, see Use the MSGraphClient to connect to Microsoft Graph.

Azure AD による API のセキュリティ保護Secure an API with Azure AD

Office 365 を使用している場合、Azure AD を使用してカスタム API をセキュリティ保護することは、是非検討していただきたいアーキテクチャ オプションです。If you're using Office 365, securing custom APIs using Azure AD is an architectural option that you should definitely consider. 何よりもまず、Office 365 と Azure AD によって既に管理されている、組織の既存の資格情報を使用して、API へのアクセスを保護することができます。First and foremost, it allows you to secure the access to the API using existing organizational credentials that are already managed through Office 365 and Azure AD. アクティブなアカウントを持つユーザーは、Azure AD によりセキュリティ保護された API を利用するアプリケーションとシームレスに作業できます。Users with an active account can seamlessly work with applications that leverage APIs secured with Azure AD. Azure AD 管理者は、Azure AD に登録されているその他のすべてのアプリケーションへのアクセスを管理するのと同じ方法で、API へのアクセスを一元管理できます。Azure AD administrators can centrally manage access to the API, the same way they manage access to all other applications registered with Azure AD.

API 開発者としては、Azure AD を使用して API を保護することにより、ユーザー資格情報の独自セットの管理と、API 用のカスタム セキュリティ レイヤーの実装から解放されます。As the API developer, using Azure AD to secure your API frees you from managing a proprietary set of user credentials and implementing a custom security layer for your API. さらに、Azure AD では、モバイル アプリからクライアント側ソリューションまでのさまざまな種類のアプリケーションから API に接続することができる OAuth プロトコルをサポートしています。Additionally, Azure AD supports the OAuth protocol, which allows you to connect to the API from a range of application types varying from mobile apps to client-side solutions.

カスタム API を構築するときに、Azure AD で API を保護する方法は、大きく分けて 2 つあります。When building custom APIs, there are two main ways in which you can secure your API with Azure AD. Microsoft Azure App Service で API をホストしている場合、App Service の認証オプションを利用できるメリットがあります。If you host the API in Microsoft Azure App Service, you can benefit from the App Service Authentication option. 独自のインフラストラクチャや Docker コンテナーで API をホストするなど、ホストの柔軟性をさらに求める場合は、コードで API をセキュリティ保護する必要があります。If you look for more hosting flexibility for your API, such as hosting it on your own infrastructure or in Docker containers, you need to secure it in code. そのような場合、実装は使用するプログラミング言語とフレームワークによって異なります。In such cases, the implementation depends on your programming language and framework.

この記事では、このオプションを説明するときに C# と、フレームワークとして ASP.NET Web API を使用します。In this article, when discussing this option, you will use C# and the ASP.NET Web API as the framework.

Azure App Service 認証を使用した API のセキュリティ保護Secure the API using Azure App Service Authentication

カスタム API を Azure App Service に配置する場合は、App Service 認証オプションのメリットを使用して、Azure AD で API を保護することができます。When deploying custom APIs to Azure App Service, you can benefit from the App Service Authentication option to secure the API with Azure AD. App Service 認証を使用する最大のメリットは、その単純さです。Azure portal で使用可能な構成の手順を実行することで、ウィザードにより認証の構成を設定することができます。The biggest benefit of using App Service Authentication is its simplicity: by following the configuration steps available in the Azure Portal, you can have the wizard set up the authentication configuration for you. 基本的なセットアップを選択する場合は、現在のサブスクリプションに関連付けられた Azure AD に、ウィザードで新規 Azure AD アプリケーションを作成します。If you choose the basic setup, the wizard creates a new Azure AD application in Azure AD associated with the current subscription. 高度な構成では、API をホストする App Service へのアクセスに、どの Azure AD アプリケーションを使用するかを選択できます。In the advanced configuration, you can choose which Azure AD application should be used to secure the access to the App Service hosting the API.

Azure Portal に表示される App Service 認証の設定

App Service 認証を設定した後、API にアクセスしようとするユーザーは、API をセキュリティ保護するために使用する Azure AD アプリケーションと同じ Azure AD に所属する組織のアカウントでサインインするように求められます。After App Service Authentication has been configured, users trying to access your API are prompted to sign in with their organizational account that belongs to the same Azure AD as the Azure AD application used to secure the API. サインインすると、HttpContext.Current.User プロパティを使用して現在のユーザーに関する情報にアクセスできます。After signing in, you are able to access the information about the current user through the HttpContext.Current.User property. Azure App Service 認証を使用する場合、アプリケーションに必要な追加の構成はありません。When using Azure App Service Authentication, there is no additional configuration required in your application.

Azure App Service 認証は、Azure App Service でのみ使用可能な機能です。Azure App Service Authentication is a feature available only in Azure App Service. この機能は API での認証の実装を大幅に簡素化する一方で、Azure App Service 内部で認証が実行されることになります。While this capability significantly simplifies implementing authentication in your API, it ties it to running inside Azure App Service. 別のクラウド プロバイダーを使用して、または Docker コンテナー内部で API をホストする場合は、まず認証レイヤーを実装する必要があります。If you want to host the API with another cloud provider or inside a Docker container, you need to implement the authentication layer first.

ASP.NET 認証を使用した API のセキュリティ保護Secure the API using ASP.NET authentication

API がホストされる場所やその展開方法に関して最大の柔軟性を求める場合は、ASP.NET の Azure AD 認証サポートの実装を検討する必要があります。If you want to have the maximum flexibility with regards to where your API is hosted and how it is deployed, you should consider implementing the support for Azure AD authentication in ASP.NET. Visual Studio により、この実装プロセスは大幅に簡素化されます。また、認証セットアップ ウィザードを完了した後は、API がユーザーに、組織のアカウントを使用してサインインするよう要求します。Visual Studio simplifies the implementation process significantly, and after completing the authentication setup wizard, your API requires users to sign in by using their organizational account.

Visual Studio の認証セットアップ ウィザード

構成プロセスの間に、Visual Studio は必要なすべての参照と設定を ASP.NET Web API プロジェクトに追加します。これには、API をセキュリティ保護するための新しい Azure AD アプリケーションの登録も含まれています。During the configuration process, Visual Studio adds all the necessary references and settings to your ASP.NET Web API project, including registering a new Azure AD application to secure your API.

Azure AD でセキュリティ保護された API への SharePoint Framework ソリューションからのアクセスAccess an API secured with Azure AD from SharePoint Framework solutions

SharePoint Framework ソリューションは完全にクライアント側のソリューションなので、セキュリティ保護された API への接続に必要な機密情報を安全に格納することができません。SharePoint Framework solutions are fully client-side and as such are incapable of securely storing secrets required to connect to secured APIs. クライアント側ソリューションとの安全な通信を行うために、Azure AD は認証 Cookie や OAuth の暗黙的フローなど、多くのメカニズムをサポートしています。To support secure communication with client-side solutions, Azure AD supports a number of mechanisms such as authentication cookies or the OAuth implicit flow.

ADAL JS を使用した API へのアクセスAccess the API using ADAL JS

クライアント側ソリューションから Azure AD でセキュリティ保護された API と通信するために一般的に使用される方法は、ADAL JS ライブラリの使用です。A commonly used approach for communicating with APIs secured with Azure AD from client-side solutions is using the ADAL JS library. ADAL JS はクライアント側アプリケーションでの Azure AD の実装を簡素化するとともに、特定のリソースのアクセス トークンを取得します。ADAL JS simplifies implementing authentication against Azure AD in client-side applications as well as retrieving access tokens for specific resources. AngularJS を使って構築されたアプリケーションの場合、ADAL JS は必要なアクセス トークンを、発信 Web 要求のヘッダーに自動的に追加する HTTP 要求インターセプターを提供します。For applications built using AngularJS, ADAL JS offers an HTTP request interceptor that automatically adds required access tokens to headers of outgoing web requests. この要求元を使用すると、開発者は、Azure AD でセキュリティ保護された API への Web  要求を変更する必要がなく、代わりに、アプリケーションの構築に集中できます。By using this requestor, developers don't need to modify web requests to APIs secured with Azure AD and can focus on building the application instead.

ADAL JS を使用して Azure AD でセキュリティ保護された API と通信する利点Benefits of using ADAL JS to communicate with APIs secured with Azure AD

ADAL JS を使用する場合、クライアント側のアプリケーションは、現在サインインしているユーザーの ID 情報に対するフル アクセス権限があります。When using ADAL JS, client-side applications have full access to the identity information of the currently signed-in user. これは、アプリケーションでユーザーの名前やプロフィール画像を表示するなどの要求にとって便利です。This is convenient for requirements such as displaying a user name or profile picture in the application. SharePoint でホストされるソリューションを構築する場合、開発者は SharePoint の API を使用して詳細なプロファイル情報を取得できますが、スタンドアロン アプリケーションの場合はこれができません。When building solutions hosted in SharePoint, developers can retrieve extended profile information by using the SharePoint API, but for standalone applications this isn't possible.

Azure AD に対する認証を容易にするだけではなく、ADAL JS は特定のリソースへのアクセス トークンを取得することができます。Besides facilitating authentication against Azure AD, ADAL JS is capable of retrieving access tokens to specific resources. こうしたアクセス トークンを使用して、アプリケーションは Microsoft Graph やその他のカスタム API など、Azure AD でセキュリティ保護された API に安全にアクセスできます。With these access tokens, applications can securely access APIs secured with Azure AD such as Microsoft Graph or other custom APIs. クライアント側アプリケーションが ADAL JS を使用する前に、Azure AD 内のアプリケーションとして登録する必要があります。Before a client-side application can use ADAL JS, it has to be registered as an application in Azure AD. 登録プロセスで、開発者はアプリケーションがホストされる場所の URL やアプリケーションがアクセスする必要があるリソースなどの多くのパラメーターを、自身で、あるいは現在サインインしているユーザーの代わりに指定します。In the registration process, developers specify a number of parameters such as the URL where the application is hosted and the resources to which the application requires access, either by itself or on behalf of the currently signed-in user.

Azure Portal への新しい Azure AD アプリケーションの登録

アプリケーションを初めて使用するときに、ユーザーは必要なアクセス許可を付与するよう要求されます。The first time the application is used, it prompts the user to grant it the necessary permissions. これはよく、同意フローと呼ばれます。This is often referred to as consent flow. これが承認されると、アプリケーションは特定のリソースのアクセス トークンを要求し、それらのリソースと安全に通信できます。After it's approved, the application can then request access tokens for the specific resources and communicate with them securely.

ADAL JS を使用して Azure AD でセキュリティ保護された API と通信する際の考慮事項Considerations when using ADAL JS to communicate with APIs secured with Azure AD

ADAL JS は単一ページのアプリケーションで使用するように設計されています。そのため、既定では、SharePoint Framework ソリューションで使用した場合に正しく機能しません。ただし、パッチを適用すると SharePoint Framework プロジェクトで正常に使用できます。ADAL JS has been designed to be used with single-page applications. As such, by default it doesn't work correctly when used with SharePoint Framework solutions. By applying a patch however, it can be successfully used in SharePoint Framework projects.

ADAL JS と OAuth を使用して、Azure AD でセキュリティ保護された API にアクセスする場合、認証フローは Azure によって実現します。When using ADAL JS and OAuth to access APIs secured with Azure AD, the authentication flow is facilitated by Azure. すべてのエラーは、Azure サインイン ページで処理されます。Any errors are handled by the Azure sign-in page. ユーザーが組織のアカウントでサインインすると、アプリケーションは、有効なアクセス トークンを取得しようとします。After the user has signed-in with her organizational account, the application tries to retrieve a valid access token. この段階で発生するすべてのエラーは、アプリケーションの開発者によって明示的に処理される必要があります。アクセス トークンの取得は対話型ではなく、ユーザーに UI を表示しないで行われるためです。All errors that occur at this stage have to be explicitly handled by the developer of the application because retrieving access tokens is non-interactive and doesn't present any UI to the user.

ADAL JS を使用するクライアント側アプリケーションはどれも、Azure AD のアプリケーションとして登録する必要があります。Every client-side application that wants to use ADAL JS needs to be registered as an Azure AD application. 登録情報の一部として、アプリケーションが存在する URL があります。A part of the registration information is the URL where the application is located. アプリケーションは完全にクライアント側であり、機密情報を安全に格納できないため、URL はアプリケーションと Azure AD 間のセキュリティを確立するための取り決めの一部です。Because the application is fully client-side and is not capable of securely storing a secret, the URL is a part of the contract between the application and Azure AD to establish security. 開発者は特定の Web パーツが使用される URL すべてを前もって知ることはできないため、SharePoint Framework ソリューションにとってこの要件は問題となります。This requirement is problematic for SharePoint Framework solutions because developers cannot simply know upfront all URLs where a particular web part will be used. さらに現時点では、Azure AD は最大 10 の応答 URL を指定できますが、シナリオによってはこれは十分ではない可能性があります。Additionally, at this moment, Azure AD supports specifying up to 10 reply URLs, which might not be sufficient in some scenarios.

クライアント側のアプリケーションが特定のリソースへのアクセス トークンを取得する前に、ユーザーを認証し、アクセス トークンに交換できる ID トークンを取得する必要があります。Before a client-side application can retrieve an access token to a specific resource, it needs to authenticate the user to obtain the ID token which can then be exchanged for an access token. ユーザーが組織のアカウントを使用して既にサインインしている SharePoint で SharePoint Framework ソリューションがホストされている場合でも、SharePoint Framework ソリューションは現在のユーザーの認証情報を利用できません。Even though SharePoint Framework solutions are hosted in SharePoint, where users are already signed in using their organizational accounts, the authentication information for the current user isn't available to SharePoint Framework solutions. 代わりに、それぞれのソリューションがユーザーに対し、明示的にサインインを要求する必要があります。Instead, each solution must explicitly request the user to sign in. これを行うには、ユーザーを Azure サインイン ページにリダイレクトするか、サインイン ページでポップアップ ウィンドウを表示します。This can be done either by redirecting the user to the Azure sign-in page or by showing a pop-up window with the sign-in page. 後者はページ上の多くの要素の 1 つなので、Web パーツの場合にあまり目立ちません。The latter is less intrusive in the case of a web part, which is one of the many elements on a page. ページに複数の SharePoint Framework のクライアント側 Web パーツがある場合、それぞれが自身の状態を個別に管理し、その特定の Web パーツに明示的にサインインするよう、ユーザーに要求します。If there are multiple SharePoint Framework client-side web parts on the page, each of them manages its state separately and requires the user to explicitly sign in to that particular web part.

Azure AD でセキュリティ保護された API と通信に必要なアクセス トークンの取得は、Azure AD エンドポイントへのリダイレクトを処理する非表示の iframe により行われます。Retrieving access tokens required to communicate with APIs secured with Azure AD is facilitated by hidden iframes that handle redirects to Azure AD endpoints. Azure AD のサインイン エンドポイントと SharePoint Online の URL が同じセキュリティ ゾーンにない場合に、OAuth の暗黙的フローでアクセス トークンの取得が失敗することは、Microsoft Internet Explorer の既知の制限です。There is a known limitation in Microsoft Internet Explorer where obtaining access tokens in OAuth implicit flow fails, if the Azure AD sign-in endpoints and the SharePoint Online URL are not in the same security zone. 組織で Internet Explorer を使用している場合は、Azure AD のエンドポイントと SharePoint Online の URL が同じセキュリティ ゾーンで構成されていることを確認してください。If your organization is using Internet Explorer, ensure that the Azure AD endpoint and SharePoint Online URLs are configured in the same security zone. 一貫性を維持するために、グループ ポリシーを使用して、エンドユーザーに対してこれらの設定をプッシュする選択をする組織もあります。To maintain consistency, some organizations choose to push these settings to end-users using group policies.

Azure AD でセキュリティ保護された API には匿名でアクセスできません。APIs secured with Azure AD cannot be accessed anonymously. 代わりに、API を呼び出すアプリケーションにより、有効な資格情報を提示するように要求します。Instead they require a valid credential to be presented by the application calling them. クライアント側アプリケーションで OAuth の暗黙的フローを使用する場合、この資格情報は ADAL JS を使用して取得された、ベアラーのアクセス トークンです。When using the OAuth implicit flow with client-side applications, this credential is the bearer access token obtained using ADAL JS. AngularJS を使用して SharePoint Framework ソリューションを構築した場合、ADAL JS はユーザーが特定のリソースの有効なアクセス トークンを持っていることを自動的に確認し、AngularJS の $http サービスを使用して実行されるすべての送信要求にそれを追加します。If you have built your SharePoint Framework solution using AngularJS, ADAL JS automatically ensures that you have a valid access token for the particular resource, and adds it to all outgoing requests executed by using the AngularJS $http service. 他の JavaScript ライブラリを使用する場合は、有効なアクセス トークンを取得し、さらに必要に応じてそれを更新し、自身で Web 送信要求にそれを添付する必要があります。When using other JavaScript libraries, you have to obtain a valid access token, and if necessary refresh it, and attach it to the outgoing web requests yourself.

ADAL JS を使用して Azure AD でセキュリティ保護された API に接続する別の方法は、カスタム API へのシームレスな認証のために既存の認証 Cookie を活用することです。An alternative approach to using ADAL JS for connecting to APIs secured with Azure AD is leveraging the existing authentication cookie for seamless authentication to the custom API.

しくみHow it works

組織のアカウントで SharePoint Online にサインインすると、ブラウザーに認証 Cookie が設定されます。When you sign in with your organizational account to SharePoint Online, an authentication cookie is set in your browser. この Cookie は SharePoint への要求ごとに送信され、サイトやドキュメントを操作できるようになります。This cookie is sent with every request to SharePoint allowing to work sites and documents. この Cookie を使用して、Azure AD でセキュリティ保護されたカスタム API に接続するには、その API がホストされており、同じく Azure AD で保護されている URL を指す非表示の iframe をページに配置します。To use this cookie, to connect to a custom API secured with Azure AD, you place a hidden iframe on the page pointing to a URL where the API is hosted and which is also secured with Azure AD. ブラウザーがこの URL を読み込もうとすると、匿名アクセスは許可されていないので、Azure AD のサインイン ページにリダイレクトされます。After the browser tries to load this URL, it gets redirected to the Azure AD sign-in page because anonymous access is not allowed. ユーザーは SharePoint にアクセスするために既に組織のアカウントでサインインしているため、認証が自動的に完了し、元の URL に再度リダイレクトされます。Because you are already signed in with your organization account to access SharePoint, the authentication completed automatically, redirecting you back to the original URL. この時点で、ユーザーのブラウザーは、Azure AD でセキュリティ保護されたカスタム API にアクセスするための Azure AD 認証 Cookie を所持することになります。At this point, your browser has the Azure AD authentication cookie for accessing the custom API secured with Azure AD.

ページに iframe を配置した後、onload イベント リスナーを添付します。これは認証フローが完了した後にトリガーされます。このイベント リスナーで、認証が完了しカスタム API を安全に呼び出すことができるようになったことを示すフラグを設定します。カスタム API へのすべての Web 要求は、このフラグが設定されるか、失敗するまで延期される必要があります。After placing the iframe on the page, you attach an onload event listener to it, which is triggered after the authentication flow completed. In this event listener, you set a flag indicating that authentication completed and you can now securely call the custom API. All web requests to your custom APIs should be delayed until this flag is set or they will fail.

// ...

export default class LatestOrdersWebPart extends BaseClientSideWebPart<ILatestOrdersWebPartProps> {
  private remotePartyLoaded: boolean = false;
  private orders: IOrder[];

  public render(): void {
    this.domElement.innerHTML = `
    <div class="${styles.latestOrders}">
      <iframe src="https://contoso.azurewebsites.net/"
          style="display:none;"></iframe>
      <div class="ms-font-xxl">Recent orders</div>
      <div class="loading"></div>
      <table class="data" style="display:none;">
        <thead>
          <tr>
            <th>ID</th>
            <th>Date</th>
            <th>Region</th>
            <th>Rep</th>
            <th>Item</th>
            <th>Units</th>
            <th>Unit cost</th>
            <th>Total</th>
          </tr>
        </thead>
        <tbody>
        </tbody>
      </table>
    </div>`;

    this.context.statusRenderer.displayLoadingIndicator(
      this.domElement.querySelector(".loading"), "orders");

    this.domElement.querySelector("iframe").addEventListener("load", (): void => {
      this.remotePartyLoaded = true;
    });

    this.executeOrDelayUntilRemotePartyLoaded((): void => {
      // retrieve and render data
    });
  }

  private executeOrDelayUntilRemotePartyLoaded(func: Function): void {
    if (this.remotePartyLoaded) {
      func();
    } else {
      setTimeout((): void => { this.executeOrDelayUntilRemotePartyLoaded(func); }, 100);
    }
  }

  // ...
}

Web パーツで AJAX 要求を実行する場合は、ドメインを越えた認証 Cookie を送信するように指定する必要があります。When executing AJAX requests in your web parts, you have to specify that the authentication cookie should be sent cross-domain. これを有効にするには、Web 要求の [資格情報] プロパティを [含める] に設定します。You can enable this by setting the credentials property of the web request to include. この設定をしない場合、要求はブラウザーでブロックされ、API を呼び出すことができません。Without this, the request is blocked in the browser and you are not able to call the API.

// ...

export default class LatestOrdersWebPart extends BaseClientSideWebPart<ILatestOrdersWebPartProps> {
    // ...

    private retrieveAndRenderData(): void {
        this.context.httpClient.get("https://contoso.azurewebsites.net/api/orders",
        HttpClient.configurations.v1, {
          credentials: "include"
        })
        .then((response: HttpClientResponse): Promise<IOrder[]> => {
          // ...
        });
    }

    // ...
}

このメソッドをサポートするためには、カスタム API にもいくつか個別の構成が必要です。To support this method, the custom API requires some specific configurations as well. まず、クロスドメイン呼び出しからの資格情報の受信に対応している必要があります。First, it requires support for receiving credentials from cross-domain calls. これを行うには、Access-Control-Allow-Credentials 応答ヘッダーを true に設定します。This is done by setting the Access-Control-Allow-Credentials response header to true.

重要

Access-Control-Allow-Credentials の使用時には、呼び出し元を 1 つのみ指定できます。When using Access-Control-Allow-Credentials, you are allowed to specify only one origin.

次に、その API を呼び出すことが許可される呼び出し元を指定する必要があります。Next, it needs to specify what origin is allowed to call the API. これは Access-Control-Allow-Origin 応答ヘッダーで設定します。This is configured in the Access-Control-Allow-Origin response header.

これらのヘッダーの正確な構成方法は、API の実装によって異なります。How these headers should be configured exactly depends on the implementation of your API. たとえば Azure 関数を使用して Node.js で API を構築する場合は、これらのヘッダーを応答オブジェクトに設定します。If you use an Azure Function to build the API using Node.js for example, you would set these headers on the response object:

context.res = {
    body: "response",
    headers: {
        "Access-Control-Allow-Credentials" : "true",
        "Access-Control-Allow-Origin" : "https://contoso.sharepoint.com"
    }
};

ASP.NET Web API を使用する場合は、Microsoft.AspNet.WebApi.Cors NuGet パッケージをインストールして config.EnableCors() メソッドを呼び出し、EnableCors 属性を使用してヘッダー値を設定します。When using ASP.NET Web API, you would install the Microsoft.AspNet.WebApi.Cors NuGet package, call the config.EnableCors() method, and use the EnableCors attribute to set the header values:

[EnableCors("origins": "*", "headers": "*", "methods": "*", SupportsCredentials = true)]
public string Get() {
    return "response";
}

SharePoint Online の認証 Cookie を使用して、Azure AD でセキュリティ保護されたカスタム API に接続する最も重要な利点は、この方法ならば各 Web パーツについて Azure AD アプリケーションを登録する必要がないことです。The most important benefit for using the SharePoint Online authentication cookie to connect to custom APIs secured with Azure AD is the fact that in this approach you don't need to register an Azure AD application for every web part. これにより、各 Web パーツが使用されるページの応答 URL を管理する必要から解放され、1 つの Azure AD アプリケーションにつき最大 10 の応答 URL という制限がなくなります。This frees you from having to manage reply URLs of pages where each web part is used and doesn't have the limitation of maximum 10 reply URLs per Azure AD application.

認証フローはシームレスに処理され、完了しなければならないユーザー操作はありません。The authentication flow is handled seamlessly, and there is no user interaction required to complete. 一方、ADAL JS を使用すると、それぞれの Web パーツは異なる Azure AD アプリケーションに基づくため、ユーザーが明示的にサインインする必要があります。In comparison, when using ADAL JS, each web part is based on a different Azure AD application and requires the user to explicitly sign in to it.

機能面から見ると、ADAL JS を使用しても SharePoint Online の認証 Cookie を使用しても、Azure AD でセキュリティ保護された API に接続できます。From the functional point of view, using both ADAL JS and the SharePoint Online authentication cookie allows you to connect to APIs secured with Azure AD. ただし、これらの 2 つの方法には気を付けなければならない、いくつかの重要な違いがあります。There are, however, a few important differences between the two approaches that you should be aware of.

ADAL JS を使用する場合、クライアント側アプリケーションはアクセス トークンを取得する前に、現在のユーザーの ID トークンを取得します。When using ADAL JS, before the client-side application retrieves an access token, it retrieves the identity token for the current user. このトークンには、ユーザー名やパスワードなどの Azure AD から取得した現在のユーザーに関する情報が含まれています。This token contains information about the current user retrieved from Azure AD such as the user name or password. 認証 Cookie を使用する場合、ID トークンはありません。When using the authentication cookie, there is no identity token. SharePoint を使用していれば、現在のユーザーについての同じ情報を SharePoint から取得できるので、これは実際には制限となりません。Because you're working with SharePoint, this isn't really a limitation, since you can retrieve the same information about the current user from SharePoint.

ADAL JS では、Azure AD でセキュリティ保護されたどの API にも接続できます。ADAL JS allows you to connect to any API secured with Azure AD. 認証 Cookie を使用している場合、API はクロスドメイン呼び出しからの資格情報の受信を明示的にサポートする必要があります。When using the authentication cookie, the API must explicitly support receiving credentials from cross-domain calls. API を設計する場合はこの要件を考慮して、こうした API を SharePoint Framework ソリューションで使用できることを確認する必要があります。When designing APIs, you should take this requirement into account to ensure that you are able to use these APIs in SharePoint Framework solutions.

ADAL JS と SharePoint Online 認証 Cookie のどちらを使用しても、Azure AD でセキュリティ保護された API にアクセスできます。With both ADAL JS and the SharePoint Online authentication cookie, you can access APIs secured with Azure AD. しかしすべての API がこの両方の方法の使用をサポートしているわけではありません。But not all APIs support use of both methods. たとえば、Microsoft Graph にアクセスするには、特定の Microsoft Graph アクセス許可を持つ有効な OAuth アクセス トークンを取得する必要があります。For example, to access Microsoft Graph, you need to have a valid OAuth access token with specific Microsoft Graph permissions. このトークンは ADAL JS を使用して取得できますが、SharePoint Online の認証 Cookie では取得できません。You can obtain this token by using ADAL JS but not by using a SharePoint Online authentication cookie.

SharePoint Online の認証 Cookie を使用して、Azure AD でセキュリティ保護された API にアクセスするに場合は、その他の認証情報がアクセス要求と共に送信されことはありません。When using the SharePoint Online authentication cookie to access APIs secured with Azure AD, no additional authorization information is being sent along with the request. つまり、API と関連付けられた Azure AD に有効な組織アカウントを持つすべてのユーザーは、既定でその API にアクセスできることになります。This means, that by default, every user with a valid organizational account in Azure AD associated with the API can access the API. API を構築する際には、すべての API 操作が十分な特権を持つユーザーにより実行されるように、承認に気を付ける必要があります。When building the API, you must take care of authorization to ensure that all API operations are performed by users with sufficient privileges.

カスタム API は SharePoint Online の外でホストされるので、クロスドメイン Web 要求によりアクセスできます。Custom APIs are hosted outside of SharePoint Online and can be accessed by using cross-domain web requests. 既定では、Web ブラウザーはクロスドメイン AJAX 要求を実行するときに資格情報を含めません。By default, web browsers don't include credentials when performing cross-domain AJAX requests. こうしたセキュリティで保護された API に接続するには、クロス ドメインの資格情報送信を、発信する Web 要求ごとに明示的に有効にする必要があります。To connect to these secured APIs, you have to enable sending credentials with cross-domains explicitly for each outgoing web request.

一般的な考慮事項General considerations

ADAL JS も SharePoint Online の認証 Cookie を使用する方法も、Azure AD と通信するために iframe を使用します。Both ADAL JS and the method that uses the SharePoint Online authentication cookie use iframes for communicating with Azure AD. その理由はリダイレクトにあります。リダイレクトは OAuth フローの一部ですが、その後に自動的に AJAX 要求が続くことはできません。The reason for that are the redirects that are a part of the OAuth flow, and which cannot be automatically followed by AJAX requests. Microsoft Internet Explorer はセキュリティ ゾーンを使用して、関連付けられたゾーンに応じてセキュリティ ポリシーを Web サイトに適用します。Microsoft Internet Explorer uses security zones to apply security policies to websites depending on the associated zone. スクリプトが iframe からの情報にアクセスできるようにするには、iframe 内のリソースと iframe をホストしているページが同じセキュリティ ゾーンに存在する必要があります。For the scripts to be able to access information from an iframe, the resource in the iframe and the page hosting the iframe must be located in the same security zone. 適切な構成を行うために、組織はグループ ポリシーを使用して、ユーザーに一貫した設定を配布できます。To ensure correct configuration, organizations can use group policies to distribute the settings consistently to their users.

Azure AD でセキュリティ保護された API の構築Build an API secured with Azure AD

Azure AD を使用して API へのアクセスを保護することは、複雑な作業ではなく、ほんのいくつかの手順しか必要ありません。Securing the access to an API with Azure AD isn't complex and requires just a few steps. 正確な手順は、API の実装によって異なります。The exact process varies depending on the implementation of your API. Azure 関数の使用を選択する場合は、Azure Portal でセキュリティを構成できます。If you choose to use Azure Functions, you are able to configure the security through the Azure Portal. ASP.NET Web API を使用して API を構築し、Azure App Service 以外の場所でホストする場合は、Web API のコードを拡張して認証を API に追加する必要があります。If you built your API by using the ASP.NET Web API and want to host it somewhere else than in Azure App Service, you need to extend the Web API's code to add authentication to it. 以下に、Azure 関数と ASP.NET Web API の両方を使用して、Azure AD でセキュリティ保護された API を構築、構成する方法を、順を追って説明します。Following is a step-by-step description of how you would build and configure an API secured with Azure AD by using both Azure Functions and ASP.NET Web API.

Azure 関数を使用した API の構築Build the API using an Azure Function

Azure 関数を使用して API を構築することには、多くの利点があります。Building APIs using Azure Functions offers you a number of benefits. 何よりもまず、API の開発と導入のプロセスが大幅に簡素化されます。First and foremost, it significantly simplifies the development and deployment process of the API. Azure 関数は豊富な構成オプション セットを提供します。Azure Functions offer a rich set of configuration options. 注意しなければならないの唯一のことは、実際の API コードです。The only thing that you need to take care of is the actual API code. 認証からクロス オリジン リソース共有 (CORS) のサポートや API のドキュメント化に至るまで、その他のすべてのことについて、Azure Portal を使用できます。For everything else, from authentication to supporting Cross-Origin Resource Sharing (CORS) and documenting the API, you can use the Azure Portal.

Azure 関数は Azure App Service でホストされており、基礎となるサービスで使用可能な多くの機能のメリットがあります。Azure Functions are hosted in Azure App Service and benefit from many capabilities available in the underlying service. 関数または管理者キーを使用した API のセキュリティ保護の上で Azure App Service のセキュリティを有効にし、Azure AD または他の利用可能な認証プロバイダーの 1 つを使用して、API を保護することができます。On top of securing the API by using a function or admin key, you can choose to enable Azure App Service security and protect your API by using Azure AD or one of the other available authentication providers. App Service の認証は Azure Portal 経由で構成でき、API コードの変更は必要ありません。App Service Authentication can be configured via the Azure Portal and doesn't require any changes in the API code.

Azure 関数を使用して Azure AD でセキュリティ保護された API を作成し、安全な方法でクロスドメインの配信元から呼び出すことができる方法を次に示します。Following is how you would use Azure Functions to create an API secured with Azure AD and capable of being called from a cross-domain origin in a secured way.

新しい Azure 関数の作成Create a new Azure Function

  1. Azure Portal でリソース グループに移動し、Function App を追加します。In the Azure Portal, go to your Resource Group and add a Function App.

    リソース グループに追加できる利用可能なサービスのリストで強調表示された Function App

  2. Function App がプロビジョニングされたら、新しく作成した Function App を開き、関数ラベルの隣にあるプラス アイコンを選択して新しい関数を追加します。After the Function App has been provisioned, open the newly created Function App and add a new function by selecting the plus icon next to the Functions label.

    [Function App] ブレードで強調表示されている [関数] ラベルの横にあるプラス アイコン

  3. クイック スタート画面で [関数を独自に作成する] セクションまでスクロールし、[カスタム関数] オプションを選択します。On the quick start screen, scroll to the Get started on your own section, and select the Custom function option.

    [新しい関数の追加] 画面で強調表示された [カスタム関数] リンク

  4. テンプレートのリストから HttpTrigger JavaScript を選択します。From the list of templates, select HttpTrigger-JavaScript.

  5. 関数名に「Orders」を入力します。さらに、Azure 関数へのアクセスを保護するのに Azure AD を使用するので、関数の承認のレベルを [匿名] に設定します。For the function name, enter Orders, and set the function authorization level to Anonymous because you will use Azure AD to secure access to the Azure Function. [作成] を選択して、選択内容を確定します。Confirm your selection by selecting Create.

    新しい Azure 関数の構成

API コードの実装Implement API code

  1. 関数のコードを次に示すスニペットで置換します。Replace the function's code with the following snippet:

    module.exports = function (context, req) {
        context.res = {
            body: [
                {
                id: 1,
                orderDate: new Date(2016, 0, 6),
                region: "east",
                rep: "Jones",
                item: "Pencil",
                units: 95,
                unitCost: 1.99,
                total: 189.05
                },
                {
                id: 2,
                orderDate: new Date(2016, 0, 23),
                region: "central",
                rep: "Kivell",
                item: "Binder",
                units: 50,
                unitCost: 19.99,
                total: 999.50
                },
                {
                id: 3,
                orderDate: new Date(2016, 1, 9),
                region: "central",
                rep: "Jardine",
                item: "Pencil",
                units: 36,
                unitCost: 4.99,
                total: 179.64
                },
                {
                id: 4,
                orderDate: new Date(2016, 1, 26),
                region: "central",
                rep: "Gill",
                item: "Pen",
                units: 27,
                unitCost: 19.99,
                total: 539.73
                },
                {
                id: 5,
                orderDate: new Date(2016, 2, 15),
                region: "west",
                rep: "Sorvino",
                item: "Pencil",
                units: 56,
                unitCost: 2.99,
                total: 167.44
                }],
            headers: {
                "Access-Control-Allow-Credentials" : "true",
                "Access-Control-Allow-Origin" : "https://contoso.sharepoint.com"
            }
        };
        context.done();
    };
    
  2. Access-Control-Allow-Origin ヘッダーで指定された URL を、この API を呼び出す SharePoint Online テナントの URL と一致するように変更します。Change the URL specified in the Access-Control-Allow-Origin header to match the URL of your SharePoint Online tenant from which you are calling this API.

  3. [保存] を選択して、変更を関数のコードに保存します。Save the changes to the function's code by selecting Save.

    Azure 関数のコード画面で強調表示された [保存] ボタン

CORS の設定の変更Change CORS settings

Azure 関数は Azure App Service でホストされるので、ユーザーはクロス オリジン リソース共有 (CORS) 設定を Azure Portal 経由で構成できます。Azure Functions are hosted in Azure App Service, which allows you to configure its Cross-Origin Resource Sharing (CORS) settings through the Azure Portal. CORS 設定がポータル経由で構成されるのは便利ではありますが、Access-Control-Allow-Credentials ヘッダーと組み合わせて使用することができません。しかしこのヘッダーは API が別の送信元から送られる認証 Cookie を受け入れるのに必要なのです。While this is convenient, if configured through the portal, it cannot be used in combination with the Access-Control-Allow-Credentials header, which is required by the API to accept authentication cookies coming from another origin. クライアント側認証が正常に機能するには、Azure App Service の CORS 設定をクリアする必要があります。For the client-side authentication to work correctly, CORS settings of the Azure App Service must be cleared.

重要

SharePoint Online Cookieを使用してAPIで認証する場合は、すべてのCORS設定を消去する必要があります。そうしないと、認証プロセスが失敗します。If you're authenticating with the API using the SharePoint Online cookie you have to clear all CORS settings or the authentication process will fail. ただし、OAuthを使用して認証している場合は、Azureポータルを使用して、APIのCORS設定を構成できます。If you're however authenticating using OAuth, you can use the Azure portal, to configure CORS settings for your API.

  1. 使用する Azure 関数を Function App で選択し、[プラットフォーム機能] ブレードに移動します。In the Function App, select your Azure Function, and navigate to the Platform features blade.

    Azure 関数の設定で強調表示されている、[プラットフォーム機能] リンク

  2. [API] セクションで、[CORS] オプションを選択します。In the API section, select the CORS option.

    Azure 関数の [プラットフォーム機能] ブレードで強調表示されている [CORS] オプション

  3. [CORS の設定] ブレードですべてのエントリを削除して、CORS の設定を空にします。On the CORS settings blade, delete all entries so that the CORS configuration is empty.

    CORS の最初のエントリで強調表示されている [削除] オプション

  4. [保存] を選択して削除を確認します。Confirm the deletion by selecting Save.

    CORS の設定ブレードで強調表示されている [保存] ボタン

App Service 認証の有効化Enable App Service Authentication

  1. Function App の設定で、[プラットフォーム機能] ブレードに戻ります。In the Function App settings, go back to the Platform features blade.

  2. [ネットワーク] セクションで、[認証/承認] オプションを選択します。In the Networking section, select the Authentication / Authorization option.

    Function App のプラットフォーム設定ブレードで強調表示されている [認証/承認] オプション

  3. [App Service 認証] の切り替えを [オン] に設定して、App Service 認証を有効にします。Enable App Service Authentication by setting the App Service Authentication toggle to On.

    [App Service 認証] の切り替えを [オン] に設定

  4. API への匿名アクセスを禁止し、Azure AD を使用した認証を強制するには、[要求が認証されない場合に実行するアクション] リストの値を [Azure Active Directory でのログイン] に設定します。To disallow anonymous access to the API and force authentication using Azure AD, set the value of the Action to take when request is not authenticated list to Log in with Azure Active Directory.

    [要求が認証されない場合に実行するアクション] ドロップダウンで選択された [Azure Active Directory でのログイン] オプション

  5. 認証プロバイダーのリストで [Azure Active Directory] を選択し、構成します。In the list of authentication providers, select Azure Active Directory to configure it.

    認証プロバイダーのリストで強調表示された Azure Active Directory

  6. [Active Directory 認証] ブレードで、[管理モード][簡易] に設定し、新しい Azure AD アプリを作成します。On the Active Directory Authentication blade, set the Management mode to Express, and create a new Azure AD app.

    重要

    [簡易] 構成モードを使用する場合、Azure Portal は Function App があるディレクトリから新しい Azure AD アプリケーションを作成します。When using the Express configuration mode, the Azure Portal creates a new Azure AD application from the same directory where the Function App is located. Function App が別のディレクトリの別の Azure サブスクリプションでホストされる場合は、代わりに詳細モードを使用し、API へのアクセスを保護するために使用するディレクトリとアプリケーションの ID を指定する必要があります。If the Function App is hosted in a different Azure subscription with a different directory, you should use the advanced mode instead, and specify the ID of the directory and application that should be used to secure access to the API.

    既存の Azure AD アプリケーションを使用する場合は、1 つのテナントのみから資格情報を受け入れるようにアプリケーションを構成します。When using existing Azure AD applications, configure the application to accept credentials from a single tenant only. マルチ テナントとしてアプリケーションを構成すると、組織または個人の有効なアカウントを持つどのユーザーも API に接続できます。Configuring the application as multi-tenant allows any user with a valid organization or personal account to connect to your API.

    Azure AD アプリケーションを使用して、認証のための API 専用アカウントへのアクセスをセキュリティ保護します。Using an Azure AD application to secure the access to your API only accounts for authentication. API を構築するときには、API のコードでも要求を承認し、十分な特権を持つユーザーのみが API を使用するようにする必要があります。When building your API, you should also authorize requests in your API's code to ensure that only users with sufficient privileges are using the API.

  7. このアプリは Azure 関数へのアクセスを保護するためだけのものなので、追加のアクセス許可は必要ありません。Because the app is only meant to secure access to the Azure Function, it doesn't require any additional permissions. [OK] ボタンをクリックして、選択内容を確定します。Confirm the selection by selecting OK.

    Azure Active Directory の認証設定

  8. [Azure Active Directory] ブレードを閉じると、[認証/承認] ブレードに戻ります。[保存] を選択して、認証設定の変更をすべて確定します。When the Azure Active Directory blade closes, back on the Authentication / Authorization blade, select Save to confirm all changes to authentication settings.

    [認証/承認] ブレードで強調表示されている [保存] ボタン

  9. 新しいプライベート ウィンドウで API URL に移動しようとすると、Azure AD アカウントを使用してサインインするように求められます。If you try to navigate to your API URL in a new private window, you should be prompted to sign in by using your Azure AD account.

    Azure AD のサインイン ページ

この時点で、API は認証 Cookie を使用して SharePoint Framework のクライアント側 Web パーツから安全に呼び出される準備ができています。At this point, the API is ready to be called securely from a SharePoint Framework client-side web part by using the authentication cookie.

ASP.NET Web API を使用した API の構築Build the API by using ASP.NET Web API

API を実装するもう 1 つの方法は、ASP.NET Web API を使用するものです。Another way to implement the API is by using the ASP.NET Web API. Azure 関数を使用して API を構築するのと比較すると、ASP.NET Web API はかなり多くの作業が必要です。Compared to using Azure Functions to build the API, the ASP.NET Web API requires significantly more work. 完全なプロジェクトを設定しなければならないだけではなく、API を配置する場所も検討する必要があります。Not only do you have to set up a complete project for it, but you also have to think about where the API will be deployed. その一方で、ASP.NET Web API を使用するとより高い柔軟性が生まれ、ユーザーは別のプラットフォーム上に API を配置できます。たとえば Azure App Service や Docker コンテナー、他のクラウド プロバイダー、さらに独自のインフラストラクチャ上にさえ配置できるのです。On the other hand, using the ASP.NET Web API offers you more flexibility and allows you to deploy the API to different platforms such as Azure App Service, Docker containers, other cloud providers, or even on your infrastructure.

ASP.NET Web API を使用して API を構築し、それを Azure App Service に配置し、Azure App Service 認証を使用して保護する手順を次に示します。Following are steps to build an API using the ASP.NET Web API, deploy it to Azure App Service, and secure it by using Azure App Service Authentication. 後で、この API を拡張して、他のプラットフォームにも配置できるように、自身で認証を実行できるようにします。Later, you will extend the API to perform the authentication by itself so that it can be deployed to other platforms as well.

新しい ASP.NET Web API プロジェクトの作成Create a new ASP.NET Web API project

  1. Visual Studio の [ファイル] メニューで、[新規/プロジェクト] オプションを選択します。In Visual Studio, on the File menu, select the New / Project option.

  2. [新しいプロジェクト] ダイアログ ボックスで Visual C# Web テンプレートを選択し、使用可能なテンプレートのリストから [ASP.NET Web アプリケーション] テンプレートを選択します。In the New Project dialog box, select the Visual C# Web templates, and from the list of available templates, select the ASP.NET Web Application template.

    [新しいプロジェクト] ダイアログで選択した [ASP.NET Web アプリケーション] プロジェクト テンプレート

  3. ASP.NET Web アプリケーション プロジェクトの種類として、[Web API] を選択します。As the type of ASP.NET Web Application project, select Web API.

    作成する ASP.NET Web アプリケーション プロジェクトの種類として選択した [Web API]

  4. Azure App Service 認証を使用して API へのアクセスをセキュリティ保護するので、[認証の変更] ボタンを選択し、次に [認証なし] オプションを選択します。Because you will use Azure App Service Authentication to secure the access to the API, select the Change Authentication button, and then select the No Authentication option.

    新しく作成された ASP.NET Web アプリケーションの認証オプションとして選択された [認証なし] オプション

  5. [OK] を選択して選択内容を確定します。Confirm your choice by selecting OK.

  6. Visual Studio では、Web API を Azure App Service に簡単に展開することができます。Visual Studio allows you to easily deploy your Web API to Azure App Service. この機能のメリットを活用するには、[新しい ASP.NET Web アプリケーション] ダイアログ ボックスの [Microsoft Azure] セクションで、[クラウド内のホスト] チェック ボックスを選択し、リストで [App Service] オプションを選択します。To benefit from this capability, in the New ASP.NET Web Application dialog box, in the Microsoft Azure section, select the Host in the cloud check box, and in the list, select the App Service option.

    Web アプリケーションのホスティング プラットフォームとして選択された App Service

  7. [App Service の作成] ダイアログ ボックスで、作成する Web アプリの名前を指定し、このアプリケーションに使用する Azure サブスクリプションリソース グループ、および App Service プランを選択します。In the Create App Service dialog box, specify the name for the web app to be created, and select the Azure Subscription, Resource Group, and App Service Plan that you want to use for this application.

    App Service 作成の設定ページ

  8. [作成] を選択して選択内容を確定します。Confirm your choice by selecting Create. この時点で、Visual Studio により、Web アプリケーションをホストする新しい Azure Web アプリが作成されます。At this point, Visual Studio creates a new Azure Web App to host your web application.

CORS のサポートの追加Add support for CORS

既定では、ASP.NET Web アプリケーション プロジェクト テンプレートを使用して作成された API は CORS をサポートせず、別のドメインでホストされているクライアント アプリケーションから呼び出すことはできません。By default, APIs created using the ASP.NET Web Application project template don't support CORS and cannot be called by client-applications hosted on different domains.

  1. Web API に CORS のサポートを追加するには、プロジェクトを右クリックし、コンテキスト メニューから [NuGet パッケージの管理] オプションを選択します。To add support for CORS to your Web API, right-click the project, and from the context menu, select the Manage NuGet Packages option.

    Visual Studio のプロジェクトのコンテキスト メニューで強調表示された [NuGet パッケージの管理] オプション

  2. [NuGet パッケージの管理] タブで Microsoft.AspNet.WebApi.Cors という名前のパッケージを検索し、プロジェクトにインストールします。On the Manage NuGet Packages tab, search for a package named Microsoft.AspNet.WebApi.Cors and install it in your project.

    [NuGet パッケージの管理] タブで強調表示された Microsoft.AspNet.WebApi.Cors パッケージ

データ モデルの追加Add data model

プロジェクトで、API によって返されるデータを表すモデルを定義します。In the project, define a model that represents the data returned by the API. [モデル] フォルダーに新しいクラスを追加し、「Order」と名前を付けます。In the Models folder, add a new class and name it Order. 以下のコードを新しく作成したファイルに貼り付けます。Paste the following code into the newly created file:

    using Newtonsoft.Json;
    using Newtonsoft.Json.Converters;
    using System;

    namespace PnP.Aad.Api.Models {
        public class Order {
            [JsonProperty(PropertyName = "id")]
            public int Id { get; set; }
            [JsonProperty(PropertyName = "orderDate")]
            public DateTime OrderDate { get; set; }
            [JsonConverter(typeof(StringEnumConverter))]
            [JsonProperty(PropertyName = "region")]
            public Region Region { get; set; }
            [JsonProperty(PropertyName = "rep")]
            public string Rep { get; set; }
            [JsonProperty(PropertyName = "item")]
            public string Item { get; set; }
            [JsonProperty(PropertyName = "units")]
            public uint Units { get; set; }
            [JsonProperty(PropertyName = "unitCost")]
            public double UnitCost { get; set; }
            [JsonProperty(PropertyName = "total")]
            public double Total { get; set; }
        }

        public enum Region {
            East,
            Central,
            West
        }
    }

Orders API の追加Add Orders API

最新の注文に関する情報を返す API を追加します。Add an API that returns the information about the latest orders. [コントローラー] フォルダーに新しいクラスを作成し、「OrdersController」と名前を付けます。In the Controllers folder, create a new class and name it OrdersController. 以下のコードを新しく作成したファイルに貼り付けます。Paste the following code into the newly created file:

using PnP.Aad.Api.Models;
using System;
using System.Collections.Generic;
using System.Web.Http;

namespace PnP.Aad.Api.Controllers {
    public class OrdersController : ApiController {
        private List<Order> orders = new List<Order> {
            new Order {
                Id = 1,
                OrderDate = new DateTime(2016, 1, 6),
                Region = Region.East,
                Rep = "Jones",
                Item = "Pencil",
                Units = 95,
                UnitCost = 1.99,
                Total = 189.05
            },
            new Order {
                Id = 2,
                OrderDate = new DateTime(2016, 1, 23),
                Region = Region.Central,
                Rep = "Kivell",
                Item = "Binder",
                Units = 50,
                UnitCost = 19.99,
                Total = 999.50
            },
            new Order {
                Id = 3,
                OrderDate = new DateTime(2016, 2, 9),
                Region = Region.Central,
                Rep = "Jardine",
                Item = "Pencil",
                Units = 36,
                UnitCost = 4.99,
                Total = 179.64
            },
            new Order {
                Id = 4,
                OrderDate = new DateTime(2016, 2, 26),
                Region = Region.Central,
                Rep = "Gill",
                Item = "Pen",
                Units = 27,
                UnitCost = 19.99,
                Total = 539.73
            },
            new Order {
                Id = 5,
                OrderDate = new DateTime(2016, 3, 15),
                Region = Region.West,
                Rep = "Sorvino",
                Item = "Pencil",
                Units = 56,
                UnitCost = 2.99,
                Total = 167.44
            }
        };

        public IEnumerable<Order> Get() {
            return orders;
        }
    }
}

CORS のサポートによる API の拡張Extend the API with support for CORS

プロジェクトに CORS のサポートをインストールした場合でも、まだそれはアクティブに使用されていません。Even though you have installed support for CORS in your project, it's not being actively used yet. 別のドメインでホストされているクライアント アプリケーションから、新しく作成した Orders API を呼び出すと、CORS エラーが発生し、要求は失敗します。If you call the newly created Orders API from a client application hosted on another domain, you get a CORS error and the request fails.

  1. API が CORS をサポートするには、EnableCors 属性で修辞する必要があります。For an API to support CORS, it has to be decorated with the EnableCors attribute.

    using PnP.Aad.Api.Models;
    using System;
    using System.Collections.Generic;
    using System.Web.Http;
    using System.Web.Http.Cors;
    
    namespace PnP.Aad.Api.Controllers {
        public class OrdersController : ApiController {
            private List<Order> orders = new List<Order> {
                // ...
            };
    
            [EnableCors("*", "*", "GET", SupportsCredentials = true)]
            public IEnumerable<Order> Get() {
                return orders;
            }
        }
    }
    
  2. .\App_Start\WebApiConfig.cs ファイルを開き、次のコードを貼り付けます。Open the .\App_Start\WebApiConfig.cs file, and paste the following code:

    using System.Web.Http;
    
    namespace PnP.Aad.Api {
        public static class WebApiConfig {
            public static void Register(HttpConfiguration config) {
                // Web API configuration and services
    
                // Web API routes
                config.MapHttpAttributeRoutes();
    
                config.EnableCors();
    
                config.Routes.MapHttpRoute(
                    name: "DefaultApi",
                    routeTemplate: "api/{controller}/{id}",
                    defaults: new { id = RouteParameter.Optional }
                );
            }
        }
    }
    

この時点で API はコードが完成しており、Azure Web App に公開できます。At this point, the API is code complete and can be published to the Azure Web App.

API の Web App への発行Publish the API to Azure Web App

  1. Visual Studio でプロジェクトを右クリックし、コンテキスト メニューから [発行] オプションを選択します。In Visual Studio, right-click the project, and from the context menu, select the Publish option.

    プロジェクトのコンテキスト メニューで強調表示された [発行] オプション

  2. [発行] ダイアログ ボックスですべての情報が正しいことを確認し、[発行] ボタンを選択して発行処理を開始します。In the Publish dialog box, verify that all the information is correct, and select Publish to start the publishing process.

    発行情報を含む [発行] ダイアログ

  3. 発行プロセスが完了したら、http://pnp-aad-api.azurewebsites.net/api/orders のように、Web ブラウザーで API の URL に移動します。After the publishing process completes, navigate in your web browser to the API URL, for example, http://pnp-aad-api.azurewebsites.net/api/orders. この時点では、API はセキュリティ保護されておらず、匿名ユーザーがアクセスできます。At this point, the API is not secured and can be accessed by anonymous users.

    匿名ユーザーの Web ブラウザーに表示される API 応答

Azure App Service を使用した API のセキュリティ保護Secure the API using Azure App Service

  1. Azure AD を使用してAPI をセキュリティで保護するには、Azure Portal に移動し、API をホストしている Web アプリケーションを開きます。To secure the API using Azure AD, go to the Azure Portal and open the Web App hosting your API.

  2. [設定] グループから、[認証/承認] オプションを選択します。From the Settings group, select the Authentication / Authorization option.

    Azure Portal に表示される Azure App Service の 認証/承認ページ

  3. Web App の認証を有効にするには、[App Service 認証] 切り替えを [オン] に設定します。To enable authentication for your Web App, set the App Service Authentication toggle to On.

    WebAPI をホストしている Web App の [App Service 認証] 切り替えが [オン] に設定されている

  4. API への匿名アクセスを拒否するには、[要求が認証されない場合に実行するアクション] リストで、[Azure Active Directory でのログイン] オプションを選択します。To disallow anonymous access to the API, in the Action to take when request is not authenticated listn, select the Log in with Azure Active Directory option.

    Web App 認証の設定の、[要求が認証されない場合に実行するアクション] ドロップダウンで選択された [Azure Active Directory でのログイン] オプション

  5. 認証プロバイダーのリストから [Azure Active Directory] を選択して、Azure Active Directory 認証を構成します。Configure Azure Active Directory authentication from the list of authentication providers by selecting Azure Active Directory.

    認証プロバイダーのリストで強調表示された Azure Active Directory

  6. [Active Directory 認証] ブレードで [管理モード][簡易] に設定し、新しい Azure AD アプリを作成します。On the Active Directory Authentication blade, set the Management mode to Express and create a new Azure AD app.

    重要

    [簡易] 構成モードを使用する場合、Azure Portal は Function App があるディレクトリから新しい Azure AD アプリケーションを作成します。When using the Express configuration mode, the Azure Portal creates a new Azure AD application from the same directory where the Function App is located. Function App が別のディレクトリの別の Azure サブスクリプションでホストされる場合は、代わりに詳細モードを使用し、API へのアクセスを保護するために使用するディレクトリとアプリケーションの ID を指定する必要があります。If the Function App is hosted in a different Azure subscription with a different directory, you should use the advanced mode instead, and specify the ID of the directory and application that should be used to secure access to the API.

    既存の Azure AD アプリケーションを使用する場合は、1 つのテナントのみから資格情報を受け入れるようにアプリケーションを構成します。When using existing Azure AD applications, configure the application to accept credentials from a single tenant only. マルチ テナントとしてアプリケーションを構成すると、組織または個人の有効なアカウントを持つどのユーザーも API に接続できます。Configuring the application as multi-tenant allows any user with a valid organization or personal account to connect to your API.

    Azure AD アプリケーションを使用して、認証のための API 専用アカウントへのアクセスをセキュリティ保護します。Using an Azure AD application to secure the access to your API only accounts for authentication. API を構築するときには、API のコードでも要求を承認し、十分な特権を持つユーザーのみが API を使用するようにする必要があります。When building your API, you should also authorize requests in your API's code to ensure that only users with sufficient privileges are using the API.

  7. このアプリは Azure 関数へのアクセスを保護するためだけのものなので、追加のアクセス許可は必要ありません。Because the app is only meant to secure access to the Azure Function, it doesn't require any additional permissions. [OK] ボタンをクリックして、選択内容を確定します。Confirm the selection by selecting OK.

    Azure Active Directory の認証設定

  8. [Azure Active Directory] ブレードを閉じると、[認証/承認] ブレードに戻ります。[保存] を選択して、認証設定の変更をすべて確定します。When the Azure Active Directory blade closes, back on the Authentication / Authorization blade, select Save to confirm all changes to authentication settings.

    [認証/承認] ブレードで強調表示されている [保存] ボタン

  9. 新しいプライベート ウィンドウで API URL に移動しようとすると、Azure AD アカウントを使用してサインインするように求められます。If you try to navigate to your API URL in a new private window, you should be prompted to sign in by using your Azure AD account.

    Azure AD のサインイン ページ

この時点で、API は認証 Cookie を使用して SharePoint Framework のクライアント側 Web パーツから安全に呼び出される準備ができています。At this point, the API is ready to be called securely from a SharePoint Framework client-side web part by using the authentication cookie.

OpenID を使用した API のセキュリティ保護Secure the API using OpenID

Azure App Service 以外の場所に、ASP.NET Web API プロジェクトを配置し、Azure AD でセキュリティ保護する場合は、App Service の認証に依存することはできません。If you want to deploy your ASP.NET Web API project to other location than Azure App Service and want it to be secured with Azure AD, you can't rely on App Service Authentication. 代わりに Web アプリケーションを拡張して、ユーザーに対し、API を使用する前に認証を要求する必要があります。Instead, you have to extend the web application to require its users to authenticate before they can use the API.

すべてのリソースへの匿名アクセスの無効化Disable anonymous access to all resources
  1. すべてのリソースをセキュリティ保護する必要がある場合は、.\App_Start\FilterConfig.cs ファイルを開き、次のコードを貼り付けます。Assuming you want all resources secured, open the .\App_Start\FilterConfig.cs file, and paste the following code:

    using System.Web.Mvc;
    
    namespace PnP.Aad.Api {
        public class FilterConfig {
            public static void RegisterGlobalFilters(GlobalFilterCollection filters) {
                filters.Add(new HandleErrorAttribute());
                filters.Add(new AuthorizeAttribute());
            }
        }
    }
    
  2. すべての API の認証を要求するには、.\App_Start\WebApiConfig.cs ファイルを開き、次のコードを貼り付けます。To require authentication for all APIs, open the .\App_Start\WebApiConfig.cs file, and paste the following code:

    using System.Web.Http;
    
    namespace PnP.Aad.Api {
        public static class WebApiConfig {
            public static void Register(HttpConfiguration config) {
                // Web API configuration and services
    
                // Web API routes
                config.MapHttpAttributeRoutes();
    
                config.EnableCors();
                config.Filters.Add(new AuthorizeAttribute());
    
                config.Routes.MapHttpRoute(
                    name: "DefaultApi",
                    routeTemplate: "api/{controller}/{id}",
                    defaults: new { id = RouteParameter.Optional }
                );
            }
        }
    }
    
  3. API か Web アプリケーションの他のリソースのいずれかにアクセスを試行すると、401 Unauthorized 応答が返されます。If you try to access either the API or any other resource in your web application, you get a 401 Unauthorized response.

    API へのアクセスを試行したときの Unauthorized 応答

この時点で、Web アプリケーションはリソースへのすべての要求が認証されるよう要求しますが、Azure AD のサインイン フローは開始しません。At this point, the web application requires that all requests to its resources are authenticated, but it doesn't start the Azure AD sign-in flow.

次の手順で Web アプリケーションを拡張し、ユーザーがまだ認証されていない場合は、そのユーザーが Azure AD サインイン ページにリダイレクトされるようにします。In the following steps, you extend the web application so that it redirects users to the Azure AD sign-in page, if they weren't previously authenticated.

Azure AD アプリケーションの登録Register Azure AD application

Azure AD で API をセキュリティ保護するには、Azure AD アプリケーションを登録する必要があります。To secure an API with Azure AD, you need to register an Azure AD application. 登録すると、このアプリケーションは Web アプリケーション プロジェクトで参照されるようになり、API へのアクセスを Azure AD でセキュリティ保護するために OWIN ミドルウェアによって使用されます。This application is then referenced in the web application project and used by the OWIN middleware to secure the access to your API with Azure AD.

  1. 既存の Azure AD アプリケーションをまだ持っていない場合は、[Azure Active Directory] ブレードに移動して、Azure Portal でアプリケーションを作成できます。If you don't have an existing Azure AD application yet, you can create one in the Azure Portal, by navigating to the Azure Active Directory blade.

    重要

    API をセキュリティ保護するために使用される Azure AD アプリケーションは、組織が Office 365 にアクセスするために使用する Azure Active Directory と同じ Azure Active Directory に作成する必要があります。The Azure AD application used to secure the API should be created in the same Azure Active Directory that is used by your organization to access Office 365.

    Azure Portal で開いた [Azure Active Directory] ブレード

  2. [Azure Active Directory] ブレードで、[アプリの登録] ブレードに移動します。On the Azure Active Directory blade, navigate to the App registrations blade.

    [Azure Active Directory] ブレードで強調表示された [アプリの登録] セクション

  3. [アプリの登録] ブレードで、[新しいアプリケーション登録] ボタンを選択して、新しい Azure AD アプリケーションを登録します。On the App registrations blade, select the New application registration button to register a new Azure AD application.

    [アプリの登録] ブレードで強調表示された [新しいアプリケーション登録] ボタン

  4. [作成] ブレードでアプリケーションに関する情報を入力し、[作成] を選択して作成を確認します。On the Create blade, provide the information about your application, and confirm the creation by selecting Create.

    [新しいアプリケーションの登録の作成] ブレードで強調表示された [作成] ボタン

  5. アプリケーションの登録が正常に完了したら、リストでアプリケーションを選択して詳細を表示します。After the application registration is successfully created, select it in the list to view its details.

    Azure Portal に表示されるアプリケーションの登録情報

  6. アプリケーション登録情報からアプリケーション ID をコピーして保存します。これは、Web アプリケーションの Azure AD 認証を構成する際に ID が必要になるためです。From the application registration information, copy the Application ID and store it because you will need it when you configure Azure AD authentication for your web application.

匿名要求の Azure AD サインイン ページへのリダイレクトRedirect anonymous requests to Azure AD sign-in page
  1. Visual Studio でプロジェクトを右クリックし、コンテキスト メニューから [NuGet パッケージの管理] オプションを選択します。In Visual Studio, rightclick the project, and from the context menu, select the Manage NuGet Packages option.

  2. [NuGet パッケージの管理] ウィンドウで、プロジェクトに次のパッケージを追加します。In the Manage NuGet Packages window, add the following packages to your project:

    • Microsoft.Owin.Host.SystemWebMicrosoft.Owin.Host.SystemWeb
    • Microsoft.Owin.Security.CookiesMicrosoft.Owin.Security.Cookies
    • Microsoft.Owin.Security.OpenIdConnectMicrosoft.Owin.Security.OpenIdConnect
  3. プロジェクトのルート ディレクトリで Startup という名前の新しいクラスを追加し、次のコードを貼り付けます。In the root directory of your project, add a new class named Startup, and paste the following code:

    using Owin;
    
    namespace PnP.Aad.Api {
        public partial class Startup
        {
            public void Configuration(IAppBuilder app)
            {
                ConfigureAuth(app);
            }
        }
    }
    
  4. App_Start フォルダーに Startup.Auth という名前の新しいクラスを作成し、次のコードを貼り付けます。In the App_Start folder, create a new class named Startup.Auth, and paste the following code:

    using Microsoft.Owin.Security;
    using Microsoft.Owin.Security.Cookies;
    using Microsoft.Owin.Security.OpenIdConnect;
    using Owin;
    using System.Configuration;
    
    namespace PnP.Aad.Api {
        public partial class Startup {
            // For more information on configuring authentication, please visit http://go.microsoft.com/fwlink/?LinkId=301864
            public void ConfigureAuth(IAppBuilder app) {
                app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);
    
                app.UseCookieAuthentication(new CookieAuthenticationOptions());
    
                app.UseOpenIdConnectAuthentication(
                    new OpenIdConnectAuthenticationOptions {
                        ClientId = ConfigurationManager.AppSettings["ida:ClientId"],
                        Authority = $"https://login.microsoftonline.com/{(ConfigurationManager.AppSettings["ida:Tenant"])}",
                        PostLogoutRedirectUri = ConfigurationManager.AppSettings["ida:PostLogoutRedirectUri"],
                    });
            }
        }
    }
    
  5. Visual Studio で Web.config ファイルを開き、appSettings セクションに次の要素を追加します。In Visual Studio, open the Web.config file, and in the appSettings section, add the following elements:

    <add key="ida:Tenant" value="contoso.onmicrosoft.com" />
    <add key="ida:ClientId" value="eeb40f1f-c5fa-4096-896b-71c77d459e21" />
    <add key="ida:PostLogoutRedirectUri" value="https://localhost:44320/" />
    
    • ida:Tenant キーの値は、この API をセキュリティで保護するために使用する Azure AD アプリが定義されている Azure AD の名前です。The value of the ida:Tenant key is the name of the Azure AD where the Azure AD app used to secure the API is defined.
    • ida:ClientId には API をセキュリティで保護するために使用する Azure AD アプリケーションの ID を指定します。ida:ClientId specifies the ID of the Azure AD application used to secure the API.
    • ida: PostLogoutRedirectUri プロパティで指定される URL は、アプリケーションからサインアウトした後に Azure AD がリダイレクトする場所ですが、今回は使用しません。The URL specified in the ida:PostLogoutRedirectUri property is where Azure AD would redirect to after signing out of your application, which isn't used in this case.

これで構成プロセスは完了します。This concludes the configuration process. Web アプリケーションを開始すると、いずれかのリソースにアクセスする前に、Azure AD アカウントでサインインするように求められます。If you start your web application, before you are able to access any of its resources, you are prompted to sign in with your Azure AD account. 承認されたユーザーだけが特定の API にアクセスできるようにするには、独自のカスタム API で承認を実装する必要があります。To ensure that only authorized users are accessing the particular API, you should implement authorization in your custom APIs. ユーザー名を RequestContext.Principal.Identity プロパティから取得し、使用するセキュリティ マトリックスに照らしてそれを検証します。You can do that by retrieving the user name from the RequestContext.Principal.Identity property, and verifying it against your security matrix.

関連項目See also