Регистрация надстроек SharePoint

Зарегистрируйте надстройку SharePoint в Azure ACS, используя Visual Studio, Панель мониторинга продаж или страницу AppRegNew.aspx, и получите регистрационную информацию.

Важно!

Служба контроля доступа Azure (ACS), которая входит в состав Azure Active Directory (Azure AD), будет упразднена 7 ноября 2018 г. Это не влияет на модель надстроек SharePoint, использующую имя узла https://accounts.accesscontrol.windows.net (на который также не влияет это прекращение работы службы). Дополнительные сведения см. в статье Влияние упразднения службы контроля доступа Azure на надстройки SharePoint.

Чтобы удаленные компоненты надстройки SharePoint с размещением у поставщика могли взаимодействовать с SharePoint, используя OAuth, необходимо зарегистрировать надстройку в облачной службе Azure ACS и службе управления приложениями SharePoint клиента или фермы. (Служба управления приложениями называется так, потому что изначально надстройки SharePoint назывались приложениями для SharePoint).

Примечание.

Это не требуется для надстроек с размещением в SharePoint.

Чтобы зарегистрировать надстройку в Azure ACS, укажите следующие сведения:

• GUID надстройки, называемый идентификатором клиента;
• пароль для надстройки, называемый секретом клиента;
• отображаемое имя надстройки, используемое на странице согласия, на которой пользователь указывает, доверяет ли он надстройке;
• URL-адрес домена, в котором размещена удаленная надстройка;
• URL-адрес перенаправления.

Зарегистрированная надстройка имеет идентификатор и является субъектом безопасности. При установке надстройки администраторы SharePoint могут получать информацию об этом субъекте.

Когда пользователь в первый раз предоставляет надстройке разрешения на доступ к ресурсам SharePoint (что может произойти как на этапе установки, так и во время выполнения в зависимости от конструкции надстройки), SharePoint получает информацию о надстройке из Azure ACS. Затем SharePoint сохраняет эту информацию в базе данных службы управления приложениями клиентской организации или фермы SharePoint. Секрет клиента хранится только в Azure ACS. SharePoint никогда не запоминает секрет надстройки. Служба базы данных контента и другие компоненты, например служба профилей пользователей, могут получать отображаемое имя и другие основные сведения о надстройке непосредственно из общей службы управления приложениями. Дополнительные сведения см. в разделе Получение информации о регистрации и субъекте этой статьи.

Примечание.

В этой статье предполагается, что вы знакомы с основными понятиями и принципами платформы OAuth 2.0. Дополнительные сведения см. на сайте OAuth.net и на веб-странице Протокол веб-авторизации (OAuth).

Регистрация надстройки SharePoint в Azure ACS

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

Метод регистрации	Сведения
Создание временного удостоверения надстройки с помощью Visual Studio и Инструментов разработчика Microsoft Office для Visual Studio.	Мастер Инструментов разработчика Office для Visual Studio создает временную регистрацию для надстройки в ACS и службе управления приложениями вашего тестового веб-сайта SharePoint. Когда вы запускаете надстройку в Visual Studio (F5), используется это удостоверение. Инструменты также вставляют идентификатор и секрет клиента в файлы web.config и AppManifest.xml. Когда вы будете готовы к публикации надстройки, воспользуйтесь мастером публикации Visual Studio, чтобы перейти на Панель мониторинга продаж и зарегистрировать надстройку. Если вы не хотите продавать свою надстройку SharePoint в Магазине Office, зарегистрируйте ее с помощью страницы AppRegNew.aspx. (Действия, которые необходимо выполнить, см. ниже.) Примечание. Если надстройка запрашивает разрешение на динамический доступ к ресурсам SharePoint во время выполнения, а не при установке надстройки, вы не сможете использовать Visual Studio для создания удостоверений надстроек.
Зарегистрируйте надстройку на Панели мониторинга продаж.	Если вы собираетесь использовать надстройку в нескольких клиентах или фермах SharePoint, используйте Панель мониторинга продаж для регистрации надстройки независимо от канала распространения (Магазин Office или каталог надстроек). После регистрации на Панели мониторинга продаж вы можете сделать надстройку мультитенантной, не требуя от администраторов клиента или фермы регистрировать ее отдельно. Кроме того, если вы планируете публиковать надстройку в Магазине Office, для регистрации надстройки необходимо использовать Панель мониторинга продаж. Надстройку, зарегистрированную на Панели мониторинга продаж, не обязательно публиковать в Магазине. Дополнительные сведения см. в статье Создание или обновление идентификаторов и секретов клиентов на Панели мониторинга продаж.
Использование страницы AppRegNew.aspx.	Если вы собираетесь использовать надстройку SharePoint только в одной клиентской организации или ферме, используйте для регистрации форму AppRegNew. Например, если вы создаете надстройки для одной организации и собираетесь распространять их через каталог надстроек организации, то для их регистрации можно использовать страницу AppRegNew.aspx любого веб-сайта в клиентской организации или ферме. Надстройку, зарегистрированную с помощью страницы AppRegNew.aspx, невозможно опубликовать в Магазин Office. Для надстроек, опубликованных в Магазин Office, необходимо получить удостоверение из Панель мониторинга продаж.

Регистрация с использованием страницы AppRegNew.aspx

1. Перейдите на страницу <site collection url>/_layouts/15/AppRegNew.aspx в веб-браузере.

   Форма на странице AppRegNew

   

2. Введите значения для указанных ниже полей формы.

   • Идентификатор надстройки. Он также называется идентификатором клиента и представляет собой GUID, который можно создать (нажав кнопку Создать) или вставить на странице AppRegNew.aspx. Значение должно быть уникальным для каждой надстройки и содержать только строчные символы.

   • Секрет надстройки. Он также называется секретом клиента и представляет собой непрозрачную строку. Он создается на странице AppRegNew.aspx с помощью кнопки Создать. Вот пример секрета надстройки: xvVpG0AgVIJfch6ldu4dLUlcZyysmGqBRbpFDu6AfJw=.

     Важно!

     Секреты надстроек имеют ограниченный срок действия. Если вы регистрируете надстройку на Панели мониторинга продаж, срок действия можно указать (не более трех лет). Кроме того, по мере истечения срока действия старых секретов на панели мониторинга можно добавлять новые секреты. Новый секрет будет включен во всех экземплярах надстройки. Если вы регистрируете надстройку с помощью страницы AppRegNew.aspx, срок действия секрета составляет один год. Подробные сведения см. в статье Замена секрета клиента с истекающим сроком действия в надстройке SharePoint.

   • Название. Понятное название; например Надстройка для фотопечати Contoso. Пользователям предлагается предоставить разрешения, необходимые надстройке. Это название появляется в запросе разрешений.

   • Домен надстройки. Имя узла удаленного компонента, входящего в надстройку SharePoint. Если удаленное приложение не использует порт 443, то домен надстройки должен включать номер порта. Домен надстройки должен совпадать с привязками URL-адресов, используемыми для веб-приложения. Не включайте в это значение протокол (https:) или символы "/". Если для узла веб-приложения используется псевдоним DNS CNAME, используйте его. Примеры:

     • www.contoso.com:3333
     • www.fabrikam.com

   • URI перенаправления. Конечная точка в удаленном приложении или службе, на которую ACS отправляет код аутентификации. Строго говоря, надстройки SharePoint не используют это значение. URI перенаправления требуется для веб-приложений, запускаемых за пределами SharePoint и использующих поток кода аутентификации для получения авторизованного доступа к данным SharePoint.

     URI перенаправления игнорируется для настоящих надстроек SharePoint (которые запускаются из SharePoint и используют поток маркера контекста).

     Обычно URI перенаправления представляет собой ту же страницу, метод контроллера или метод веб-службы, которые запрашивали код аутентификации у ACS, но он может быть другой конечной точкой. У конечной точки должна быть логика, получающая код авторизации из ответа HTTP, отправляемого ACS, а затем использующая этот код для запроса доступа и обновления маркера. Дополнительные сведения см. в разделе Поток кода авторизации OAuth для надстроек SharePoint.

     В форму необходимо ввести допустимое значение (даже для настоящих надстроек SharePoint), хотя оно и не используется. Значение должно представлять собой полный URL-адрес конечной точки, включая протокол (обязательно HTTPS). Примеры:

     • https://www.contoso.com/Default.aspx
     • https://www.fabrikam.com/RedirectAccept.aspx
     • https://www.northwindtraders.com/home/index
     • https://adventureworks.com/

3. В форме нажмите кнопку Создать. Страница перезагрузится, и на ней будут показаны введенные значения. Сохраните эти значения в виде, удобном для копирования и вставки. Вам потребуется указать эти значения в файлах web.config и AppManifest.xml или в мастере публикации Visual Studio.

Независимо от способа регистрации, когда вы будете готовы развернуть надстройку в промежуточной или рабочей среде, вам потребуется ввести регистрационные значения в файлы web.config и AppManifest.xml. Если вы используете Visual Studio, Инструменты разработчика Microsoft Office для Visual Studio сделают это автоматически.

Ввод регистрационных значений в файлы web.config и AppManifest.xml

Прежде чем упаковывать надстройку SharePoint и развертывать ее удаленные компоненты, необходимо указать некоторые регистрационные данные в файлах AppManifest.xml и web.config.

Совет

Если вы публикуете свою надстройку SharePoint, используя мастер публикации Visual Studio, Visual Studio запрашивает идентификатор и секрет клиента и автоматически помещает эту информацию в нужные места.

1. В файле Web.config проекта Visual Studio укажите значение идентификатора надстройки в качестве значения ClientId (заменив временное значение, введенное средством).

   Важно!

   Все буквы в GUID идентификатора клиента должны быть строчными.

   Ниже приведен пример.

   <appSettings>
     <add key="ClientId" value="a044e184-7de2-4d05-aacf-52118008c44e " />
     .  .  .
   </appSettings>
   

2. В качестве значения ClientSecret введите секрет надстройки (заменив временное значение, введенное средством).

   В примере ниже показано, как используются значения в файле Web.config или в веб-приложении.

   <appSettings>
     <add key="ClientId" value="a044e184-7de2-4d05-aacf-52118008c44e " />
     <add key="ClientSecret" value="l0z/8TzWN0yQBzMBSEZtYts2Vt3Eo/oE3rfCdPaogKQ= " />
   </appSettings>
   

3. В файле AppManifest.xml в проекте Visual Studio введите значение идентификатора надстройки в качестве значения параметра ClientId, используя строчные буквы.

   Примечание.

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

   В примере ниже показано, как использовать значение ClientId в файле AppManifest.xml.

   <AppPrincipal>
     <RemoteWebApplication ClientId="a044e184-7de2-4d05-aacf-52118008c44e"/>
   </AppPrincipal>
   

4. Инструменты разработчика Office для Visual Studio используют маркер ~remoteAppUrl в элементе StartPage. (Например, <StartPage>~remoteAppUrl/Pages/Default.aspx?{StandardTokens}</StartPage>.) Если вы используете мастер публикации в Visual Studio, то этот маркер сопоставляется с URL-адресом удаленного компонента. Если вы не используете мастер (или если используете его, но публикуете удаленный компонент в Azure), вам нужно вручную заменить маркер значением Домен надстройки, которое вы использовали при регистрации надстройки. Это должно быть точно такое же значение, включающее помимо протокола HTTPS номер порта (если он имеется). Ниже приведен пример.

   <StartPage>https://www.contoso.com/Pages/Default.aspx?{StandardTokens}</StartPage>
   

5. Для элемента Title в файле AppManifest.xml рекомендуется использовать то же значение, которое вы указывали в поле Название на странице AppRegNew.aspx. Значение элемента Title представляет собой имя надстройки, которое отображается для пользователей после ее установки. Если в диалоговом окне согласия надстройка будет иметь имя, отличающееся от ее имени в пользовательском интерфейсе SharePoint, это может ввести пользователя в заблуждение.

   В примере ниже показаны эти значения в манифесте надстройки.

   <Properties>
     <Title>Contoso photo printing app</Title>
     <StartPage>https://www.contoso.com/Pages/Default.aspx?{StandardTokens}</StartPage>
   </Properties>
   

Использование URL-адреса перенаправления в надстройке, запрашивающей разрешения во время выполнения

Если веб-приложение запускается за пределами SharePoint (и, таким образом, не является настоящей надстройкой SharePoint), оно должно запрашивать разрешения у SharePoint во время выполнения. Оно должно содержать код, использующий URI перенаправления и другие сведения, для получения маркера доступа от ACS. Найдите место, где задан этот URI, и используйте точно такое же значение, которое указано в поле URI перенаправления в AppRegNew.aspx или в Панели мониторинга продаж. Это может быть файл кода или файл конфигурации.

Получение информации о регистрации и субъекте

Вы можете получить информацию о регистрации и субъекте для надстроек, которые вы установили или зарегистрировали в SharePoint.

Чтобы найти информацию о регистрации надстройки, перейдите по адресу http://<SharePointWebsite>/_layouts/15/AppInv.aspx.

Для поиска необходимо использовать идентификатор клиента (идентификатор надстройки), указанный при регистрации надстройки. Результаты поиска будут содержать указанные ниже сведения для заданного идентификатора клиента.

• Название
• Домен надстройки.
• URL-адрес перенаправления (то же, что и URI перенаправления).

При поиске не будет возвращено значение секрета надстройки.

Чтобы посмотреть список зарегистрированных субъектов, перейдите по следующему адресу: http://<SharePointWebsite>/_layouts/15/AppPrincipals.aspx.

Дополнительные ресурсы

• Три системы авторизации для надстроек SharePoint
• Знакомство с созданием надстроек SharePoint с размещением у поставщика
• Авторизация и проверка подлинности для надстроек в SharePoint