Типы политик авторизации надстроек в SharePoint

  • Статья

Прежде чем изучать эту статью, ознакомьтесь со статьями Разрешения надстроек в SharePoint и Поток OAuth маркера контекста для надстроек SharePoint.

Общие сведения о типах политик авторизации надстроек

В SharePoint есть три указанных ниже типа политик авторизации.

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

    Надстройка для утверждения расходов — это пример надстройки, разработанной для использования этой политики. Надстройка позволяет пользователям (у которых в ином случае не было бы возможности утверждать расходы) утверждать расходы в рамках определенной суммы. Пример см. в сценарии в следующем разделе.

    Примечание.

    Для определенных API требуется контекст пользователя, и их невозможно выполнить при использовании политики "Только для надстроек". Среди них много API, предназначенных для взаимодействия с Project Server и Project Online, а также для выполнения поисковых запросов.

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

  • Политика "Для пользователей и надстроек" При использовании политики "Для пользователей и надстроек" SharePoint проверяет разрешения и для пользователя, и для субъекта надстройки. Проверки авторизации выполняются успешно, только если и у текущего пользователя, и у надстройки есть разрешения на выполнение необходимого действия.

    Например, эта политика используется, когда надстройке SharePoint необходимо получить доступ к ресурсам пользователя в SharePoint. (Код в удаленных компонентах надстройки SharePoint необходимо разработать так, чтобы он выполнял вызовы SharePoint согласно политике "Для пользователей и надстроек".)

Пример сценария надстройки, в котором используется политика "Только для надстроек".

Предположим, что Илья, менеджер по продажам в компании Contoso, приобретает надстройку для отправки сведений о расходах, в которой используется политика "Только для надстроек". Когда Илья решит приобрести надстройку, ему будет предложено разрешить надстройке повысить уровень разрешений пользователя, то есть разрешить надстройке выполнять вызовы SharePoint согласно политике "Только для надстроек". Илья предоставляет требуемые разрешения надстройке. Затем он приобретает необходимое количество лицензий на надстройку для всех сотрудников отдела продаж компании Contoso и устанавливает надстройку на веб-сайте SharePoint группы отдела продаж.

Вскоре сотрудники отдела продаж начинают отправлять отчеты о расходах с помощью новой надстройки. Обычно у сотрудников отдела продаж нет полномочий утверждать свои отчеты о расходах, но они могут делать это, когда используют надстройку, так как Илья предоставил надстройке возможность автоматически утверждать отчеты суммой менее 50 долларов США. Надстройка автоматически назначает Илье задачи утверждения отчетов на суммы от 50 долларов США.

Это можно реализовать, предоставив надстройке SharePoint разрешение Write для списка утвержденных расходов в SharePoint. Но среди пользователей разрешение Write для списка есть только у менеджеров отдела кадров. Код в надстройке разработан так, чтобы добавлять сведения о расходах в список путем выполнения вызовов SharePoint согласно политике "Только для надстроек" в случаях, когда сумма расходов меньше 50 долларов США. Так как разрешения пользователя не проверяются, любые отправленные пользователями отчеты на суммы менее 50 долларов США автоматически добавляются в список утвержденных расходов, даже если у пользователя нет разрешения Write для списка.

Сведения о том, как надстройки получают разрешение на использование политики "Только для надстроек"

Чтобы иметь возможность выполнять вызовы только для надстроек в SharePoint, надстройка должна запросить разрешение на использование политики только надстроек. Этот запрос выполняется в манифесте надстройки. Для этого добавьте атрибут AllowAppOnlyPolicy в элемент AppPermissionRequests и задав для него значение true , как показано в следующей разметке:

    <AppPermissionRequests AllowAppOnlyPolicy="true">
        ...
    </AppPermissionRequests>

Примечание.

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

Пользователю, устанавливающему надстройку, будет предложено утвердить этот запрос. Если надстройка просит разрешения уровня клиента, только администратор клиента может разрешить использовать политику "Только для надстроек", соответственно, только администратор клиента может установить такую надстройку.

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

Сведения о том, как надстройки выполняют вызовы согласно политике "Только для надстроек"

Различие между вызовом к SharePoint только для надстроек и вызовом для пользователей и надстроек заключается в типе маркера доступа, который включен в вызов. В примере кода ниже показано, как создать и получить маркеры доступа для пользователей и надстроек и маркеры доступа только для надстроек в управляемом коде. Готовый код представлен в файле TokenHelper.cs (или с расширением VB), который Инструменты разработчика Office для Visual Studio автоматически добавляет в проект надстройки SharePoint в Visual Studio.

    string contextTokenString = TokenHelper.GetContextTokenFromRequest(Request);
    if (contextTokenString != null)
    {
        //Get context token.
        SharePointContextToken contextToken =
            TokenHelper.ReadAndValidateContextToken(contextTokenString, Request.Url.Authority);
        Uri sharepointUrl = new Uri(Request.QueryString["SPHostUrl"]);

        //Get user+add-in access token.
        string accessToken =
            TokenHelper.GetAccessToken(contextToken, sharepointUrl.Authority).AccessToken;

        ClientContext clientContext =
            TokenHelper.GetClientContextWithAccessToken(sharepointUrl.ToString(), accessToken);

        //Do something. 
        ...
        
        //Get add-in-only access token.
        string addinOnlyAccessToken = 
                TokenHelper.GetAppOnlyAccessToken(contextToken.TargetPrincipalName, 
                                sharepointUrl.Authority, contextToken.Realm).AccessToken;
            //Do something.
            ...
    }

Примечание.

Надстройки, которые не совершают вызовов, прошедших проверку подлинности OAuth (например, надстройки, которые выполняют только код JavaScript на сайте надстройки), не могут использовать политику "Только для надстроек". Они могут запросить необходимое разрешение, но они не смогут использовать его, так как для этого требуется передать маркер OAuth "Только для надстроек". Только надстройки с веб-приложениями, выполняющимися за пределами SharePoint, могут создавать маркеры "Только для надстроек" и передавать их.

В общем случае для вызова требуется присутствие текущего пользователя. При использовании политики "Только для надстроек" SharePoint создает пользователя SHAREPOINT\APP, аналогичного существующему пользователю SHAREPOINT\SYSTEM. Все запросы "Только для надстроек" выполняет пользователь SHAREPOINT\APP. Невозможно пройти проверку подлинности в качестве пользователя SHAREPOINT\APP при проверке подлинности для пользователей.

Рекомендации по использованию политики "Только для надстроек"

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

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

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

См. также