Создание надстроек SharePoint, использующих авторизацию с низким уровнем доверия

  • Статья

Удаленные компоненты в надстройке SharePoint (или внешнем приложении) могут проходить авторизацию для доступа к ресурсам SharePoint, передавая маркер доступа в SharePoint с каждым HTTP-запросом. Удаленные компоненты получают маркер доступа из учетной записи службы контроля доступа Microsoft Azure (ACS), сопоставленной с областью клиентов Office 365 пользователя. Azure ACS выступает в качестве сервера авторизации в транзакции OAuth 2.0, называемой потоком. При этом SharePoint используется в качестве сервера ресурсов, а удаленные компоненты — в качестве клиентов. Сведения о характеристиках этого протокола см. в статье Протокол веб-авторизации (oauth).

Важно!

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

Надстройки SharePoint, для которых используется система авторизации с низким уровнем доверия, можно продавать в Магазине Office, а также устанавливать в Microsoft SharePoint Online и в локальной ферме SharePoint, настроенной так, чтобы использовать область клиентов Office 365 пользователя для создания доверия с помощью Azure ACS. Чтобы можно было установить надстройку SharePoint, для которой используется система с низким уровнем доверия, у пользователя должна быть область клиентов Office 365. Пользователь может не применять область клиентов в каких-либо других целях. Инструкции о том, как связать локальную ферму с областью клиентов Office 365, см. в статье Использование сайта SharePoint Office 365 для авторизации размещаемых у поставщика надстроек на локальном сайте SharePoint.

Регистрация в Azure ACS

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

Для надстроек, продаваемых в Магазине Office, регистрацию в ACS можно выполнить в службе "Панель мониторинга продаж". Такая регистрация выполняется при установке надстройки.

Для надстроек, которые распространяются в каталоге надстроек организации, регистрация в ACS и службе выполняется на странице _Layouts\15\AppRegNew.aspx любого клиента Или фермы SharePoint, где должна быть установлена надстройка. Внешние приложения (не приложения SharePoint), получающие доступ к SharePoint, также необходимо зарегистрировать. Эта категория включает надстройки Office, приложения Microsoft Store, веб-приложения и приложения для устройств, например для смартфонов.

Примечание.

Чтобы можно было выполнить регистрацию, у приложения должен быть домен Интернета. Для этой цели можно использовать любой существующий домен. Но нельзя со 100%-й уверенностью полагать, что какой-либо не принадлежащий вам домен однажды не прекратит существование. Поэтому веб-приложение должно быть частью встроенного приложения для устройства, даже если компонент, представляющий собой веб-приложение, используется только для регистрации. Расширенный пример кода, разработанного по такой схеме, см. в статье Подготовка сайтов в пакетах с помощью модели надстроек.

Дополнительные сведения о регистрации см. в статье Регистрация надстроек SharePoint.

Окончание срока действия секрета надстройки

Секрет надстройки необходимо заменять каждые 12 месяцев. Дополнительные сведения см. в статье Замена секрета клиента с истекающим сроком действия в надстройке SharePoint.

Политики авторизации

Надстройку SharePoint можно разработать так, чтобы в ней использовалась одна из трех указанных ниже политик авторизации.

  • Политика "Только для пользователей". При использовании политики "Только для пользователей" SharePoint проверяет разрешения только для пользователя. SharePoint применяет эту политику, когда пользователь получает непосредственный доступ к ресурсам, не используя надстройку (например, если пользователь впервые открывает домашнюю страницу веб-сайта SharePoint или получает доступ к API SharePoint из PowerShell).

  • Политика "Только для надстроек". Надстройка, в которой используется эта политика, может выполнять любые действия, на которые у нее есть разрешения, даже если у пользователя нет таких разрешений. Разработчик должен запросить использование этой политики в манифесте надстройки. Пользователь, устанавливающий надстройку, должен утвердить этот запрос. Эту политику разрешено использовать только для надстроек SharePoint, размещаемых у поставщика.

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

Дополнительные сведения о политиках авторизации см. в статье Типы политик авторизации надстроек в SharePoint.

Два потока среды выполнения OAuth

Каждый раз, когда запускается надстройка SharePoint, размещаемая в облаке, или внешнее приложение, получающее доступ к SharePoint, возникает поток (или ряд взаимодействий между надстройкой, SharePoint, ACS и иногда пользователем). Конечный результат потока заключается в том, что SharePoint получает маркер доступа, включаемый в каждый запрос на создание, чтение, обновление и удаление данных (CRUD-запрос), который приложение отправляет в SharePoint.

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

  • Поток маркеров контекста. Удаленный компонент надстройки SharePoint использует клиентскую объектную модель (CSOM) SharePoint или конечные точки REST для выполнения вызовов SharePoint. Служба SharePoint запрашивает из ACS маркер контекста, который она сможет отправить удаленному серверу. Удаленный сервер использует маркер контекста для запрашивания маркера доступа из ACS. Затем удаленный сервер использует маркер доступа для связи с SharePoint.

    Дополнительные сведения об этом потоке см. в статье Поток OAuth маркера контекста для надстроек SharePoint.

  • Поток кода проверки подлинности. При установке надстройки SharePoint она получает разрешения, необходимые ей для доступа к ресурсам SharePoint. Приложения, не установленные в SharePoint, должны запрашивать разрешения "на лету", то есть при каждом запуске таких приложений. В этом потоке не используется маркер контекста SharePoint. Вместо этого, когда надстройка запускается и пытается получить доступ к SharePoint, SharePoint предлагает пользователю предоставить приложению разрешения, которые оно запрашивает. Когда пользователь предоставляет необходимые разрешения, SharePoint получает код авторизации из ACS, который затем передает приложению. Приложение использует этот код для получения из служб ACS маркера доступа, который оно затем может использовать для обмена данными с SharePoint.

    Сведения об этом потоке см. в статье Поток кода авторизации OAuth для надстроек SharePoint.

Устранение неполадок, связанных с надстройками SharePoint с низким уровнем доверия

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

Использование средства Fiddler

С помощью бесплатного средства Fiddler можно перехватывать HTTP-запросы, отправляемые удаленным компонентом надстройки в среду SharePoint. Существует бесплатное расширение для этого средства, которое автоматически декодирует маркеры доступа в запросах.

Отключение требования использовать протокол HTTPS для OAuth во время разработки

При использовании OAuth требуется, чтобы служба SharePoint применяла протокол HTTPS (т. е. не только ваша служба, но и SharePoint). Это может мешать при разработке надстройки. Например, при попытке вызвать SharePoint во время отладки надстройки вы можете получить сообщение 403 (Запрещено), так как на узле localhost, на котором работает ваша надстройка, нет поддержки SSL.

Вы можете отключить требование использовать протокол HTTPS во время разработки с помощью указанных ниже командлетов Windows PowerShell.

$serviceConfig = Get-SPSecurityTokenServiceConfig
$serviceConfig.AllowOAuthOverHttp = $true
$serviceConfig.Update()

Чтобы снова включить требование использовать протокол HTTPS, выполните указанные ниже командлеты Windows PowerShell.

$serviceConfig = Get-SPSecurityTokenServiceConfig
$serviceConfig.AllowOAuthOverHttp = $false
$serviceConfig.Update()

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

  • Домен надстройки, который указывают при регистрации надстройки SharePoint на странице AppRegNew.aspx или в службе "Панель мониторинга продаж".

  • Домен, в котором зарегистрирован сертификат безопасности удаленного веб-приложения.

  • Часть значения StartPage, относящаяся к домену, в файле AppManifest.xml.

  • Доменная часть URL-адресов всех приемников событий, указанных в файле AppManifest.xml.

В связи с этим учтите указанные ниже особенности.

  • Если удаленный компонент надстройки SharePoint использует порт, отличный от 443, необходимо явно включить этот порт в качестве части домена во всех четырех местах. Пример: contoso.com:3333. (Необходимо использовать протокол HTTPS, для которого по умолчанию используется порт 443.)

  • Если для своего удаленного веб-приложения вы создаете псевдоним DNS CNAME, укажите псевдоним CNAME для значения домена во всех четырех случаях. Например, если приложение размещено в contoso.cloudapp.net и вы создали для него CNAME contososoftware.com, используйте contososoftware.com в качестве домена.

  • Перед упаковкой надстройки необходимо жестко указать домен в значении StartPage (и во всех URL-адресах приемников событий) в файле AppManifest.xml. Если для упаковки надстройки вы используете мастер публикации в среде Visual Studio, вам будет предложено указать домен, и инструменты Visual Studio Office Developer Tools автоматически добавят домен в значение StartPage (вместо маркера ~remoteWebUrl, используемого во время отладки). Но если вы не используете мастер публикации или используете его, но ваше удаленное веб-приложение развернуто в Azure, необходимо вручную заменить маркер обозначением домена (и протокола). Пример: https://contososoftware.com или https://MyCloudVM:3333.

Ошибка "Базовое соединение закрыто: не удалось установить отношение доверия для безопасного канала SSL/TLS"

Такое сообщение возникает из-за проблемы со связью SSL, а не с OAuth. Убедитесь, что SharePoint доверяет сертификату, который вы используете, и что этот сертификат соответствует имени конечной точки.

Ошибки при использовании метода HTTP DAV для чтения файлов из SharePoint

HTTP DAV не работает с OAuth. Если вы используете клиентскую объектную модель (CSOM) SharePoint, то для чтения файла используйте указанный ниже код.

File f = clientContext.Web.GetFileByServerRelativeUrl( url);
ClientResult<Stream> r = f.OpenBinaryStream();
clientContext.ExecuteQuery();

См. также