Compartilhar via

MinimalPermissionsGuidancePlugin

Compara as permissões usadas no token JWT enviadas para APIs com os escopos mínimos necessários para solicitações que o proxy registrou e mostra a diferença.

Captura de tela de uma linha de comando mostrando a verificação do Proxy de Desenvolvimento se as solicitações de API gravadas usam permissões mínimas de API de tokens.

Definição de instância do plug-in

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

Exemplo de configuração

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

Propriedades de configuração

Propriedade Descrição Padrão
apiSpecsFolderPath Caminho relativo ou absoluto para a pasta com especificações de API Nenhum
permissionsToExclude Os escopos a serem ignorados e não incluídos no relatório. profile openid offline_access email
schemeName O nome da definição do esquema de segurança usado para determinar permissões mínimas. Se não for especificado, o plug-in lerá informações do primeiro esquema oauth2 na especificação Nenhum

Opções de linha de comando

Nenhum

Observações

O MinimalPermissionsGuidancePlugin plug-in verifica se o aplicativo usa permissões mínimas para chamar APIs. Para verificar as permissões, o plug-in usa informações sobre APIs localizadas na pasta local especificada.

Definir permissões de API

O MinimalPermissionsGuidancePlugin plug-in dá suporte à verificação de permissões OAuth para APIs protegidas com OAuth. O plug-in calcula as permissões mínimas necessárias para chamar as APIs usadas no aplicativo usando as informações das especificações de API fornecidas. Em seguida, o plug-in compara as permissões usadas no token JSON Web Token (JWT) com os escopos mínimos necessários para as solicitações que o Dev Proxy registrou.

Para definir permissões para suas APIs, inclua-as na definição de OpenAPI de sua API. O exemplo a seguir mostra como definir permissões para uma API em uma definição 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"
  }
}

A parte relevante é a securitySchemes seção em que você define os escopos do OAuth que a API usa. Em seguida, para cada operação, você inclui os escopos necessários na security seção.

Substituir variáveis em especificações de API

Algumas especificações de API podem conter variáveis nas URLs do servidor. Usar variáveis é uma prática comum para acomodar ambientes diferentes (por exemplo, desenvolvimento, preparo, produção), versões de API ou locatários. Uma URL com uma variável tem esta aparência:

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

O MinimalPermissionsGuidancePlugin plug-in dá suporte à substituição de variáveis no conteúdo de especificações de API. Para substituir uma variável, inicie o Proxy de Desenvolvimento pela opção --env e especifique o nome e o valor da variável. Por exemplo, para substituir a tenant variável contoso, use o seguinte comando:

devproxy --env tenant=northwind

Esse comando substitui a tenant variável nas especificações da API pelo valor northwind. O plug-in usa a URL substituída para verificar se o aplicativo usa permissões mínimas para chamar APIs.

Mais informações

  • Last updated on