Integrando o Express com as permissões verificadas da Amazon - Amazon Verified Permissions
Pré-requisitosConfigurando a integraçãoConfigurar autorizaçãoImplementando o middleware de autorizaçãoTestando a integraçãoSolução de problemasPróximas etapas

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Integrando o Express com as permissões verificadas da Amazon

A integração do Verified Permissions Express fornece uma abordagem baseada em middleware para implementar a autorização em seus aplicativos Express.js. Com essa integração, você pode proteger seus endpoints de API usando políticas de autorização refinadas sem modificar seus manipuladores de rotas existentes. A integração processa as verificações de autorização automaticamente interceptando solicitações, avaliando-as de acordo com suas políticas definidas e garantindo que somente usuários autorizados possam acessar recursos protegidos.

Este tópico explica como configurar a integração do Express, desde a criação de um repositório de políticas até a implementação e o teste do middleware de autorização. Seguindo essas etapas, você pode adicionar controles de autorização robustos ao seu aplicativo Express com o mínimo de alterações no código.

Os seguintes GitHub repositórios são referenciados em todo este tópico:

Pré-requisitos

Antes de implementar a integração Express, certifique-se de ter:

Configurando a integração

Etapa 1: criar um repositório de políticas

Crie um repositório de políticas usando AWS CLI:

aws verifiedpermissions create-policy-store --validation-settings "mode=STRICT"
nota

Salve o ID do repositório de políticas retornado na resposta para uso nas etapas subsequentes.

Etapa 2: instalar dependências

Instale os pacotes necessários em seu aplicativo Express:

npm i --save @verifiedpermissions/authorization-clients-js
npm i --save @cedar-policy/authorization-for-expressjs

Configurar autorização

Etapa 1: gerar e carregar o esquema Cedar

Um esquema define o modelo de autorização para um aplicativo, incluindo os tipos de entidades no aplicativo e as ações que os usuários podem realizar. Recomendamos definir um namespace para seu esquema. Neste exemplo, usamos YourNamespace. Você anexa seu esquema aos seus repositórios de políticas de Permissões Verificadas e, quando as políticas são adicionadas ou modificadas, o serviço valida automaticamente as políticas em relação ao esquema.

O @cedar-policy/authorization-for-expressjs pacote pode analisar as especificações da OpenAPI do seu aplicativo e gerar um esquema Cedar. Especificamente, o objeto paths é obrigatório em sua especificação.

Se você não tiver uma especificação OpenAPI, siga as instruções rápidas do express-openapi-generatorpacote para gerar uma especificação OpenAPI.

Gere um esquema a partir da sua especificação da OpenAPI:

npx @cedar-policy/authorization-for-expressjs generate-schema --api-spec schemas/openapi.json --namespace YourNamespace --mapping-type SimpleRest

Em seguida, formate o esquema Cedar para uso com o. AWS CLI Para obter mais informações sobre o formato específico necessário, consulteEsquema do armazenamento de políticas do Amazon Verified Permissions. Se precisar de ajuda para formatar o esquema, há um script chamado prepare-cedar-schema.sh no repositório GitHubverifiedpermissions/examples. Veja a seguir um exemplo de chamada para esse script que gera o esquema formatado de Permissões Verificadas no arquivo. v2.cedarschema.forAVP.json

./scripts/prepare-cedar-schema.sh v2.cedarschema.json v2.cedarschema.forAVP.json

Faça upload do esquema formatado em seu repositório de políticas, policy-store-id substituindo-o pelo ID do repositório de políticas:

aws verifiedpermissions put-schema \
  --definition file://v2.cedarschema.forAVP.json \
  --policy-store-id policy-store-id

Etapa 2: criar políticas de autorização

Se nenhuma política for configurada, o Cedar negará todas as solicitações de autorização. A integração da estrutura Express ajuda a iniciar esse processo gerando políticas de exemplo com base no esquema gerado anteriormente.

Ao usar essa integração em seus aplicativos de produção, recomendamos criar novas políticas usando ferramentas de infraestrutura como código (IAAC). Para obter mais informações, consulte Criação de recursos do Amazon Verified Permissions com o AWS CloudFormation.

Gere exemplos de políticas do Cedar:

npx @cedar-policy/authorization-for-expressjs generate-policies --schema v2.cedarschema.json

Isso gerará exemplos de políticas no /policies diretório. Em seguida, você pode personalizar essas políticas com base em seus casos de uso. Por exemplo:

// Defines permitted administrator user group actions
permit (
    principal in YourNamespace::UserGroup::"<userPoolId>|administrator",
    action,
    resource
);

// Defines permitted employee user group actions
permit (
    principal in YourNamespace::UserGroup::"<userPoolId>|employee",
    action in
        [YourNamespace::Action::"GET /resources",
         YourNamespace::Action::"POST /resources",
         YourNamespace::Action::"GET /resources/{resourceId}",
         YourNamespace::Action::"PUT /resources/{resourceId}"],
    resource
);

Formate as políticas para uso com AWS CLI o. Para obter mais informações sobre o formato exigido, consulte create-policy na referência.AWS CLI Se precisar de ajuda para formatar as políticas, há um script chamado convert_cedar_policies.sh no repositório GitHubverifiedpermissions/examples. A seguir está uma chamada para esse script:

./scripts/convert_cedar_policies.sh

Faça upload das políticas formatadas para Permissões verificadas, policy_1.json substituindo-as pelo caminho e nome do seu arquivo de política e policy-store-id pelo ID do repositório de políticas:

aws verifiedpermissions create-policy \
  --definition file://policies/json/policy_1.json \
  --policy-store-id policy-store-id

Etapa 3: Conectar um provedor de identidade

Por padrão, o middleware autorizador de permissões verificadas lê um token Web JSON (JWT) fornecido no cabeçalho de autorização da solicitação da API para obter informações do usuário. As permissões verificadas podem validar o token, além de realizar a avaliação da política de autorização.

Crie um arquivo de configuração de origem identity-source-configuration.txt de identidade chamado semelhante ao seguinte com seu userPoolArn eclientId:

{
    "cognitoUserPoolConfiguration": {
        "userPoolArn": "arn:aws:cognito-idp:region:account:userpool/pool-id",
        "clientIds": ["client-id"],
        "groupConfiguration": {
            "groupEntityType": "YourNamespace::UserGroup"
        }
    }
}

Crie a fonte de identidade executando o seguinte AWS CLI comando, policy-store-id substituindo-o pelo ID do repositório de políticas:

aws verifiedpermissions create-identity-source \
  --configuration file://identity-source-configuration.txt \
  --policy-store-id policy-store-id \
  --principal-entity-type YourNamespace::User

Implementando o middleware de autorização

Atualize seu aplicativo Express para incluir o middleware de autorização. Neste exemplo, estamos usando tokens de identidade, mas você também pode usar tokens de acesso. Para obter mais informações, consulte authorization-for-expressjsemGitHub.

const { ExpressAuthorizationMiddleware } = require('@cedar-policy/authorization-for-expressjs');

const { AVPAuthorizationEngine } = require('@verifiedpermissions/authorization-clients');

const avpAuthorizationEngine = new AVPAuthorizationEngine({
    policyStoreId: 'policy-store-id',
    callType: 'identityToken'
});

const expressAuthorization = new ExpressAuthorizationMiddleware({
    schema: {
        type: 'jsonString',
        schema: fs.readFileSync(path.join(__dirname, '../v4.cedarschema.json'), 'utf8'),
    },
    authorizationEngine: avpAuthorizationEngine,
    principalConfiguration: { type: 'identityToken' },
    skippedEndpoints: [],
    logger: {
        debug: (s) => console.log(s),
        log: (s) => console.log(s),
    }
});

// Add the middleware to your Express application
app.use(expressAuthorization.middleware);

Testando a integração

Você pode testar sua implementação de autorização fazendo solicitações aos seus endpoints da API com diferentes tokens de usuário. O middleware de autorização avaliará automaticamente cada solicitação em relação às suas políticas definidas.

Por exemplo, se você configurou grupos de usuários diferentes com permissões diferentes:

  • Administradores: acesso total a todos os recursos e funções de gerenciamento

  • Funcionários: podem visualizar, criar e atualizar recursos

  • Clientes: só podem visualizar recursos

Você pode validar se as políticas de permissões estão funcionando conforme o esperado fazendo login com usuários diferentes e tentando várias operações. No terminal do aplicativo Express, você pode ver a saída do log que fornece detalhes adicionais sobre as decisões de autorização.

Solução de problemas

Se você tiver falhas na autorização, tente o seguinte:

  • Verifique se o ID do repositório de políticas está correto

  • Certifique-se de que sua fonte de identidade esteja configurada corretamente

  • Verifique se suas políticas estão formatadas corretamente

  • Valide se seus tokens JWT são válidos

Próximas etapas

Depois de implementar a integração básica, considere:

  • Implementando mapeadores personalizados para cenários de autorização específicos

  • Configurando o monitoramento e o registro para decisões de autorização

  • Criação de políticas adicionais para diferentes funções de usuário