Поделиться через

Авторизация и роли в построителе API данных

Конструктор API данных использует рабочий процесс авторизации на основе ролей. Любой входящий запрос, прошедший проверку подлинности или нет, назначается роли. Роли могут быть системным ролями или ролями пользователей. Затем назначенная роль проверяется на соответствие определенным разрешениям , указанным в конфигурации, чтобы понять, какие действия, поля и политики доступны для этой роли в запрошенной сущности.

Иллюстрация того, как построитель api данных выбирает роль и оценивает разрешения для запроса.

Определение роли пользователя

Роль не имеет разрешений по умолчанию. После того как построитель API данных определяет роль, сущность permissions должна определить actions для успешного выполнения запроса.

Следующая матрица оценки ролей применяется к поставщикам токенов JWT (например, EntraID/AzureAD и Custom), где клиент отправляет Authorization: Bearer <token>.

Предоставленный маркер носителя X-MS-API-ROLE предоставлено Запрошенная роль, указанная в утверждении токена roles Эффективная роль или результат
нет нет N/A Anonymous
Да (допустимо) нет N/A Authenticated
Да (допустимо) Да нет Отклонено (403 Запрещено)
Да (допустимо) Да Да Значение X-MS-API-ROLE
Да (недопустимо) Любое N/A Отклонено (401 Несанкционированное)

Для использования другой роли, нежели Anonymous или Authenticated, требуется заголовок X-MS-API-ROLE.

Замечание

Запрос может быть связан с множеством ролей в аутентифицированном субъекте. Однако построитель API данных оценивает разрешения и политики в контексте ровно одной эффективной роли. При указании X-MS-API-ROLE заголовок выбирает, какая роль используется.

Примечания поставщика:

  • Поставщики EasyAuth (например, AppService): проверку подлинности можно установить с помощью заголовков, внедренных платформой (таких как X-MS-CLIENT-PRINCIPAL), а не с помощью маркера носителя.
  • Simulator: запросы обрабатываются как прошедшие проверку подлинности для разработки и тестирования без проверки реального токена.

Системные роли

Системные роли являются встроенными ролями, распознаваемыми построителем API данных. Системная роль автоматически назначается запрашивателю независимо от членства в роли, указанного в его жетонах доступа. Существует две системные роли: Anonymous и Authenticated.

Анонимная системная роль

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

Пример

Следующая конфигурация среды выполнения построителя данных демонстрирует явную настройку системной роли Anonymous для включения доступа на чтение к сущности Book:

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "Anonymous",
            "actions": [ "read" ]
        }
    ]
}

Когда клиентское приложение отправляет запрос на доступ к сущности Book от имени неавторентированного пользователя, приложение не должно включать Authorization заголовок HTTP.

Роль системы с проверкой подлинности

Системная Authenticated роль назначается запросам, выполняемым прошедшими проверку подлинности пользователями.

Пример

Следующая конфигурация среды выполнения построителя данных демонстрирует явную настройку системной роли Authenticated для включения доступа на чтение к сущности Book:

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "Authenticated",
            "actions": [ "read" ]
        }
    ]
}

Роли пользователя

Роли пользователей — это несистемные роли, назначенные пользователям в поставщике удостоверений, заданном в конфигурации среды выполнения. Чтобы построитель API данных оценил запрос в контексте роли пользователя, необходимо выполнить два требования:

  1. Субъект, прошедший проверку подлинности, должен включать утверждения роли, которые перечисляют членство пользователя в роли (например, утверждение JWT roles ).
  2. Клиентское приложение должно включать заголовок HTTP с запросами и задать значение заголовка X-MS-API-ROLE в качестве требуемой роли пользователя.

Пример оценки ролей

В следующем примере показаны запросы Book к сущности, настроенной в конфигурации среды выполнения построителя данных, следующим образом:

"Book": {
    "source": "books",
    "permissions": [
        {
      "role": "Anonymous",
            "actions": [ "read" ]
        },
        {
      "role": "Authenticated",
            "actions": [ "read" ]
        },
        {
            "role": "author",
            "actions": [ "read" ]
        }
    ]
}

Конструктор API данных оценивает запросы в контексте одной активной роли. Если запрос прошел проверку подлинности и заголовок X-MS-API-ROLE не указан, Data API builder оценивает запрос в контексте системной роли Authenticated по умолчанию.

Если запрос клиентского приложения также содержит заголовок X-MS-API-ROLE HTTP со значением author, запрос вычисляется в контексте author роли. Пример запроса, включая маркер доступа и X-MS-API-ROLE заголовок HTTP:

curl -k -X 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" ]
  }]
}

Если вы хотите предоставить доступ пользователям с проверкой подлинности и без неё, необходимо явно предоставить разрешения для обеих системных ролей (Anonymous и Authenticated).

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

"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 конфигурация разрешений по-прежнему применяет управление доступом, как описано здесь.

Уровень безопасности элементов

Политики базы данных позволяют фильтровать результаты на уровне строки. Политики преобразовываются в предикаты запросов, которые вычисляет база данных, обеспечивая пользователям доступ только к авторизованным записям.

Поддерживаемые действия Не поддерживается
read update delete create, execute

Замечание

Azure Cosmos DB для NoSQL в настоящее время не поддерживает политики базы данных.

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

Быстрый пример
{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.ownerId eq @claims.userId"
      }
    }
  ]
}

Связанный контент

  • Last updated on