ApiCenterMinimalPermissionsPlugin

發行項
06/07/2024

檢查應用程式是否使用最少的許可權來呼叫 API。使用來自指定 Azure API 中心實例的 API 資訊。

外掛程式實例定義

{
  "name": "ApiCenterMinimalPermissionsPlugin",
  "enabled": true,
  "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
  "configSection": "apiCenterMinimalPermissionsPlugin"
}

設定範例

{
  "apiCenterMinimalPermissionsPlugin": {
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "resource-group-name",
    "serviceName": "apic-instance",
    "workspaceName": "default"
  }
}

設定屬性

屬性	說明	預設
`resourceGroupName`	Azure API 中心所在的資源群組名稱。	無
`serviceName`	開發 Proxy 應該用來檢查應用程式中使用的 API 是否已註冊的 Azure API 中心實例名稱。	無
`subscriptionId`	Azure API 中心實例所在的 Azure 訂用帳戶標識碼。	無
`workspace`	要使用的 Azure API 中心工作區名稱。	`default`

命令列選項

None

備註

外掛程式 ApiCenterMinimalPermissionsPlugin 會檢查應用程式是否使用最少的許可權來呼叫 API。若要檢查許可權，外掛程式會使用在指定的 Azure API 中心實例中註冊的 API 相關信息。

連線到 Azure API 中心

若要連線到 Azure API 中心，外掛程式會使用 Azure 認證（依此順序）：

Environment
工作負載身分識別
受控識別
Visual Studio
Visual Studio Code
Azure CLI
Azure PowerShell
Azure Developer CLI

如果外掛程式無法取得存取令牌來存取 Azure，它會顯示錯誤，而開發人員 Proxy 會停用它。使用這些工具之一登入 Azure，然後重新啟動 Dev Proxy 以使用 ApiCenterMinimalPermissionsPlugin 外掛程式。

如果您在 CI/CD 管線中使用開發 Proxy，您可以將、resourceGroupName、 serviceName和 workspaceName 屬性的值subscriptionId當做環境變數傳遞。若要使用環境變數，請使用前面加上值 @的名稱，例如：

{
  "apiCenterMinimalPermissionsPlugin": {
    "subscriptionId": "@AZURE_SUBSCRIPTION_ID",
    "resourceGroupName": "@AZURE_RESOURCE_GROUP_NAME",
    "serviceName": "@AZURE_APIC_INSTANCE_NAME",
    "workspaceName": "@AZURE_APIC_WORKSPACE_NAME"
  }
}

在這裡範例中，外掛程式會將、、和屬性分別設定subscriptionId為、AZURE_RESOURCE_GROUP_NAME、 AZURE_APIC_INSTANCE_NAME和 AZURE_APIC_WORKSPACE_NAME 環境變數的值AZURE_SUBSCRIPTION_ID。workspaceName serviceNameresourceGroupNameApiCenterMinimalPermissionsPlugin

定義 API 許可權

外掛程式 ApiCenterMinimalPermissionsPlugin 支援檢查在 Azure API 中心註冊的 OAuth 所保護之 API 的 OAuth 許可權。外掛程式會使用 API 中心的信息，計算呼叫應用程式中使用的 API 所需的最小許可權。然後，外掛程式會將 JSON Web 令牌（JWT）令牌中使用的許可權與開發 Proxy 所記錄要求所需的最低必要範圍進行比較。

若要定義 API 的許可權，請在 API 的 OpenAPI 定義中包含這些許可權。下列範例示範如何在 OpenAPI 定義中定義 API 的權限：

{
  "openapi": "3.0.1",
  "info": {
    "title": "Northwind API",
    "description": "Northwind API",
    "version": "v1.0"
  },
  "servers": [
    {
      "url": "https://api.northwind.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize",
            "tokenUrl": "https://login.microsoftonline.com/common/oauth2/token",
            "scopes": {
              "customer.read": "Grants access to ready customer info",
              "customer.readwrite": "Grants access to read and write customer info"
            }
          }
        }
      }
    },
    "schemas": {
      "Customer": {
        "type": "object",
        // [...] trimmed for brevity
      }
    }
  },
  "paths": {
    "/customers/{customers-id}": {
      "description": "Provides operations to manage a customer",
      "get": {
        "summary": "Get customer by ID",
        "operationId": "getCustomerById",
        "security": [
          {
            "OAuth2": [
              "customer.read"
            ]
          },
          {
            "OAuth2": [
              "customer.readwrite"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/Customer"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update customer by ID",
        "operationId": "updateCustomerById",
        "security": [
          {
            "OAuth2": [
              "customer.readwrite"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Customer"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "No Content"
          }
        }
      },
      "parameters": [
        {
          "name": "customers-id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ]
    }
  },
  "x-ms-generated-by": {
    "toolName": "Dev Proxy",
    "toolVersion": "0.19.0"
  }
}

相關部分是 securitySchemes 區段，您可以在其中定義 API 所使用的 OAuth 範圍。然後，針對每個作業，您會在 security 區段中包含必要的範圍。

共用方式為