模擬使用 Microsoft Entra 保護的 CRUD API

發行項
06/18/2024

建置應用程式時，您通常會與後端 API 互動。有時候，這些 API 尚無法使用，或其他小組正在更新它們以符合最新的需求。為了避免等候，您通常會建立模擬 API 來傳回您需要的數據。雖然此方法會解除封鎖您，但您需要花時間建置最終取代為實際 API 的 API。當您需要使用 Microsoft Entra 來保護 API 時，它變得更加複雜。若要避免浪費時間，您可以使用開發 Proxy 來模擬 CRUD API 並加速開發。

CrudApiPlugin使用，您可以使用記憶體內部資料存放區來模擬 CRUD （建立、讀取、更新、刪除） API。使用簡單的組態檔，您可以定義模擬 API 支援的 URL 及其傳回的數據。外掛程式也支援從用戶端應用程式使用跨網域的CORS。外掛程式也支援 Microsoft Entra 驗證，因此您可以使用 Microsoft Entra 來保護模擬 API，並為應用程式實作與生產環境中相同的驗證流程。

案例

例如，您正在建置可讓使用者管理客戶的應用程式。若要取得數據，您必須呼叫 /customers 後端 API 的端點。 API 受到Microsoft Entra 保護。為了避免等待後端小組完成其工作，您決定使用開發 Proxy 來模擬 API 並傳回您需要的數據。

開始之前

您一開始會使用客戶數據建立模擬 CRUD API。確認 API 運作之後，您可以使用 Microsoft Entra 來保護它。

範例 1：使用單一範圍模擬使用 Microsoft Entra 保護的 CRUD API

在第一個範例中，您會使用單一範圍保護整個 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})]"
    }
  ]
}

藉由將 auth 屬性設定為您 entra 指定，API 會受到Microsoft Entra 保護。在屬性中 entraAuthConfig ，您可以指定組態詳細數據。屬性 audience 會指定 API 的物件、 issuer 屬性指定令牌的簽發者，而 scopes 屬性會指定存取 API 所需的範圍。因為您在 API 檔案的根層級定義 scopes ，因此所有動作都需要相同的範圍。

如果您嘗試在沒有具有指定對象、簽發者和範圍的令牌的情況下呼叫 API，您會收到 401 Unauthorized 回應。

注意

在此階段，開發 Proxy 不會驗證令牌。它只會檢查令牌是否存在，而且具有必要的對象、簽發者和範圍。這在早期開發期間很方便，當您還沒有真正的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 範圍。

驗證令牌

開發 Proxy 可讓您模擬使用 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 回應。開發 Proxy 只允許具有由 Microsoft Entra 簽發之有效令牌的要求。

後續步驟

深入瞭解 CrudApiPlugin。

CrudApiPlugin

範例

另請參閱相關的開發 Proxy 範例：

使用 Northwind 資料庫數據的 CRUD API

共用方式為