Compartir a través de

MinimalPermissionsGuidancePlugin

Compara los permisos usados en el token JWT enviados a las API con los ámbitos mínimos necesarios para las solicitudes que registró el proxy y muestra la diferencia.

Captura de pantalla de una línea de comandos que muestra la comprobación del proxy de desarrollo si las solicitudes de API grabadas usan tokens mínimos de permisos de API.

Definición de instancia del complemento

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

Ejemplo de configuración

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

Propiedades de configuración

Propiedad Descripción Valor predeterminado
apiSpecsFolderPath Ruta de acceso relativa o absoluta a la carpeta con especificaciones de API Ninguno
permissionsToExclude Ámbitos que se omitirán y no se incluirán en el informe. profile openid offline_access email
schemeName Nombre de la definición del esquema de seguridad que se usa para determinar los permisos mínimos. Si no se especifica, el complemento lee información del primer esquema de oauth2 en la especificación. Ninguno

Opciones de línea de comandos

Ninguno

Observaciones

El MinimalPermissionsGuidancePlugin complemento comprueba si la aplicación usa permisos mínimos para llamar a las API. Para comprobar los permisos, el complemento usa información sobre las API ubicadas en la carpeta local especificada.

Definición de permisos de API

El MinimalPermissionsGuidancePlugin complemento admite la comprobación de permisos de OAuth para las API protegidas con OAuth. El complemento calcula los permisos mínimos necesarios para llamar a las API usadas en la aplicación mediante la información de las especificaciones de API proporcionadas. A continuación, el complemento compara los permisos usados en el token json Web Token (JWT) con los ámbitos mínimos necesarios para las solicitudes que registró el proxy de desarrollo.

Para definir permisos para las API, inclúyelos en la definición de OpenAPI de la API. En el ejemplo siguiente se muestra cómo definir permisos para una API en una definición de 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"
  }
}

La parte pertinente es la securitySchemes sección, donde se definen los ámbitos de OAuth que usa la API. A continuación, para cada operación, se incluyen los ámbitos necesarios en la security sección .

Reemplazo de variables en especificaciones de API

Algunas especificaciones de API pueden contener variables en las direcciones URL del servidor. El uso de variables es una práctica común para dar cabida a diferentes entornos (por ejemplo, desarrollo, ensayo, producción), versiones de API o inquilinos. Una dirección URL con una variable tiene este aspecto:

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

El MinimalPermissionsGuidancePlugin complemento admite la sustitución de variables en el contenido de las especificaciones de API. Para reemplazar una variable, inicie Dev Proxy por la --env opción y especifique el nombre y el valor de la variable. Por ejemplo, para reemplazar la tenant variable por contoso, use el siguiente comando:

devproxy --env tenant=northwind

Este comando reemplaza la tenant variable en las especificaciones de API por el valor northwind. El complemento usa la dirección URL reemplazada para comprobar si la aplicación usa permisos mínimos para llamar a las API.

Más información

  • Last updated on