Share via

Подключение к API, защищенным службой Azure AD, в решениях SharePoint Framework

  • Статья

При создании решений SharePoint Framework может потребоваться подключиться к API, защищенному с помощью Azure Active Directory (Azure AD). На платформе SharePoint Framework можно указать, какие разрешения и приложения Azure AD необходимы вашему решению, а глобальный администратор или администратор SharePoint может предоставить необходимые разрешения, если они еще не предоставлены. С помощью AadHttpClient вы можете легко подключаться к API, защищенным службой Azure AD, не реализуя поток OAuth самостоятельно.

Обзор разрешений веб-API

Azure AD защищает ряд ресурсов, от Office 365 до специальных бизнес-приложений, созданных в организации. Чтобы подключаться к этим ресурсам, приложению необходимо получить действительный маркер доступа для определенного ресурса. Приложение может получить маркер доступа в ходе потока авторизации OAuth.

Клиентские приложения, которые не могут хранить секрет, например решения SharePoint Framework, используют специальный вариант потока OAuth, называемый неявным потоком OAuth.

Разработчики клиентских решений несут ответственность за реализацию авторизации с использованием неявного потока OAuth в своем приложении. В решениях SharePoint Framework это уже сделано на уровне платформы с помощью объектов MSGraphClient и AadHttpClient, появившихся в SharePoint Framework 1.4.1.

Примечание

Если вы создаете решения на платформе SharePoint Framework версии ниже 1.4.1, вы все еще можете подключаться к ресурсам, защищенным службой Azure AD. В этом случае необходимо реализовать неявный поток OAuth, напрямую используя библиотеки проверки подлинности на основе платфамиров удостоверений Майкрософт. Дополнительные сведения см. в статье Подключение к API, защищенному с помощью Azure Active Directory.

As part of the SharePoint Framework, a specific process is defined for how developers can request permissions and administrators can manage permissions to resources secured with Azure AD. The following schema illustrates this process.

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

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

Все разрешения предоставляются всему клиенту, а не только тому приложению, которое их запрашивает. Когда администратор предоставляет определенное разрешение, оно добавляется в приложение Azure AD Расширение клиента SharePoint Online, которое подготавливается корпораций Майкрософт в каждой службе Azure AD и используется платформой SharePoint Framework в потоке OAuth для предоставления решений с действительными маркерами доступа.

Определение доступных приложений и разрешений

Целевая служба Azure AD, которая защищает Office 365, также определяет, для каких приложений можно запрашивать разрешения в вашем решении. Список доступных приложений может зависеть от лицензии на Office 365, используемой в организации, и от того, какие бизнес-приложения зарегистрированы в ее службе Azure AD. Если у вас есть необходимые разрешения, вы можете несколькими способами определять, какие приложения и области разрешений доступны в клиенте.

Использование портала Azure или центра администрирования Azure AD

Один из способов просмотреть доступные приложения в Azure AD — перейти на портал Azure или в центр администрирования Azure AD.

  1. В центре администрирования Azure AD выберите ссылку Корпоративные приложения в области навигации слева.

    Ссылка "Корпоративные приложения", выделенная на портале Azure AD

  2. В колонке Корпоративные приложения, в группе Управление, выберите ссылку Все приложения.

    Ссылка "Все приложения", выделенная на портале Azure AD

  3. Чтобы быстрее найти приложение, к которому требуется подключиться, выполните фильтрацию по типу приложения (Приложения Майкрософт или Корпоративные приложения) либо поиск по имени или идентификатору.

    Например, если вам нужно запросить дополнительные разрешения для Microsoft Graph, введите в поле поиска запрос graph.

    Поиск по слову "graph" в списке доступных приложений Azure AD на портале Azure AD

  4. Когда вы найдете приложение, выберите его для получения дополнительной информации. В колонке приложения в группе Управление выберите Свойства, чтобы открыть свойства приложения.

    Ссылка "Свойства", выделенная в колонке приложения на портале Azure AD

  5. В списке свойств скопируйте значение свойства ИД объекта. Оно необходимо, чтобы запросить дополнительные области разрешений для Microsoft Graph. Вместо этого, можно скопировать Имя приложения и использовать его в запросе на получение разрешений.

    Значение свойства "ИД объекта", скопированное в буфер обмена с портала Azure AD

Примечание

Свойство ИД объекта уникально для каждого клиента, но во всех клиентах используется одно и то же имя. Если вам нужно собрать решение один раз и развернуть его в разных клиентах, следует использовать имя, запрашивая дополнительные разрешения в решении.

Использование Azure PowerShell

Примечание

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

  1. Войдите в учетную запись своей подписки Azure, выполнив в PowerShell следующую команду (это необязательно, если используется Azure Cloud Shell):

    Login-AzureRmAccount

  2. Введите следующую команду, чтобы получить список приложений, доступных в клиенте:

    Get-AzureRmADServicePrincipal | sort DisplayName | ft DisplayName, Id

    Running this cmdlet lists all applications available in your tenant. For each application, its display name and object ID are displayed, which you can use in your SharePoint Framework solution to request application permissions.

Использование интерфейса командной строки Azure

Примечание

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

  1. Если интерфейс командной строки работает на вашем компьютере или в контейнере Docker, для начала подключитесь к своей подписке на Azure с помощью следующей команды:

    azure login

  2. После подключения выполните следующую команду, чтобы получить список всех доступных приложений Azure AD:

    azure ad sp list --query "sort_by([*].{displayName: displayName, objectId: objectId}, &displayName)" -o table

    При выполнении этой команды появится список всех доступных в клиенте приложений Azure AD, отсортированный по свойству displayName. Эта команда выводит свойства displayName и objectId каждого приложения. Кроме того, выходные данные форматируются в виде таблицы.

Получение списка областей разрешений, предоставляемых приложением

Каждое приложение Azure AD предоставляет ряд областей разрешений. Зачастую они относятся к определенным ресурсам или операциям в приложении. Чтобы получить список доступных разрешений для приложения, к которому требуется подключиться, ознакомьтесь с документацией к нему. Список областей разрешений, доступных в Microsoft Graph, представлен в статье Справочник по разрешениям Microsoft Graph.

Запрашивание разрешений для приложения Azure AD

Если вашему решению SharePoint Framework требуются разрешения для определенных ресурсов, защищенных с помощью Azure AD, например Microsoft Graph или корпоративных приложений, вы можете указывать эти ресурсы вместе с необходимыми разрешениями в конфигурации решения.

  1. В проекте SharePoint Framework откройте файл config/package-solution.json.

  2. В свойстве solution добавьте свойство webApiPermissionRequests, в котором перечислены все ресурсы и соответствующие разрешения, необходимые решению.

    Ниже представлен пример решения SharePoint Framework, запрашивающего доступ на чтение календарей пользователей с помощью Microsoft Graph.

    {
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "spfx-graph-client-side-solution",
    "id": "5d16587c-5e87-44d7-b658-1148988f212a",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "webApiPermissionRequests": [
      {
        "resource": "Microsoft Graph",
        "scope": "Calendars.Read"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/spfx-graph.sppkg"
  }
}

    Примечание

    В качестве значения свойства resource нужно указать displayName приложения, для которого запрашиваются разрешения. Если указать ресурс с помощью его objectId, вы получите сообщение об ошибке при попытке утвердить запрос на предоставление разрешений.

  3. Если вам нужно запросить несколько областей разрешений для того или иного ресурса, указывайте каждую область в отдельной записи, например:

    {
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "spfx-graph-client-side-solution",
    "id": "5d16587c-5e87-44d7-b658-1148988f212a",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "webApiPermissionRequests": [
      {
        "resource": "Microsoft Graph",
        "scope": "Calendars.Read"
      },
      {
        "resource": "Microsoft Graph",
        "scope": "User.ReadBasic.All"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/spfx-graph.sppkg"
  }
}

  4. При развертывании этого решения в каталоге приложений SharePoint администратору предлагается проверить запрашиваемые разрешения и предоставить их либо отказать.

    Примечание

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

Управление запросами на получение разрешений

When you deploy SharePoint Framework solutions that request permissions to Azure AD applications, administrators are prompted to manage the permission request provided with the solution. Permission requests can be managed in several ways.

Управление разрешениями в новом Центре администрирования SharePoint

Сведения о том, как использовать страницу доступа API в новом Центре администрирования SharePoint, см. в статье Управление доступом к API, защищенным с помощью Azure AD.

Управление разрешениями с помощью PowerShell

Глобальный администратор и администратор SharePoint также могут управлять разрешениями и запросами на их получение в SharePoint Online с помощью командной консоли SharePoint Online.

  • Чтобы просмотреть все запросы на получение разрешений, ожидающие проверки, используйте командлет Get-SPOTenantServicePrincipalPermissionRequests. Этот командлет выводит для каждого запроса на получение разрешений ИД (необходимый для утверждения или отклонения запроса), имя ресурса, для которого запрашиваются разрешения, и названия этих разрешений.

    Примечание

    SharePoint не проверяет, предоставлены ли уже запрашиваемые разрешения, поэтому прежде чем утверждать или отклонять запрос на получение разрешений, проверьте, какие разрешения уже предоставлены в клиенте.

  • Чтобы утвердить определенный запрос на получение разрешений, используйте командлет Approve-SPOTenantServicePrincipalPermissionRequest -RequestId <Guid>, указав ИД нужного запроса.

    Примечание

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

  • Чтобы отклонить запрос разрешения (если запрашиваемое разрешение уже было предоставлено либо запрос противоречит политикам организации), используйте командлет Deny-SPOTenantServicePrincipalPermissionRequest -RequestId <Guid>, указав ИД нужного запроса.

    Примечание

    Даже если запрос на получение разрешений, отправленный приложением SharePoint Framework, был отклонен, приложение все равно можно развернуть в каталоге приложений и устанавливать на сайтах.

  • Чтобы просмотреть разрешения, предоставленные в клиенте, используйте командлет Get-SPOTenantServicePrincipalPermissionGrants. Этот командлет выводит следующие сведения о каждом предоставленном разрешении:

    • ClientId. Свойство objectId субъекта-службы, которому предоставлено разрешение действовать от имени пользователя при доступе к ресурсу (представленному свойством resourceId).
    • ConsentType. Указывает, кем было предоставлено согласие — администратором для организации или отдельным лицом. Возможные значения: AllPrincipals и Principal.
    • ObjectId. Уникальный идентификатор предоставленного разрешения.
    • Resource. Ресурс, к которому предоставлен доступ.
    • ResourceId. Свойство objectId субъекта-службы ресурса, к которому предоставлен доступ.
    • Scope. Ожидаемое значение требования scope в маркере доступа OAuth 2.0.

  • Чтобы отозвать предоставленное ранее разрешение, используйте командлет Revoke-SPOTenantServicePrincipalPermission -ObjectId <String>. В параметре ObjectId следует указать objectId нужного разрешения. Это значение можно получить с помощью командлета Get-SPOTenantServicePrincipalPermissionGrants.

    Примечание

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

Управление разрешениями с помощью CLI для Microsoft 365

Глобальный администратор и администратор SharePoint могут управлять разрешениями и запросами на их получение в SharePoint Online с помощью CLI для Microsoft 365.

Примечание

CLI для Microsoft 365 — это решение с открытым исходным кодом, поддерживаемое активным сообществом. SLA для поддержки инструмента с открытым исходным кодом со стороны Майкрософт отсутствует.

  • Чтобы просмотреть все запросы на получение разрешений, ожидающие проверки, используйте команду spo serviceprincipal permissionrequest list. Для каждого запроса на получение разрешений эта команда выводит ИД (необходимый для утверждения или отклонения запроса), имя ресурса, для которого запрашиваются разрешения, и названия этих разрешений.

    Примечание

    SharePoint не проверяет, предоставлены ли уже запрашиваемые разрешения, поэтому прежде чем утверждать или отклонять запрос на получение разрешений, проверьте, какие разрешения уже предоставлены в клиенте.

  • Чтобы утвердить определенный запрос на получение разрешений, используйте команду spo serviceprincipal permissionrequest approve, указав ИД нужного запроса.

    Примечание

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

  • Чтобы отклонить запрос разрешения (если запрашиваемое разрешение уже было предоставлено либо запрос противоречит политикам организации), используйте команду spo serviceprincipal permissionrequest deny, указав ИД нужного запроса.

    Примечание

    Даже если запрос на получение разрешений, отправленный приложением SharePoint Framework, был отклонен, приложение все равно можно развернуть в каталоге приложений и устанавливать на сайтах.

  • Чтобы просмотреть разрешения, предоставленные в клиенте, используйте команду spo serviceprincipal grant list. Эта команда выводит следующие сведения о каждом предоставленном разрешении:

    • ObjectId. Уникальный идентификатор предоставленного разрешения.
    • Resource. Ресурс, к которому предоставлен доступ.
    • ResourceId. Свойство objectId субъекта-службы ресурса, к которому предоставлен доступ.
    • Scope. Ожидаемое значение требования scope в маркере доступа OAuth 2.0.

  • Чтобы отозвать предоставленное ранее разрешение, используйте команду spo serviceprincipal grant revoke. В параметре grantId укажите objectId нужного разрешения. Это значение можно получить с помощью команды spo serviceprincipal grant list.

    Примечание

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

Подключение к приложениям AD с помощью AadHttpClient

Представленное в версии 1.4.1, SharePoint Framework упрощает подключение к API, защищенным при помощи Azure AD. С помощью нового объекта AadHttpClient вы можете легко подключаться к API, защищенным службой Azure AD, не реализуя проверку подлинности и авторизацию самостоятельно.

На внутреннем уровне AadHttpClient реализует поток Azure AD OAuth, использующий библиотеки проверки подлинности платформа удостоверений Майкрософт с помощью субъекта-службы расширяемости клиента SharePoint Online для получения допустимого маркера доступа. Субъект-служба Расширение клиента SharePoint Online подготавливается к работе корпорацией Майкрософт и доступна в Azure AD для всех клиентов Office 365.

  1. Чтобы использовать объект AadHttpClient в решении SharePoint Framework, добавьте выражение import в основной файл веб-части:

    import { AadHttpClient, HttpClientResponse } from '@microsoft/sp-http';

  2. Получите экземпляр объекта AadHttpClient, передав в качестве параметров ресурс, к которому требуется подключиться:

    export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    // ...

    this.context.aadHttpClientFactory
      .getClient('https://contoso.azurewebsites.net')
      .then((client: AadHttpClient): void => {
        // connect to the API
      });
  }

  // ...
}

    Примечание

    Каждый экземпляр объекта AadHttpClient связан с определенным ресурсом. Именно поэтому необходимо создавать новый экземпляр клиента для каждого подключаемого ресурса.

  3. Создав экземпляр AadHttpClient для ресурса, вы можете отправить веб-запрос для связи с API. В этом примере API возвращает список заказов, представленный пользовательским интерфейсом Order, который определен в другом файле проекта:

    export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    // ...

    this.context.aadHttpClientFactory
      .getClient('https://contoso.azurewebsites.net')
      .then((client: AadHttpClient): void => {
        client
          .get('https://contoso.azurewebsites.net/api/orders', AadHttpClient.configurations.v1)
          .then((response: HttpClientResponse): Promise<Order[]> => {
            return response.json();
          })
          .then((orders: Order[]): void => {
            // process data
          });
      });
  }

  // ...
}

Замечания

Ниже представлены некоторые замечания, которые следует учитывать при работе с разрешениями веб-API.

Запрашивание разрешений с помощью решений SharePoint Framework

В данный момент запрашивать дополнительные разрешения можно только с помощью решения SharePoint Framework. Запрос инициируется при развертывании пакета решения (.sppkg), содержащего запрос на получение разрешений, в каталоге приложений. После этого глобальный администратор или администратор SharePoint может утвердить или отклонить запрос.

Предоставленные разрешения применяются ко всем решениям

Несмотря на то что решение SharePoint Framework запрашивает разрешения для ресурсов Azure AD, после предоставления они применяются ко всему клиенту, и их может использовать любое решение в этом клиенте.

Разрешения не отзываются при удалении решения

При удалении решения, которое изначально запросило то или иное разрешение, предоставленное разрешение не отзывается. Администраторам необходимо вручную отзывать разрешения, предоставленные по запросам приложений SharePoint Framework.

Отзыв ранее предоставленных разрешений не делает недействительными выданные маркеры доступа

Отзыв ранее предоставленных разрешений не делает недействительными маркеры доступа, выданные пользователям. Эти маркеры доступа остаются действительными, пока не истечет срок их действия.

Запрос на получение разрешений не влияет на развертывание решений

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

Управление субъектом-службой клиента SharePoint Online

Все разрешения, предоставленные по запросам веб-API, хранятся с помощью приложения Azure AD Расширение клиента SharePoint Online. Если администраторам не нужно, чтобы разработчики использовали модель запросов веб-API, а также объекты MSGraphClient и AadHttpClient в своих решениях, они могут отключить субъект-службу Расширение клиента SharePoint Online в консоли PowerShell с помощью командлета Disable-SPOTenantServicePrincipal.

Субъект-службу можно заново включить с помощью командлета Enable-SPOTenantServicePrincipal. Вместо этого также можно включать и отключать субъект-службу Расширение клиента SharePoint Online с помощью CLI для Microsoft 365, используя команду spo serviceprincipal set.