Использование корпоративных API, защищенных службой Azure AD в SharePoint Framework

В этой статье показан порядок подключения к корпоративным API, защищенными службой Azure Active Directory с решения SharePoint Framework. Здесь рассмотрено как создание и защита API, так и создание решения SharePoint Framework.

Создание корпоративного API, защищенного службой Azure AD

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

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

Создание функции Azure

На портале Azure создайте новое приложение-функцию.

Дополнительную информацию о создании приложения-функции в Azure можно найти в справочной статье Создание приложения-функции на портале Azure.

В приложении-функции вы создадите новую функцию, активируемую с помощью HTTP. В этом примере вы создадите функцию, используя C#, но, как правило, ограничений касательно выбора языка программирования нет.

В приложении-функции нажмите кнопку Создать функцию:

В списке шаблонов выберите Триггер HTTP:

На панели создания функции укажите название функции, задайте Уровень авторизации как Анонимный и нажмите кнопку Создать:

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

После создания функции замените ее содержимое на следующие фрагменты кода:

#r "Newtonsoft.Json"

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;

public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    return (ActionResult)new OkObjectResult(new List<object> {
        new {
            Id = 1,
            OrderDate = new DateTime(2016, 1, 6),
            Region = "east",
            Rep = "Jones",
            Item = "Pencil",
            Units = 95,
            UnitCost = 1.99,
            Total = 189.05
        },
        new {
            Id = 2,
            OrderDate = new DateTime(2016, 1, 23),
            Region = "central",
            Rep = "Kivell",
            Item = "Binder",
            Units = 50,
            UnitCost = 19.99,
            Total = 999.50
        },
        new {
            Id = 3,
            OrderDate = new DateTime(2016, 2, 9),
            Region = "central",
            Rep = "Jardine",
            Item = "Pencil",
            Units = 36,
            UnitCost = 4.99,
            Total = 179.64
        },
        new {
            Id = 4,
            OrderDate = new DateTime(2016, 2, 26),
            Region = "central",
            Rep = "Gill",
            Item = "Pen",
            Units = 27,
            UnitCost = 19.99,
            Total = 539.73
        },
        new {
            Id = 5,
            OrderDate = new DateTime(2016, 3, 15),
            Region = "west",
            Rep = "Sorvino",
            Item = "Pencil",
            Units = 56,
            UnitCost = 2.99,
            Total = 167.44
        }
    });
}

Убедитесь, что функция работает правильно, нажав кнопку Сохранить и запустить:

Если функции работают правильно, вы увидите метку Состояние: 200 ОК и список заказов в области тестирования.

Защита функции Azure

Теперь функция Azure работает. Далее следует обеспечить ее безопасность с помощью Azure Active Directory, чтобы доступ к ней можно было получить, только войдя в учетную запись вашей организации.

В колонке приложения-функции на боковой панели выберите приложение-функцию:

В области сверху перейдите на вкладку Функции платформы:

После этого в группе Сеть выберите ссылку Аутентификация/авторизация.

В колонке Аутентификация/авторизация включите проверку подлинности службы приложений, установив переключатель аутентификации службы приложений в положение Вкл:

В раскрывающемся списке Предпринимаемое действие, если проверка подлинности для запроса не выполнена измените значение на Войти с помощью Azure Active Directory. Этот параметр обеспечивает запрет анонимных запросов к API:

После этого выберите Azure Active Directory в списке поставщиков аутентификации:

В колонке Параметры Azure Active Directory выберите для параметра Режим управления значение Экспресс. Для второго параметра Режим управления выберите Создать новое приложение AD:

Важно!

Прежде чем продолжить, обратите внимание на значение в поле Создать приложение. Это значение отображает название приложения Azure AD, которое вы будете использовать для обеспечения безопасности API. Оно понадобится вам позже для запроса разрешений доступа к API из проекта SharePoint Framework.

Подтвердите выбор, нажав кнопку OK.

В колонке Аутентификация/авторизация обновите параметры аутентификации и авторизации приложения-функции, нажав кнопку Сохранить:

Убедитесь, что API правильно защищен: откройте новое окно браузера в режиме скрытной связи и перейдите к API. URL-адрес приложения-функции можно найти в разделе Обзор колонки приложения-функции. Если параметры аутентификации были применены правильно, вы будете перенаправлены на страницу входа Azure AD:

Получите идентификатор приложения Azure AD

Чтобы запросить токен доступа для подключения к API, вам понадобится идентификатор приложения Azure AD, которое использовалось для обеспечения безопасности API.

В приложении-функции перейдите к параметрам Проверки подлинности. Если ссылка Аутентификация недоступна в заголовке Настроенные функции, нажмите кнопку Обновить рядом с приложением-функцией на панели слева:

Выберите Azure Active Directory в списке поставщиков аутентификации:

В колонке Параметры Azure Active Directory нажмите кнопку Управление приложением:

В колонке приложения Azure AD скопируйте значение свойства Идентификатор приложения:

Включение CORS

Функциональное приложение будет запускаться из JavaScript запущенного на странице SharePoint. Так как API размещен не на том же домене, что и портал SharePoint, ограничения междоменной безопасности будут применяться к запуску API. По умолчанию API, реализованные с помощью функциональных приложений Azure, невозможно запустить с других доменов. Это можно изменить с помощью настройки параметров CORS приложения-функции.

Важно!

Если для аутентификации в API используется файл cookie SharePoint Online, а не OAuth, вы не сможете настроить параметры CORS на портале Azure. Чтобы аутентификация работала, необходимо удалить все параметры CORS на портале Azure и указать их в API.

В приложении-функции перейдите на вкладку Функции платформы.

В группе API выберите ссылку CORS:

Добавьте URL-адрес клиента SharePoint в список разрешенных источников, например, https://contoso.sharepoint.com:

Подтвердите изменения, нажав кнопку Сохранить.

Использование корпоративного API, защищенного службой Azure AD в SharePoint Framework

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

Перед продолжением убедитесь, что установили генератор Yeoman SharePoint Framework версии 1.4.1 или более поздней версии. Если генератор установлен глобально, вы можете узнать установленную версию, выполнив в командной строке следующее: npm ls -g --depth=0.

Создание проекта SharePoint Framework

Далее вы создадите новый проект SharePoint Framework для использования API.

В командной строке создайте папку для проекта:

md contoso-api

Измените рабочий каталог.

cd contoso-api

Для создания нового проекта запустите генератор Yeoman для SharePoint Framework:

yo @microsoft/sharepoint

Когда появится соответствующий запрос, укажите следующие значения:

• Имя вашего решения? contoso-api
• Какие базовые пакеты нужно выбрать для ваших компонентов? Только SharePoint Online (последняя версия)
• Где следует разместить файлы? Использовать текущую папку
• Предоставить ли администратору клиента возможность развернуть решение на всех сайтах сразу, не запуская развертывание компонентов или добавление приложений на сайтах? Да
• Потребуются ли компонентам решения уникальные разрешения на доступ к веб-API, не используемые другими компонентами в клиенте? Нет
• Какой тип клиентского компонента нужно создать? WebPart
• Как называется ваша веб-часть? Заказы
• Какое описание у вашей веб-части? Отображение недавних покупок
• Какую платформу нужно использовать? Без платформы JavaScript

После создания проекта откройте его в редакторе кода. В этом руководстве используется Visual Studio Code.

Запрос разрешений для корпоративного API

По умолчанию SharePoint Framework не имеет доступа к корпоративным API, несмотря на то что они зарегистрированы в том же Azure Active Directory, что и Office 365. Это предусмотрено службой и позволяет организациям осознанно выбирать API, которые будут доступны сценариям и клиентским решениям, развернутым с помощью SharePoint. Для получения доступа к API вашей организации вам необходимо сделать запрос разрешения из создаваемого проекта SharePoint Framework.

В редакторе кода откройте файл config/package-solution.json:

В свойстве solution добавьте новое свойство под названием webApiPermissionRequests со ссылкой на приложение Azure AD, используемое для защиты вашего API:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "contoso-api-client-side-solution",
    "id": "8cbc01fb-bab6-48fc-afec-2c2053759771",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "isDomainIsolated": false,
    "webApiPermissionRequests": [
      {
        "resource": "contoso-api-dp20191109",
        "scope": "user_impersonation"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/contoso-api.sppkg"
  }
}

Значение свойства resource должно относиться к названию приложения Azure AD, использованного для обеспечения безопасности API. Значение свойства scope определяет область разрешений, которая требуется вашему решению, чтобы взаимодействовать с API. В этом обучении Azure AD используется только для обеспечения безопасности API, поэтому user_impersonation является областью, которую вы будете использовать.

Примечание.

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

Подключение к корпоративному API

Теперь осталось реализовать фактическое подключение к корпоративному API.

В редакторе кода откройте файл src\webparts\orders\OrdersWebPart.ts:

В верхней части файла ссылайтесь на классы AadHttpClient и HttpClientResponse, добавив следующий фрагмент программного кода:

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

Добавьте к классу OrdersWebPart новую классовую переменную под названием ordersClient:

export default class OrdersWebPart extends BaseClientSideWebPart<IOrdersWebPartProps> {
  private ordersClient: AadHttpClient;

  // shortened for brevity
}

Затем в классе OrdersWebPart переопределите метод onInit() для создания нового экземпляра AadHttpClient:

export default class OrdersWebPart extends BaseClientSideWebPart<IOrdersWebPartProps> {
  private ordersClient: AadHttpClient;

  protected onInit(): Promise<void> {
    return new Promise<void>((resolve: () => void, reject: (error: any) => void): void => {
      this.context.aadHttpClientFactory
        .getClient('6bc8bca8-5866-405d-b236-9200bdbb73c0')
        .then((client: AadHttpClient): void => {
          this.ordersClient = client;
          resolve();
        }, err => reject(err));
    });
  }

  // shortened for brevity
}

GUID на месте второго параметра конструктора AadHttpClient — это идентификатор приложения Azure AD, используемого для обеспечения безопасности корпоративного API.

Теперь расширьте метод render() для загрузки и отображения заказов, полученных из корпоративного API:

export default class OrdersWebPart extends BaseClientSideWebPart<IOrdersWebPartProps> {
  private ordersClient: AadHttpClient;

  protected onInit(): Promise<void> {
    return new Promise<void>((resolve: () => void, reject: (error: any) => void): void => {
      this.context.aadHttpClientFactory
        .getClient('6bc8bca8-5866-405d-b236-9200bdbb73c0')
        .then((client: AadHttpClient): void => {
          this.ordersClient = client;
          resolve();
        }, err => reject(err));
    });
  }

  public render(): void {
    this.context.statusRenderer.displayLoadingIndicator(this.domElement, 'orders');

    this.ordersClient
      .get('https://contoso-api-dp20191109.azurewebsites.net/api/Orders', AadHttpClient.configurations.v1)
      .then((res: HttpClientResponse): Promise<any> => {
        return res.json();
      })
      .then((orders: any): void => {
        this.context.statusRenderer.clearLoadingIndicator(this.domElement);
        this.domElement.innerHTML = `
          <div class="${ styles.orders}">
            <div class="${ styles.container}">
              <div class="${ styles.row}">
                <div class="${ styles.column}">
                  <span class="${ styles.title}">Orders</span>
                  <p class="${ styles.description}">
                    <ul>
                      ${orders.map(o => `<li>${o.rep} $${o.total}</li>`).join('')}
                    </ul>
                  </p>
                  <a href="https://aka.ms/spfx" class="${ styles.button}">
                    <span class="${ styles.label}">Learn more</span>
                  </a>
                </div>
              </div>
            </div>
          </div>`;
      }, (err: any): void => {
        this.context.statusRenderer.renderError(this.domElement, err);
      });
  }

  // shortened for brevity
}

Развертывание решения в каталоге приложений SharePoint

После завершения реализации решения SharePoint Framework вам необходимо будет развернуть его в SharePoint.

Сначала выполните сборку и упакуйте проект с помощью командной строки:

gulp bundle --ship && gulp package-solution --ship

Затем в проводнике откройте папку проекта и перейдите в папку Sharepoint/solution:

В веб-браузере перейдите в каталог приложений клиента в своем клиенте Office 365:

Добавьте новый файл .sppkg, перетащив его из проводника в каталог приложений клиента:

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

Предоставление доступа к корпоративному API

В веб-браузере перейдите к сайту администратора клиента, выбрав в средстве запуска приложений Office 365 параметр Администратор:

В меню из группыЦентры управления выберите SharePoint:

В центре администрирования SharePoint перейдите к просмотру нового центра администрирования SharePoint с помощью ссылки Просмотр нового центра администрирования SharePoint:

В новой версии центра администрирования из меню выберите параметр Управление API:

На странице управления API в группе Ожидающие утверждения выберите новый запрос разрешения для доступа к API contoso api (будет отображаться название вашего API):

После этого на панели инструментов нажмите кнопку Утвердить или отклонить:

Предоставьте доступ к API, нажав на боковой панели кнопку Утвердить:

Примечание.

Существует возможность создания веб-части, изолированной в домене, которая подключается к API, защищенному с помощью AAD. В этом случае необходимо правильно настроить CORS для API, поскольку каждый экземпляр веб-части, изолированной в домене, выполняется в выделенном сайте приложения на уникальном домене.

Добавьте веб-часть "Заказы" на страницу

Чтобы убедиться, что все работает должным образом, добавьте созданную ранее веб-часть "Заказы" на страницу.

В веб-браузере перейдите на нужный сайт в вашем клиенте. На панели инструментов выберите параметр Изменить:

В конструкторе выберите раздел, в который следует добавить веб-часть:

Выберите параметр +, чтобы открыть панель элементов. В поле поиска введите Заказы для быстрого поиска веб-части Заказы:

Выберите веб-часть Заказы и добавьте ее на страницу. Вы увидите список заказов, полученных с корпоративного API:

Если вы получили сообщение об ошибке "Не удалось открыть всплывающее окно", у вас включено блокирование всплывающих окон. Отключите блокирование всплывающих окон браузера, чтобы сайт правильно отобразил страницу.