Microsoft Entra でセキュリティ保護された CRUD API をシミュレートする

[アーティクル]
11/23/2024

アプリをビルドするときは、多くの場合、バックエンド API と対話します。これらの API がまだ利用できない場合や、他のチームが最新の要件を満たすように API を更新している場合があります。待機を回避するには、通常、必要なデータを返すモック API を作成します。この方法ではブロックが解除されますが、最終的に実際の API に置き換える API の構築に時間を費やす必要があります。 Microsoft Entra を使用して API をセキュリティで保護する必要がある場合は、さらに複雑になります。時間の無駄を避けるために、開発プロキシを使用して CRUD API をシミュレートし、開発を高速化できます。

CrudApiPluginを使用すると、メモリ内データストアを使用して CRUD (作成、読み取り、更新、削除) API をできます。単純な構成ファイルを使用して、モック API でサポートされる URL と返されるデータを定義できます。このプラグインでは、クライアント側アプリケーションからのクロスドメイン使用に対する CORS もサポートされています。このプラグインは Microsoft Entra 認証もサポートしているため、Microsoft Entra でモック API をセキュリティで保護し、運用環境と同じ認証フローをアプリに実装できます。

シナリオ

たとえば、ユーザーが顧客を管理できるアプリを構築しているとします。データを取得するには、バックエンド API の /customers エンドポイントを呼び出す必要があります。 API は Microsoft Entra で保護されています。バックエンドチームが作業を完了するのを待つのを避けるために、開発プロキシを使用して API をシミュレートし、必要なデータを返します。

開始する前に

まず、顧客データを使用してシミュレートされた CRUD API をします。 API が動作することを確認したら、Microsoft Entra で保護できます。

例 1: 1 つのスコープを使用して Microsoft Entra でセキュリティ保護された CRUD API をシミュレートする

最初の例では、1 つのスコープで 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 にアクセスするために必要なスコープを指定します。 API ファイルのルートレベルで scopes を定義するため、すべてのアクションに同じスコープが必要です。

対象ユーザー、発行者、スコープを指定してトークンなしで API を呼び出そうとすると、 401 Unauthorized 応答が返されます。

Note

この段階では、開発プロキシはトークンを検証しません。トークンが存在し、必要な対象ユーザー、発行者、スコープがあるかどうかを確認するだけです。これは、実際の Microsoft Entra アプリの登録がまだがなく、実際のトークンを取得できない場合に、初期の開発中に便利です。

例 2: さまざまなアクションに対して異なるスコープを使用して、Microsoft Entra でセキュリティ保護された CRUD API をシミュレートする

多くの場合、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"]
      }
    }
  ]
}

今回は、API ファイルのルートレベルで scopes を指定しません。代わりに、アクションごとに指定します。これにより、スコープが異なるさまざまなアクションをセキュリティで保護できます。たとえば、顧客に関する情報を取得するには api://contoso.com/customer.read スコープが必要ですが、顧客を更新するには api://contoso.com/customer.write スコープが必要です。

トークンを検証する

開発プロキシを使用すると、Microsoft Entra でセキュリティ保護された CRUD API をシミュレートし、有効なトークンを使用していることを確認できます。トークンの検証は、Microsoft Entra でアプリを登録しているが、チームがまだ API を構築している場合に便利です。これにより、アプリをより正確にテストできます。

Dev Proxy でアクセストークンを検証する場合は、 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

サンプル

関連する開発プロキシのサンプルも参照してください。

Northwind データベースデータを含む CRUD API

次の方法で共有