Имитация API CRUD, защищенного с помощью Microsoft Entra

Статья
06/18/2024

При создании приложений часто взаимодействуют с внутренними API. Иногда эти API еще недоступны или другие команды обновляют их в соответствии с последними требованиями. Чтобы избежать ожидания, обычно создается макет API, который возвращает необходимые данные. Хотя этот подход разблокирует вас, это требует времени для создания API, который вы в конечном итоге заменяете реальным. Это становится еще более сложным, когда необходимо защитить API с помощью Microsoft Entra. Чтобы избежать тратить время, можно использовать прокси разработки для имитации API CRUD и ускорения разработки.

CrudApiPluginС помощью api CRUD (создание, чтение, обновление, удаление) можно имитировать с помощью хранилища данных в памяти. С помощью простого файла конфигурации можно определить URL-адреса, поддерживаемые API макета и возвращаемые им данные. Подключаемый модуль также поддерживает CORS для использования между доменами из клиентских приложений. Подключаемый модуль также поддерживает проверку подлинности Microsoft Entra, поэтому вы можете защитить api макета с помощью Microsoft Entra и реализовать тот же поток проверки подлинности для приложения, что и в рабочей среде.

Сценарий

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

Подготовка к работе

Сначала создайте имитированный API CRUD с данными клиента. Убедившись, что API работает, его можно защитить с помощью Microsoft Entra.

Пример 1. Имитация API CRUD, защищенного с помощью Microsoft Entra, с помощью одной области

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

customers-api.json В файле добавьте сведения о Entra.

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/crudapiplugin.schema.json",
  "baseUrl": "https://api.contoso.com/v1/customers",
  "dataFile": "customers-data.json",
  "auth": "entra",
  "entraAuthConfig": {
    "audience": "https://api.contoso.com",
    "issuer": "https://login.microsoftonline.com/contoso.com",
    "scopes": ["api://contoso.com/user_impersonation"]
  },
  "actions": [
    {
      "action": "getAll"
    },
    {
      "action": "getOne",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "create"
    },
    {
      "action": "merge",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "delete",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    }
  ]
}

Задав свойствоentra, которое необходимо указатьauth, что API защищен с помощью Microsoft Entra. В свойстве entraAuthConfig укажите сведения о конфигурации. Свойство audience указывает аудиторию API, issuer свойство указывает издателя маркеров, а scopes свойство задает области, необходимые для доступа к API. Так как вы определяете scopes на корневом уровне файла API, все действия требуют той же области.

Если вы пытаетесь вызвать API без маркера с указанной аудиторией, издателем и областями, вы получите 401 Unauthorized ответ.

Примечание.

На этом этапе прокси-сервер разработки не проверяет маркер. Он проверяет, присутствует ли маркер и имеет необходимую аудиторию, издателя и области. Это удобно во время ранней разработки, если у вас еще нет реальной регистрации приложений Microsoft Entra и не удается получить реальный токен.

Пример 2. Имитация API CRUD, защищенного с помощью Microsoft Entra, с помощью различных областей для различных действий

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

customers-api.json Обновите файл следующим образом:

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/crudapiplugin.schema.json",
  "baseUrl": "https://api.contoso.com/v1/customers",
  "dataFile": "customers-data.json",
  "auth": "entra",
  "entraAuthConfig": {
    "audience": "https://api.contoso.com",
    "issuer": "https://login.microsoftonline.com/contoso.com"
  },
  "actions": [
    {
      "action": "getAll",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.read"]
      }
    },
    {
      "action": "getOne",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.read"]
      }
    },
    {
      "action": "create",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.write"]
      }
    },
    {
      "action": "merge",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.write"]
      }
    },
    {
      "action": "delete",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.write"]
      }
    }
  ]
}

На этот раз вы не указываете scopes корневой уровень файла API. Вместо этого вы указываете их для каждого действия. Таким образом, вы можете защитить различные действия с различными областями. Например, получение сведений о клиентах требует api://contoso.com/customer.read области, при обновлении клиентов требуется api://contoso.com/customer.write область.

Проверка маркеров

Прокси-сервер разработки позволяет имитировать API CRUD, защищенный с помощью Microsoft Entra, и проверить, используете ли вы допустимый маркер. Проверка маркера удобна, если у вас есть регистрация приложения в Microsoft Entra, но команда по-прежнему создает API. Это позволяет более точно протестировать приложение.

Если требуется, чтобы прокси-сервер разработки проверял маркер доступа, добавьте entraAuthConfig validateSigningKey свойство и задайте для него значение true:

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/crudapiplugin.schema.json",
  "baseUrl": "https://api.contoso.com/v1/customers",
  "dataFile": "customers-data.json",
  "auth": "entra",
  "entraAuthConfig": {
    "audience": "https://api.contoso.com",
    "issuer": "https://login.microsoftonline.com/contoso.com",
    "scopes": ["api://contoso.com/user_impersonation"],
    "validateSigningKey": true
  },
  "actions": [
    {
      "action": "getAll"
    },
    {
      "action": "getOne",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "create"
    },
    {
      "action": "merge",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "delete",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    }
  ]
}

Если вы попытаетесь вызвать API с самоделанным маркером, вы получите 401 Unauthorized ответ. Прокси-сервер разработки разрешает только запросы с допустимым маркером, выданным Microsoft Entra.

Следующий шаг

Дополнительные сведения о CrudApiPlugin.

CrudApiPlugin

Примеры

См. также связанные примеры прокси-сервера разработки:

API CRUD с данными базы данных Northwind

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