複数地域機能のサンプル アプリケーションをセットアップするSet up your Multi-Geo sample applications

重要: OneDrive および SharePoint Online 複数地域機能は現在プレビュー段階で、変更される可能性があります。Important: OneDrive and SharePoint Online Multi-Geo is currently in preview and is subject to change.

複数地域テナント用の開発をするときには、セキュリティ モデルを理解しておくことが重要です。幸いにも、複数地域テナントで使用されるモデルは、通常のテナントで使用されるモデルと違いはありません。When developing for a Multi-Geo tenant it's important to understand the security model and luckily the used model for a Multi-Geo tenant does not differ from the model used for a regular tenant. この記事では、サンプル アプリケーションを構成する方法を説明します。This article shows you how to configure the sample applications.

アプリケーションがすべてのユーザーのプロファイルを読み取り、更新できるようになる必要があるMy application needs to be able to read/update profiles for all users

Microsoft Graph API を使用しているI'm using the Microsoft Graph API

複数地域ユーザー プロファイルのエクスペリエンス」の記事で説明したように、ユーザー プロファイル プロパティを読み取り、更新するのに推奨されるモデルは、Graph API を使用するものです。As explained in the Multi-geo User Profile Experience article the preferred model to read/update user profile properties is by using the Graph API. この章では、テナント全体にわたるユーザー プロファイルの読み取りおよび更新を実現するには、どのアクセス許可をアプリケーションに付与するべきかを説明します。This chapter explains which permissions you'll need to grant to your application to realize tenant wide user profile reads and updates. Azure AD で定義されたアプリケーションへ付与可能なアクセス許可の長いリストはありますが、プロファイルを操作するには、アクセス許可を以下のように制限することができます。There a long list of possible permissions that you can grant to an application defined in Azure AD, but for manipulating profiles you can limit permissions to:

アクセス許可Permission Type 説明Description 管理者の許諾が必要Admin consent needed
User.ReadWrite.AllUser.ReadWrite.All アプリケーションのアクセス許可Application permission サインインしているユーザーなしで、アプリで組織内の他のユーザーのプロファイル プロパティ、グループ メンバーシップ、部下、上司の完全なセットを読み書きできるようにします。Allows the app to read and write the full set of profile properties, group membership, reports and managers of other users in your organization, without a signed-in user. また、アプリで非管理ユーザーの作成と削除もできるようにします。Also allows the app to create and delete non-administrative users. ユーザーのパスワードのリセットはできません。Does not allow reset of user passwords. はいYes
Sites.ReadWrite.AllSites.ReadWrite.All アプリケーションのアクセス許可Application permission アプリが、サインインしているユーザーなしで、すべてのサイト コレクション内のドキュメントを読み取り、書き込み、アイテムを一覧表示できるようにします。Allows the app to read/write documents and list items in all site collections without a signed in user. このアクセス許可は、アプリケーションがユーザーの個人用サイトの場所を取得する場合にのみ必要とされます。(例: https://graph.microsoft.com/v1.0/users/UserB@contoso.onmicrosoft.com?$select=mySite)This permission is only needed if the application will be retrieving the user's personal site location (e.g. https://graph.microsoft.com/v1.0/users/UserB@contoso.onmicrosoft.com?$select=mySite) はいYes

Microsoft Graph をベースとする複数地域機能のサンプルは、Microsoft 認証ライブラリ (MSAL) を使用して、v2 エンドポイントで Microsoft Graph に接続します。The Microsoft Graph based Multi-Geo samples are using the Microsoft Authentication Library (MSAL) to connect with the Microsoft Graph on the v2 endpoint. v1 エンドポイントを使用して接続する ADAL に対し、MSAL では、Microsoft アカウント、Azure AD、Azure AD B2C を使用しての Microsoft Graph への接続を許可します。Compared to ADAL which connects using the v1 endpoint, MSAL allows connection to the Microsoft Graph with Microsoft Accounts, Azure AD and Azure AD B2C. 以下の指示は、v2 エンドポイントを使用するようアプリケーションをセットアップするのに役立ちますが、v1 エンドポイントに基づく「古い」手法を使用することもできます。Below instructions will help you setup your application for the v2 endpoint, but you can also use the "older" approach based on the v1 endpoints.

アプリケーションを登録するRegister your application

Microsoft Graph に対してアプリケーションのアクセス許可を使用するには、まずアプリケーションを登録する必要があります。To use application permissions against the Microsoft Graph you first have to register your application. https://apps.dev.microsoft.com で登録します。ログインしたら、[アプリの追加] をクリックし、新規の Converged アプリケーションを追加します。You do this at https://apps.dev.microsoft.com. Once logged in click add a new Converged application, by clicking Add an app

Azure AD でアプリケーションを登録する

アプリケーションの名前を指定し、[アプリケーションの作成] をクリックしてください。Give your application a name and hit Create application.

アプリケーションの構成画面で、以下のように構成します。In the application configuration screen configure the following:

  • パスワードを生成し、アプリケーション ID と併せてそれを書き留めます。Generate a password and make a note of it together with the application id
  • [プラットフォームの追加] をクリックし、ランディング ページを持たないアプリケーションであるプラットフォーム ターゲットとして「ネイティブ アプリケーション」を選択します。Click 'Add Platform' and select "Native application" as the platform target as the application does not have a landing page
  • 必要なアプリケーションのアクセス許可を追加します。Add the necessary Application Permission. このサンプル アプリでは、User.ReadWrite.All および Sites.ReadWrite.All のアプリケーションのアクセス許可を追加しました。In this sample app we have added the User.ReadWrite.All and Sites.ReadWrite.All application permissions.
  • [Live SDK サポート] のチェックを外したことを確認します。Make sure to uncheck 'Live SDK support'
  • 構成が完了したら、変更を保存します。Once configured save your changes.

Azure AD でアプリケーションを構成するパート 1

Azure AD でアプリケーションを構成するパート 2

このサンプルでは、User.ReadWrite.All および Sites.ReadWrite.All のアプリケーションのアクセス許可は、使用する前に、テナントの管理者の許諾を必要とします。In this sample the User.ReadWrite.All and Sites.ReadWrite.All application permissions require admin consent in a tenant before it can be used. 次のような許諾 URL を作成します。Create a consent URL like the following:

https://login.microsoftonline.com/<tenant>/adminconsent?client_id=<clientid>&state=<something>

登録されたアプリのクライアント ID を使用し、自分のテナント contoso.onmicrosoft.com からアプリを許諾する場合、URL は次のようになります。Using the client id from the app registered and consenting to the app from my tenant contoso.onmicrosoft.com, the URL looks like this:

https://login.microsoftonline.com/contoso.onmicrosoft.com/adminconsent?client_id=6e4433ca-7011-4a11-85b6-1195b0114fea&state=12345

作成された URL の場所へ移動し、テナント管理者としてログインし、アプリケーションを許諾します。Browsing to the created URL and log in as a tenant admin, and consent to the application. アプリケーションの名前と、構成したアクセス許可スコープが許諾画面に表示されます。You can see the consent screen show the name of your application as well as the permission scopes you configured.

Azure AD アプリケーションに対するテナントの許諾

CSOM ユーザー プロファイル API を使用しているI'm using the CSOM User Profile API

CSOM API を使用してプロファイル プロパティを操作する場合、作成されたカスタム プロパティに対してのみこの操作を行います。なぜなら、すぐに使用できるプロパティは、Microsoft Graph API の方がより上手く処理できるからです。詳細については、「複数地域ユーザー プロファイルのエクスペリエンス」という記事を参照してください。When using the CSOM API to manipulate profile properties you'll only do this for the custom created properties since out-of-the-box properties are better handled via the Microsoft Graph API...see the Multi-geo User Profile Experience article for more details. アクセス許可の観点からすると、2 つのモードがあります。From a permission point of view there's two modes:

ユーザー資格情報を使用するUsing user credentials

この場合、テナント管理者 URL と SharePoint Online 管理者資格情報を使用して、ClientContext オブジェクトを設定する必要があります。This requires setting up a ClientContext object using the tenant admin url and using SharePoint Online admin credentials. ただ 1 つだけの Azure AD インスタンスがユーザーを保持しているということは、SharePoint Online の管理者は、すべての地理的な場所の管理者でもあるということを意味します。Since there's only one Azure AD instance holding users this also implies that a SharePoint Online admin is admin for all the geo locations.

string tenantAdminSiteForMyGeoLocation = "https://contoso-europe-admin.sharepoint.com";

using (ClientContext cc = new ClientContext(tenantAdminSiteForMyGeoLocation))
{
    SecureString securePassword = GetSecurePassword("password");
    cc.Credentials = new SharePointOnlineCredentials("admin@contoso.onmicrosoft.com", securePassword);

    // user profile logic
}

static SecureString GetSecurePassword(string Password)
{
    SecureString sPassword = new SecureString();
    foreach (char c in Password.ToCharArray()) sPassword.AppendChar(c);
    return sPassword;
}

アプリ専用プリンシパルを使用するUsing an app-only principal

アプリ専用を使用するときには、作成されたアプリ プリンシパルに、http://sharepoint/social/tenant アクセス許可スコープのフル コントロールの権利を与える必要があります。When using app-only you'll need to grant the created app principal full control for the http://sharepoint/social/tenant permission scope. 以下に、appregnew.aspx および appinv.aspx を使用してアプリ プリンシパルを登録し、許諾する方法を示します。Below instructions show you to use appregnew.aspx and appinv.aspx to register an app principal and consent it.

プリンシパルを作成するCreate the principal

テナント内のサイト (例: https://contoso.sharepoint.com)) に移動して、appregnew.aspx ページ (例: https://contoso.sharepoint.com/_layouts/15/appregnew.aspx)) を呼び出します。Navigate to a site in your tenant (e.g. https://contoso.sharepoint.com) and then call the appregnew.aspx page (e.g. https://contoso.sharepoint.com/_layouts/15/appregnew.aspx). このページで、[生成] ボタンをクリックしてクライアント ID とクライアント シークレットを生成し、以下に示されているスクリーン ショットのように、残りの情報を入力します。In this page click on the Generate button to generate a client id and client secret and fill the remaining information like shown in the screen-shot below.

重要

Azure Active Directory (Azure AD) のサービスである Azure アクセス制御 (ACS) は、2018 年 11 月 7 日に廃止されます。Azure Access Control (ACS), a service of Azure Active Directory (Azure AD), will be retired on November 7, 2018. SharePoint アドイン モデルでは、この廃止の影響を受けない https://accounts.accesscontrol.windows.net ホスト名を使用しているため、この廃止による影響はありません。This retirement does not impact SharePoint add-in model which is using https://accounts.accesscontrol.windows.net hostname, which is not impacted by this retirement. 詳細については、「SharePoint アドインに対する Azure アクセス制御の終了の影響」を参照してください。See more details on this from Impact of Azure Access Control retirement for SharePoint add-ins.

ACS アプリ プリンシパルを登録する

重要: 次の手順で必要になるため、取得した情報 (クライアント ID およびクライアント シークレット) を保存します。Important Store the retrieved information (client id and client secret) since you'll need this in the next step!

作成されたプリンシパルにアクセス許可を付与するGrant permissions to the created principal

次の手順では、新しく作成されたプリンシパルにアクセス許可を付与します。Next step is granting permissions to the newly created principal. テナント スコープのアクセス許可を付与しようとしているので、この付与はテナント管理サイトの appinv.aspx ページを介してのみ行えます。Since we're granting tenant scoped permissions this granting can only be done via the appinv.aspx page on the tenant administration site. https://contoso-admin.sharepoint.com/_layouts/15/appinv.aspx を介してこのサイトに到達することができます。You can reach this site via https://contoso-admin.sharepoint.com/_layouts/15/appinv.aspx. ページが読み込まれたら、クライアント ID を追加して、作成されたプリンシパルを検索します。Once the page is loaded add your client id and look up the created principal:

アプリ プリンシパルにアクセス許可を付与する

アクセス許可を付与するために、必要なアクセス許可を記述したアクセス許可 XML を提供する必要があります。In order to grant permissions you'll need to provide the permission XML that describes the needed permissions. UI エクスペリエンス スキャナーは、すべてのサイトにアクセス可能である必要があるため、また、アプリ専用を使用した検索を使用するため、以下のアクセス許可を必要とします。Since the UI experience scanner needs to be able to access all sites + also uses search with app-only it requires below permissions:

<AppPermissionRequests AllowAppOnlyPolicy="true">
  <AppPermissionRequest Scope="http://sharepoint/social/tenant" Right="FullControl" />
</AppPermissionRequests>

[作成] をクリックすると、アクセス許可の許諾ダイアログが表示されます。When you click on Create you'll be presented with a permission consent dialog. [信頼する] を押して、アクセス許可を付与します。Press Trust It to grant the permissions:

アプリ プリンシパルを許諾する

コード内でプリンシパルを使用するUse the principal in your code

プリンシパルが作成され、許諾されたら、プリンシパルの ID およびシークレットを使用してアクセスを要求できます。Once the principal is created and consented you can use the principal's id and secret to request an access. TokenHelper.cs クラスは、アプリケーションの構成ファイルから ID とシークレットを把握します。The TokenHelper.cs class will grab the id and secret from the application's configuration file.

string tenantAdminSiteForMyGeoLocation = "https://contoso-europe-admin.sharepoint.com";

//Get the realm for the URL
string realm = TokenHelper.GetRealmFromTargetUrl(siteUri);

//Get the access token for the URL.  
string accessToken = TokenHelper.GetAppOnlyAccessToken(TokenHelper.SharePointPrincipal, siteUri.Authority, realm).AccessToken;

//Create a client context object based on the retrieved access token
using (ClientContext cc = TokenHelper.GetClientContextWithAccessToken(tenantAdminSiteForMyGeoLocation, accessToken))
{
    // user profile logic
}

サンプルの app.config は、次のようになります。A sample app.config looks like this:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <!-- Use AppRegNew.aspx and AppInv.aspx to register client id with proper secret -->
    <add key="ClientId" value="[Your Client ID]" />
    <add key="ClientSecret" value="[Your Client Secret]" />
  </appSettings>
</configuration>

注意

ソリューションに AppForSharePointOnlineWebToolkit NuGet パッケージを追加することで、TokenHelper.cs クラスをプロジェクトに簡単に挿入することができます。You can easily insert the TokenHelper.cs class in your project by adding the AppForSharePointOnlineWebToolkit nuget package to your solution.

アプリケーションが複数地域の構成を検出できるようになる必要があるMy application needs to be able to be able to discover the Multi-Geo configuration

Microsoft Graph API を使用しているI'm using the Microsoft Graph API

複数地域テナントで地理的な場所を検出する、サポートされている API は、Graph API だけです。The only supported API discover the geo locations in a Multi-Geo tenant is by using the Graph API. この章では、複数地域情報を検出するには、どのアクセス許可をアプリケーションに付与するべきかを説明します。This chapter explains which permissions you'll need to grant to your application to discover Multi-Geo information. Azure AD で定義されたアプリケーションへ付与可能なアクセス許可の長いリストはありますが、複数地域テナントの構成情報を読み込むには、アクセス許可を以下のように制限することができます。There a long list of possible permissions that you can grant to an application defined in Azure AD, but for reading Multi-Geo tenant configuration information you can limit permissions to:

アクセス許可Permission Type 説明Description 管理者の許諾が必要Admin consent needed
Sites.ReadWrite.AllSites.ReadWrite.All アプリケーションのアクセス許可Application permission アプリが、サインインしているユーザーなしで、すべてのサイト コレクション内のドキュメントを読み取り、書き込み、アイテムを一覧表示できるようにします。Allows the app to read/write documents and list items in all site collections without a signed in user. はいYes

「アプリケーションがすべてのユーザーのプロファイルを読み取り、更新できるようになる必要がある」の章で説明された Azure AD アプリケーションの作成手順を使用します。Use the Azure AD application creation steps as described in the "My application needs to be able to read/update profiles for all users" chapter.

アプリケーションがサイト コレクションを作成し、削除し、テナント サイト コレクションのプロパティを設定できるようになる必要があるMy application needs to be able to create/delete sites collections or set tenant site collection properties

Microsoft Graph API を使用しているI'm using the Microsoft Graph API

複数地域サイトは、Microsoft Graph API を使用してグループ サイト (The Multi-Geo Sites provides more details on how to create group sites (a.k.a. 「モダン」チーム サイトとも呼ばれる) を作成する方法について、より詳細な情報を提供します。このセクションでは、アクセス許可についてのみ扱います。"modern" team sites) using the Microsoft Graph API, in this section we're only addressing the permissions. 以下の表では、必要とされるアクセス許可を一覧で示します。Below table lists the needed permissions

アクセス許可Permission Type 説明Description 管理者の許諾が必要Admin consent needed
Group.ReadWrite.AllGroup.ReadWrite.All アプリケーションのアクセス許可Application permission アプリが、グループの作成、グループ メンバーシップの読み取りと更新、グループの削除ができるようにします。Allows the app to create groups, read and update group memberships, and delete groups. これらの操作はすべて、サインインしているユーザーなしで、アプリで実行できます。All of these operations can be performed by the app without a signed-in user. すべてのグループ API が、アプリ専用のアクセス許可を使用したアクセスをサポートするわけではないことに注意してください。Note that not all group API supports access using app-only permissions. はいYes

Microsoft Graph をベースとする複数地域機能のサンプルは、Microsoft 認証ライブラリ (MSAL) を使用して、v2 エンドポイントで Microsoft Graph に接続します。The Microsoft Graph based Multi-Geo samples are using the Microsoft Authentication Library (MSAL) to connect with the Microsoft Graph on the v2 endpoint. v1 エンドポイントを使用して接続する ADAL に対し、MSAL では、Microsoft アカウント、Azure AD、Azure AD B2C を使用しての Microsoft Graph への接続を許可します。Compared to ADAL which connects using the v1 endpoint, MSAL allows connection to the Microsoft Graph with Microsoft Accounts, Azure AD and Azure AD B2C. 「アプリケーションがすべてのユーザーのプロファイルを読み取り、更新できるようになる必要がある」の章で説明された Azure AD アプリケーションの作成手順を使用します。Use the Azure AD application creation steps as described in the "My application needs to be able to read/update profiles for all users" chapter.

CSOM テナント API を使用しているI'm using the CSOM Tenant API

CSOM テナント API の使用は、前述の CSOM ガイダンスに非常によく似ています。実際、ユーザー資格情報を使用するためのガイダンスは同じです。Using the CSOM Tenant API is very similar to the previously described CSOM guidance, in a matter of fact the guidance for using user credentials is identical. アプリ専用プリンシパルを使用する場合は、手順は同じですが、異なるアクセス許可 (テナント、フル コントロール) を付与する必要があります。For using an app-only principal the instructions are the same but you'll need to grant different permissions (tenant, full control):

<AppPermissionRequests AllowAppOnlyPolicy="true">
  <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" />
</AppPermissionRequests>

関連項目See also