Авторизация и роли в построителе 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 данных оценивал запрос в контексте роли пользователя, необходимо выполнить два требования:

1. Маркер доступа, предоставленный клиентским приложением, должен содержать утверждения ролей, которые перечисляют членство пользователя в роли.
2. Клиентское приложение должно включать заголовок 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

Разрешения

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

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

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

Обеспечение безопасности по умолчанию

По умолчанию сущность не имеет настроенных разрешений, что означает, что никто не может получить доступ к сущности. Кроме того, построитель 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": [ "*" ]
  }]
}

Действия

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

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

Безопасность на уровне элементов

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

Дополнительные сведения о политиках базы данных см. в документации по файлам конфигурации .

Пример

Политика базы данных, ограничивающая read действие в consumer роли только для тех записей, в которых заголовок — "Sample Title".

{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.title eq 'Sample Title'"
      }
    }
  ]
}

См. также

• Проверка подлинности Azure
• Локальная проверка подлинности