Freigeben über

MinimalPermissionsGuidancePlugin

Vergleicht die Berechtigungen, die im JWT-Token verwendet werden, das an APIs gesendet wird, mit den mindest erforderlichen Bereichen, die für Anforderungen erforderlich sind, die für Anforderungen erforderlich sind, die von dem Proxy aufgezeichnet wurden, und zeigt den Unterschied an.

Screenshot einer Befehlszeile mit Der Dev Proxy-Überprüfung, ob die aufgezeichneten API-Anforderungen Token minimale API-Berechtigungen verwenden.

Definition der Plug-In-Instanz

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

Konfigurationsbeispiel

{
  "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"
    ]
  }
}

Konfigurationseigenschaften

Eigenschaft BESCHREIBUNG Standard
apiSpecsFolderPath Relativer oder absoluter Pfad zum Ordner mit API-Spezifikationen Keine
permissionsToExclude Die Bereiche, die ignoriert werden sollen und nicht im Bericht enthalten sind. profile openid offline_access email
schemeName Der Name der Sicherheitsschemadefinition, die verwendet wird, um minimale Berechtigungen zu bestimmen. Wenn nicht angegeben, liest das Plug-In Informationen aus dem ersten oauth2-Schema in der Spezifikation. Keine

Befehlszeilenoptionen

Keine

Bemerkungen

Das MinimalPermissionsGuidancePlugin Plug-In überprüft, ob die App minimale Berechtigungen zum Aufrufen von APIs verwendet. Um Berechtigungen zu überprüfen, verwendet das Plug-In Informationen zu APIs, die sich im angegebenen lokalen Ordner befinden.

Definieren von API-Berechtigungen

Das MinimalPermissionsGuidancePlugin Plug-In unterstützt die Überprüfung von OAuth-Berechtigungen für APIs, die mit OAuth gesichert sind. Das Plug-In berechnet die minimalen Berechtigungen, die zum Aufrufen der in der App verwendeten APIs mit den Informationen aus den bereitgestellten API-Spezifikationen erforderlich sind. Anschließend vergleicht das Plug-In die Berechtigungen, die im JSON-Webtoken (JWT) verwendet werden, mit den minimal erforderlichen Bereichen, die für die Anforderungen erforderlich sind, die von Dev Proxy aufgezeichnet wurden.

Um Berechtigungen für Ihre APIs zu definieren, fügen Sie sie in die OpenAPI-Definition Ihrer API ein. Das folgende Beispiel zeigt, wie Berechtigungen für eine API in einer OpenAPI-Definition definiert werden:

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

Der relevante Teil ist der securitySchemes Abschnitt, in dem Sie die von der API verwendeten OAuth-Bereiche definieren. Anschließend fügen Sie für jeden Vorgang die erforderlichen Bereiche in den security Abschnitt ein.

Ersetzen von Variablen in API-Spezifikationen

Einige API-Spezifikationen enthalten möglicherweise Variablen in Server-URLs. Die Verwendung von Variablen ist eine gängige Methode, um verschiedene Umgebungen (z. B. Entwicklung, Staging, Produktion), API-Versionen oder Mandanten zu berücksichtigen. Eine URL mit einer Variablen sieht wie folgt aus:

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

Das MinimalPermissionsGuidancePlugin Plug-In unterstützt das Ersetzen von Variablen im INHALT der API-Spezifikationen. Um eine Variable zu ersetzen, starten Sie Dev Proxy mit der --env Option, und geben Sie den Variablennamen und -wert an. Um beispielsweise die tenant Variable durch contosozu ersetzen, verwenden Sie den folgenden Befehl:

devproxy --env tenant=northwind

Dieser Befehl ersetzt die tenant Variable in den API-Spezifikationen durch den Wert northwind. Das Plug-In verwendet die ersetzte URL, um zu überprüfen, ob die App minimale Berechtigungen zum Aufrufen von APIs verwendet.

Weitere Informationen

  • Last updated on