Обзор авторизации

Авторизация определяет, что пользователи, прошедшие проверку подлинности, могут делать в вашем приложении для создания API данных. Хотя проверка подлинности подтверждает, кем является пользователь, авторизация контролирует что они могут получить доступ и изменить.

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

Основные понятия авторизации ключей

Разрешения сущности

Управление операциями CRUD (создание, чтение, обновление, удаление) на уровне сущности. Каждой роли может быть предоставлена или отказана возможность выполнять конкретные действия с определёнными сущностями.

Управление доступом на основе ролей

Назначьте пользователей на роли и предоставьте права в зависимости от членства в роли. Роли упрощают управление большими группами пользователей с аналогичными шаблонами доступа.

Безопасность на уровне строк (RLS)

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

Политики API

Примените предикаты И фильтры OData к ответам API. Политики автоматически ограничивают результаты запросов на основе утверждений пользователей и удостоверений.

Авторизация на основе утверждений

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

Принцип работы

1. Пользователь проходит проверку подлинности с помощью одного из поддерживаемых методов проверки подлинности.
2. Система извлекает утверждения из маркера проверки подлинности (роли, группы, организация и т. д.)
3. Правила авторизации оцениваются по утверждениям пользователя и запрошенным ресурсом
4. Доступ предоставляется или запрещается на основе разрешений сущностей, политик и правил безопасности на уровне строк

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

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

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

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

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

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

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

Системные роли являются встроенными ролями, распознаваемыми построителем 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

Разрешения

Разрешения описывают:

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

Синтаксис определения разрешений описан в статье конфигурации среды выполнения.

Безопасность по умолчанию

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

Действия

Действия описывают доступность сущности в рамках роли. Действия можно указать по отдельности или с помощью ярлыка подстановочного знака: * (звездочка). Ярлык подстановочного знака представляет все действия, поддерживаемые для типа сущности:

• Таблицы и представления: 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" ]
              }
            }
          ]
        }
      ]
    }

Политики базы данных (безопасность на уровне элементов)

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

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

Быстрый пример

{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.ownerId eq @claims.userId"
      }
    }
  ]
}

Наследование ролей

DAB 2.0 представляет наследование ролей, поэтому вам не нужно повторять один блок разрешений для каждой роли. Цепочка наследования:

named-role → authenticated → anonymous

• Если authenticated не настроен явно для сущности, она наследует его от anonymous.
• Если именованная роль не настроена, она наследуется от authenticated, или от anonymous, если authenticated также отсутствует.

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

{
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] }
      ]
    }
  }
}

С помощью этой конфигурации anonymous, authenticated и любая ненастроенная именованная роль могут читать Book.

Используется dab configure --show-effective-permissions для отображения разрешенных разрешений для каждой сущности после применения наследования.

Разрешения должны быть явно настроены

Чтобы разрешить доступ к сущности без проверки подлинности, Anonymous роль должна быть явно определена в разрешениях сущности. Например, разрешения сущности book явно настроены для предоставления доступа на чтение без проверки подлинности.

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "Anonymous",
    "actions": [ "read" ]
  }]
}

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

"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": [ "*" ]
  }]
}

Многоуровневая модель безопасности

Построитель данных использует несколько уровней авторизации:

• Уровень сущности: какие сущности и операции доступны
• Уровень политики: какие данные возвращаются (фильтрация на основе утверждений)
• Уровень строки. База данных применяет фильтрацию строк через RLS
• Уровень API: заголовки HTTP и проверка запросов

Дальнейшие действия

• Наследование ролей — построение иерархий ролей
• Политики API— применение фильтров OData на основе утверждений
• Безопасность на уровне строк— фильтрация данных на уровне базы данных
• Рекомендации по обеспечению безопасности