Настройка примера приложения с поддержкой нескольких регионов

  • Статья

При разработке для клиента с несколькими регионами важно понимать модель безопасности. К счастью, модель, используемая для клиента с несколькими регионами, аналогична модели, используемой для обычного клиента.

В этой статье показано, как настроить следующие примеры приложений:

Чтение и обновление профилей для всех пользователей с помощью API Graph

Как описано в статье Работа с профилями пользователей в клиенте с несколькими регионами, предпочтительной моделью для чтения и обновления свойств профиля пользователя является API Graph. В этом разделе описываются разрешения, которые необходимо предоставить приложению для реализации операций чтения и обновлений профиля пользователя на уровне клиента.

Существует длинный список возможных разрешений, которые можно предоставить приложению, определенному в Azure AD, но для управления профилями можно ограничить разрешения следующими.

Разрешение Тип Описание требуется согласие Администратор
User.ReadWrite.All Разрешение приложения Позволяет приложению считывать и записывать полный набор свойств профиля, членства в группах, отчетов и руководителей других пользователей в вашей организации без вошедшего пользователя.

Также позволяет приложению создавать и удалять пользователей, не являющихся администраторами.

Не допускает сброс паролей пользователей.		 Да
Sites.ReadWrite.All Разрешение приложения Позволяет приложению читать и записывать документы и элементы списка во всех семействах веб-сайтов без вошедшего пользователя.

Это разрешение требуется только в том случае, если приложение будет получать расположение личного сайта пользователя (например, https://graph.microsoft.com/v1.0/users/UserB@contoso.onmicrosoft.com?$select=mySite).		 Да

Примеры на основе Microsoft Graph с несколькими регионами используют библиотеку проверки подлинности Майкрософт (MSAL) для подключения к Microsoft Graph в конечной точке версии 2. По сравнению с ADAL, который подключается с помощью конечной точки версии 1, MSAL позволяет подключаться к Microsoft Graph с помощью учетных записей Майкрософт, Azure AD и Azure AD B2C. Следующие инструкции помогут настроить приложение для конечной точки версии 2, но вы также можете использовать "старый" подход на основе конечных точек версии 1.

Регистрация приложения

  1. Чтобы использовать разрешения приложения для Microsoft Graph, зарегистрируйте приложение по адресу https://apps.dev.microsoft.com.

  2. После входа выберите Добавить приложение, а затем — Добавить новое конвергентное приложение.

  3. Присвойте приложению имя и нажмите кнопку Создать приложение.

  4. Откроется экран конфигурации приложения.

Регистрация приложения в Azure AD

  1. Создайте новый пароль и запишите его вместе с идентификатором приложения.

  2. Выберите Добавить платформу, а затем выберите Собственное приложение в качестве целевой платформы, так как у приложения нет целевой страницы.

Настройка приложения в Azure AD часть 1

  1. Добавьте необходимые разрешения приложения. В этом примере приложения мы добавили разрешения приложения Sites.ReadWrite.All и User.ReadWrite.All.

  2. Снимите флажок проверка поддержки Live SDK.

Настройка приложения в Azure AD часть 2

  1. Сохраните изменения.
  1. В этом примере разрешения приложения User.ReadWrite.All и Sites.ReadWrite.All требуют согласия администратора в клиенте, прежде чем их можно будет использовать. Создайте URL-адрес согласия, как показано ниже:
https://login.microsoftonline.com/<tenant>/adminconsent?client_id=<clientid>&state=<something>
  1. Используйте идентификатор клиента из зарегистрированного приложения и согласие на приложение из моего клиента contoso.onmicrosoft.com; URL-адрес выглядит следующим образом:
https://login.microsoftonline.com/contoso.onmicrosoft.com/adminconsent?client_id=6e4433ca-7011-4a11-85b6-1195b0114fea&state=12345
  1. Перейдите по созданному URL-адресу, войдите в систему в качестве администратора клиента и дайте согласие на использование приложения. Вы увидите, что на экране согласия отображается имя приложения, а также области разрешений, которые вы настроили.

Согласие клиента для приложения Azure AD

Чтение и обновление профилей для всех пользователей с помощью API профиля пользователей CSOM

При использовании API CSOM для управления свойствами профиля это делается только для пользовательских созданных свойств, так как готовые свойства лучше обрабатываются через API Graph Майкрософт. Дополнительные сведения см. в статье Работа с профилями пользователей в клиенте с несколькими регионами.

С точки зрения разрешений существует два режима:

  • Использование учетных данных пользователя

    Для этого необходимо настроить ClientContext объект с помощью URL-адреса администратора клиента и учетных данных администратора SharePoint Online. Так как есть только один экземпляр Azure AD, содержащий пользователей, это означает, что администратор SharePoint Online является администратором для всех географических расположений.

    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;
}

  • Использование субъекта только для приложений

    При использовании только приложения необходимо предоставить созданному субъекту приложения полный доступ к http://sharepoint/social/tenant область разрешений.

В следующих инструкциях показано, как использовать appregnew.aspx и appinv.aspx для регистрации субъекта приложения и предоставления согласия на него.

Создание субъекта

  1. Перейдите на сайт в клиенте (например, https://contoso.sharepoint.com), а затем вызовите страницу appregnew.aspx (например, https://contoso.sharepoint.com/_layouts/15/appregnew.aspx).

  2. На этой странице нажмите кнопку Создать , чтобы создать идентификатор клиента и секрет клиента.

  3. Заполните остальные поля следующим образом:

  • Название: Multi-Geo demo
  • Домен приложения: www.localhost.com
  • URI перенаправления: https://www.localhost.com

Регистрация субъекта приложения ACS

Примечание.

Сохраните полученные сведения (идентификатор клиента и секрет клиента), так как они потребуются на следующем шаге.

Важно!

Использование Azure ACS (служб контроль доступа) для SharePoint Online прекращено с 27 ноября 2023 г. См. полное объявление о выходе из эксплуатации, чтобы узнать больше. Использование Azure ACS вне контекста SharePoint уже прекращено 7 ноября 2018 г. и сейчас заканчивается.

Прекращение использования означает, что эта функция не получит новых инвестиций, но она по-прежнему поддерживается. Окончание срока службы означает, что эта функция будет прекращена и больше не доступна для использования.

Предоставление разрешений созданному субъекту

Следующий шаг — предоставление разрешений только что созданному субъекту. Так как мы предоставляем разрешения на уровне клиента, это предоставление можно сделать только на странице appinv.aspx на сайте администрирования клиента.

  1. Вы можете связаться с этим сайтом через https://contoso-admin.sharepoint.com/_layouts/15/appinv.aspx.

  2. После загрузки страницы добавьте идентификатор клиента, а затем найдите созданный субъект.

Предоставление разрешений субъекту приложения

  1. Чтобы предоставить разрешения, необходимо указать XML-код разрешений, описывающий необходимые разрешения. Так как сканер интерфейса пользовательского интерфейса должен иметь доступ ко всем сайтам и использует поиск только для приложений, ему требуются следующие разрешения:
<AppPermissionRequests AllowAppOnlyPolicy="true">
  <AppPermissionRequest Scope="http://sharepoint/social/tenant" Right="FullControl" />
</AppPermissionRequests>
  1. При нажатии кнопки Создать появится диалоговое окно согласия на разрешение. Выберите Доверять ему , чтобы предоставить разрешения.

Согласие субъекта приложения

Использование субъекта в коде

После создания субъекта и получения согласия можно использовать идентификатор и секрет участника для запроса доступа. Класс TokenHelper.cs извлекает идентификатор и секрет из файла конфигурации приложения.

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 выглядит следующим образом:

<?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>

Примечание.

Вы можете легко вставить TokenHelper.cs класс в проект, добавив в решение пакет NuGet [AppForSharePointOnlineWebToolkit] (https://www.nuget.org/packages/AppForSharePointOnlineWebToolkit/).

Обнаружение конфигурации с несколькими регионами

Единственный поддерживаемый API, который можно использовать для обнаружения географических расположений в клиенте с несколькими регионами, — это API Graph. В этом разделе описываются разрешения, которые необходимо предоставить приложению для обнаружения сведений о нескольких регионах.

Существует длинный список возможных разрешений, которые можно предоставить приложению, определенному в Azure AD, но для чтения сведений о конфигурации клиента с несколькими регионами можно ограничить разрешения следующими.

Разрешение Тип Описание требуется согласие Администратор
Sites.ReadWrite.All Разрешение приложения Позволяет приложению читать и записывать документы и элементы списка во всех семействах веб-сайтов без вошедшего пользователя. Да

Выполните действия по созданию приложений Azure AD, как описано в разделе Профили чтения и обновления для всех пользователей.

Создание и удаление семейств веб-сайтов и задание свойств семейства веб-сайтов клиента

Использование microsoft API Graph

В статье о сайтах с несколькими регионами содержатся дополнительные сведения о создании сайтов групп (также известных как "современные" сайты групп) с помощью API Graph Майкрософт. В этом разделе мы рассмотрим только разрешения. В следующей таблице перечислены необходимые разрешения.

Разрешение Тип Описание требуется согласие Администратор
Group.ReadWrite.All Разрешение приложения Позволяет приложению создавать группы, читать и обновлять сведения о членстве в группах, а также удалять группы.

Приложение может выполнять все эти операции без необходимости входа пользователя.

Обратите внимание, что не все API групп поддерживают доступ с помощью разрешений только для приложений.		 Да

Примеры на основе Microsoft Graph с поддержкой нескольких регионов используют библиотеку проверки подлинности Майкрософт (MSAL) для подключения к Microsoft Graph в конечной точке версии 2. По сравнению с ADAL, который подключается с помощью конечной точки версии 1, MSAL позволяет подключаться к Microsoft Graph с помощью учетных записей Майкрософт, Azure AD и Azure AD B2C.

Выполните действия по созданию приложений Azure AD, как описано в разделе Профили чтения и обновления для всех пользователей.

Использование API клиента CSOM

Использование API клиента CSOM очень похоже на ранее описанное руководство по CSOM. в действительности руководство по использованию учетных данных пользователя идентично. Для использования субъекта только для приложений инструкции одинаковы, но необходимо предоставить разные разрешения (клиент и полный доступ).

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

См. также