Авторизация и роли в построителе API данных
Построитель API данных использует рабочий процесс авторизации на основе ролей. Роли назначается любой входящий запрос, прошедший проверку подлинности или не прошедший проверку подлинности. Роли могут быть системные роли или роли пользователей. Затем назначенная роль проверяется на соответствие определенным разрешениям , указанным в файле конфигурации , чтобы понять, какие действия, поля и политики доступны для этой роли в запрошенной сущности.
Роли
Роли задают контекст разрешений, в котором должен выполняться запрос. Для каждой сущности, определенной в конфигурации среды выполнения, можно определить набор ролей и связанных разрешений, определяющих способ доступа к сущности в конечных точках REST и GraphQL.
Построитель API данных оценивает запросы в контексте одной роли:
anonymous
значение , если маркер доступа не представлен.authenticated
при наличии допустимого маркера доступа.<CUSTOM_USER_ROLE>
если представлен допустимый маркер доступа иX-MS-API-ROLE
включен заголовок HTTP, указывающий роль пользователя, которая также включена в утверждение маркераroles
доступа.
Роли не являются аддитивными. Это означает, что пользователь, который является членом обеих Role1
ролей и Role2
не наследует разрешения, связанные с обеими ролями.
Системные роли
Системные роли — это встроенные роли, распознаваемые построителем API данных. Системная роль автоматически назначается запрашивателю независимо от членства в роли запрашивающего, указанного в маркерах доступа. Существует две системные роли: anonymous
и authenticated
.
Анонимная системная роль
Системная anonymous
роль назначается запросам, выполняемым пользователями без проверки подлинности. Определенные сущности конфигурации среды выполнения должны включать разрешения для anonymous
роли, если требуется доступ без проверки подлинности.
Пример
Следующая конфигурация среды выполнения построителя API данных демонстрирует явную настройку системной роли anonymous
для включения доступа на чтение к сущности Book:
"Book": {
"source": "books",
"permissions": [
{
"role": "anonymous",
"actions": [ "read" ]
}
]
}
Когда клиентское приложение отправляет запрос с доступом к сущности Book от имени пользователя, не прошли проверку подлинности, приложение не должно включать Authorization
заголовок HTTP.
Системная роль с проверкой подлинности
Системная authenticated
роль назначается запросам, выполняемым прошедшими проверку подлинности пользователями.
Пример
Следующая конфигурация среды выполнения построителя API данных демонстрирует явную настройку системной роли authenticated
для включения доступа на чтение к сущности Book:
"Book": {
"source": "books",
"permissions": [
{
"role": "authenticated",
"actions": [ "read" ]
}
]
}
Пользовательские роли
Роли пользователей — это несистемные роли, назначенные пользователям в поставщике удостоверений, заданном в конфигурации среды выполнения. Чтобы построитель API данных оценивал запрос в контексте роли пользователя, необходимо выполнить два требования:
- Маркер доступа, предоставленный клиентским приложением, должен содержать утверждения ролей, которые перечисляют членство пользователя в роли.
- Клиентское приложение должно включать заголовок
X-MS-API-ROLE
HTTP с запросами и задавать значение заголовка в качестве требуемой роли пользователя.
Пример оценки роли
В следующем примере показаны запросы, выполненные к сущности Book
, настроенной в конфигурации среды выполнения построителя api данных следующим образом:
"Book": {
"source": "books",
"permissions": [
{
"role": "anonymous",
"actions": [ "read" ]
},
{
"role": "authenticated",
"actions": [ "read" ]
},
{
"role": "author",
"actions": [ "read" ]
}
]
}
В Статические веб-приложения пользователь по умолчанию является членом анонимной роли. Если пользователь прошел проверку подлинности, он является членом anonymous
ролей и authenticated
.
Когда клиентское приложение отправляет аутентифицированный запрос в построитель API данных, развернутый с помощью Статические веб-приложения подключения к базе данных (предварительная версия), клиентское приложение предоставляет маркер доступа, который Статические веб-приложения преобразуется в JSON:
{
"identityProvider": "azuread",
"userId": "d75b260a64504067bfc5b2905e3b8182",
"userDetails": "username",
"userRoles": ["anonymous", "authenticated", "author"]
}
Поскольку построитель API данных оценивает запросы в контексте одной роли, он оценивает запрос в контексте системной роли authenticated
по умолчанию.
Если запрос клиентского приложения также содержит заголовок X-MS-API-ROLE
HTTP со значением author
, запрос вычисляется в контексте author
роли. Пример запроса, включающий маркер доступа и X-MS-API-ROLE
заголовок HTTP:
curl -k -r GET -H 'Authorization: Bearer ey...' -H 'X-MS-API-ROLE: author' https://localhost:5001/api/Book
Важно!
Запрос клиентского приложения отклоняется, если утверждение предоставленного маркера roles
доступа не содержит роли, указанной в заголовке X-MS-API-ROLE
.
Разрешения
Разрешения описывают:
- Кто может выполнять запросы к сущности на основе членства в роли?
- Какие действия (создание, чтение, обновление, удаление, выполнение) может выполнять пользователь?
- Какие поля доступны для определенного действия?
- Какие дополнительные ограничения существуют на результаты, возвращаемые запросом?
Синтаксис для определения разрешений описан в статье о конфигурации среды выполнения.
Важно!
В конфигурации разрешений одной сущности может быть определено несколько ролей. Однако запрос оценивается только в контексте одной роли:
- По умолчанию системная роль
anonymous
илиauthenticated
- Если этот параметр включен, роль, заданная в заголовке
X-MS-API-ROLE
HTTP.
Обеспечение безопасности по умолчанию
По умолчанию сущность не имеет настроенных разрешений, что означает, что никто не может получить доступ к сущности. Кроме того, построитель API данных игнорирует объекты базы данных, если на них нет ссылок в конфигурации среды выполнения.
Разрешения должны быть явно настроены
Чтобы разрешить доступ к сущности без проверки подлинности, anonymous
роль должна быть явно определена в разрешениях сущности. Например, разрешения сущности book
явно заданы, чтобы разрешить доступ на чтение без проверки подлинности:
"book": {
"source": "dbo.books",
"permissions": [{
"role": "anonymous",
"actions": [ "read" ]
}]
}
Чтобы упростить определение разрешений для сущности, предположим, что если для роли нет конкретных authenticated
разрешений, используются разрешения, определенные для anonymous
роли. Показанная book
ранее конфигурация позволяет любому анонимному или прошедшему проверку подлинности пользователям выполнять операции чтения с сущностью book
.
Если операции чтения должны быть ограничены только пользователями, прошедшими проверку подлинности, следует задать следующую конфигурацию разрешений, что приведет к отклонению запросов, не прошедших проверку подлинности:
"book": {
"source": "dbo.books",
"permissions": [{
"role": "authenticated",
"actions": [ "read" ]
}]
}
Сущности не требуются и не настроены разрешения для anonymous
ролей и authenticated
. В конфигурации разрешений сущности можно определить одну или несколько ролей пользователей, а всем другим неопределенным ролям, системным или пользовательским ролям автоматически отказано в доступе.
В следующем примере роль administrator
пользователя является единственной определенной ролью для сущности book
. Пользователь должен быть членом administrator
роли и включить ее в X-MS-API-ROLE
заголовок HTTP для работы с сущностью book
:
"book": {
"source": "dbo.books",
"permissions": [{
"role": "administrator",
"actions": [ "*" ]
}]
}
Примечание
Чтобы применить управление доступом для запросов GraphQL при использовании конструктора API данных с Azure Cosmos DB, необходимо использовать директиву @authorize
в предоставленном файле схемы GraphQL.
Однако для GraphQL изменений и фильтров в запросах GraphQL управление доступом по-прежнему обеспечивается конфигурацией разрешений, как описано выше.
Действия
Действия описывают специальные возможности сущности в область роли. Действия можно указать по отдельности или с помощью ярлыка с подстановочным знаком: *
(звездочка). Ярлык с подстановочным знаком представляет все действия, поддерживаемые для типа сущности:
- Таблицы и представления:
create
,read
,update
,delete
- Хранимые процедуры:
execute
Дополнительные сведения о действиях см. в документации по файлу конфигурации .
Доступ к полю
Вы можете настроить поля, которые должны быть доступны для действия. Например, можно задать поля для включения и исключения из read
действия.
В следующем примере пользователи в free-access
роли не могут выполнять операции чтения с Column3
. Column3
Ссылки на в запросах GET (конечная точка REST) или запросах (конечная точка GraphQL) приводят к отклонению запроса:
"book": {
"source": "dbo.books",
"permissions": [
{
"role": "free-access",
"actions": [
"create",
"update",
"delete",
{
"action": "read",
"fields": {
"include": [ "Column1", "Column2" ],
"exclude": [ "Column3" ]
}
}
]
}
]
}
Примечание
Чтобы применить управление доступом для запросов GraphQL при использовании конструктора API данных с Azure Cosmos DB, необходимо использовать директиву @authorize
в предоставленном файле схемы GraphQL. Однако для GraphQL изменений и фильтров в запросах GraphQL управление доступом по-прежнему обеспечивается конфигурацией разрешений, как описано здесь.
Безопасность на уровне элементов
Выражения политики базы данных позволяют еще больше ограничивать результаты. Политики базы данных преобразуют выражения в предикаты запросов, выполняемые в базе данных. Выражения политики базы данных поддерживаются для следующих действий:
- create
- read
- обновить
- удалить
Предупреждение
Действие выполнения , используемое с хранимыми процедурами, не поддерживает политики базы данных.
Примечание
Политики базы данных в настоящее время не поддерживаются CosmosDB для NoSQL.
Дополнительные сведения о политиках базы данных см. в документации по файлам конфигурации .
Пример
Политика базы данных, ограничивающая read
действие в consumer
роли только для тех записей, в которых заголовок — "Sample Title".
{
"role": "consumer",
"actions": [
{
"action": "read",
"policy": {
"database": "@item.title eq 'Sample Title'"
}
}
]
}