Sdílet prostřednictvím

MinimalPermissionsGuidancePlugin

Porovná oprávnění používaná v tokenu JWT odesílaných do rozhraní API s minimálními požadovanými obory potřebnými pro požadavky, které proxy zaznamenal, a ukazuje rozdíl.

Snímek obrazovky příkazového řádku s kontrolou dev proxy serveru, jestli zaznamenané požadavky rozhraní API používají tokeny s minimálními oprávněními rozhraní API

Definice instance modulu plug-in

{
  "name": "MinimalPermissionsGuidancePlugin",
  "enabled": true,
  "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
  "configSection": "minimalPermissionsGuidancePlugin"
}

Příklad konfigurace

{
  "minimalPermissionsGuidancePlugin": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v1.0.0/minimalpermissionsguidanceplugin.schema.json",
    "apiSpecsFolderPath": "./api-specs",
    "permissionsToExclude": [ 
      "profile", 
      "openid", 
      "offline_access", 
      "email"
    ]
  }
}

Vlastnosti konfigurace

Vlastnost Popis Výchozí
apiSpecsFolderPath Relativní nebo absolutní cesta ke složce se specifikací rozhraní API Žádné
permissionsToExclude Obory, které se mají ignorovat a nezahrnují do sestavy. profile openid offline_access email
schemeName Název definice schématu zabezpečení sloužící k určení minimálních oprávnění. Pokud není zadaný, modul plug-in načte informace z prvního schématu oauth2 ve specifikaci. Žádné

Možnosti příkazového řádku

Žádné

Poznámky

Modul MinimalPermissionsGuidancePlugin plug-in zkontroluje, jestli aplikace používá minimální oprávnění k volání rozhraní API. Ke kontrole oprávnění používá modul plug-in informace o rozhraních API umístěných v zadané místní složce.

Definování oprávnění rozhraní API

Modul MinimalPermissionsGuidancePlugin plug-in podporuje kontrolu oprávnění OAuth pro rozhraní API zabezpečená pomocí OAuth. Modul plug-in vypočítá minimální oprávnění potřebná k volání rozhraní API používaných v aplikaci s využitím informací ze zadaných specifikací rozhraní API. Pak modul plug-in porovná oprávnění použitá v tokenu JSON Web Token (JWT) s minimálními požadovanými obory potřebnými pro požadavky, které dev proxy zaznamenal.

Pokud chcete definovat oprávnění pro vaše rozhraní API, zahrňte je do definice OpenAPI vašeho rozhraní API. Následující příklad ukazuje, jak definovat oprávnění pro rozhraní API v definici OpenAPI:

{
  "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.22.0"
  }
}

Relevantní část je securitySchemes část, ve které definujete obory OAuth, které rozhraní API používá. Pro každou operaci pak do oddílu security zahrnete požadované obory.

Nahrazení proměnných ve specifikacích rozhraní API

Některé specifikace rozhraní API můžou obsahovat proměnné v adresách URL serveru. Použití proměnných je běžný postup pro přizpůsobení různých prostředí (například vývoj, příprava, produkční prostředí), verze rozhraní API nebo tenanti. Adresa URL s proměnnou vypadá takto:

openapi: 3.0.4
info:
  title: SharePoint REST API
  description: SharePoint REST API
  version: v1.0
servers:
  - url: https://{tenant}.sharepoint.com
    variables:
      tenant:
        default: contoso

Modul MinimalPermissionsGuidancePlugin plug-in podporuje nahrazení proměnných v obsahu specifikací rozhraní API. Pokud chcete nahradit proměnnou, spusťte Dev Proxy --env s možností a zadejte název a hodnotu proměnné. Pokud chcete například nahradit proměnnou tenant následujícím příkazem contoso:

devproxy --env tenant=northwind

Tento příkaz nahradí proměnnou tenant ve specifikacích rozhraní API hodnotou northwind. Modul plug-in používá nahrazenou adresu URL ke kontrole, jestli aplikace používá minimální oprávnění k volání rozhraní API.

Více informací

  • Last updated on