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

2025-07-17

При создании приложений часто взаимодействуют с внутренними 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: Моделирование защищенного с использованием Microsoft Entra CRUD API с одной областью действия.

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

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

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v1.0.0/crudapiplugin.apifile.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})]"
    }
  ]
}

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

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

Примечание.

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

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

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

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

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v1.0.0/crudapiplugin.apifile.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. Это позволяет более точно протестировать приложение.

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

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v1.0.0/crudapiplugin.apifile.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