Integración de Express con los permisos verificados de Amazon

La integración de Verified Permissions Express proporciona un enfoque basado en el middleware para implementar la autorización en sus aplicaciones de Express.js. Con esta integración, puede proteger los puntos finales de su API mediante políticas de autorización detalladas sin modificar sus controladores de rutas existentes. La integración gestiona las comprobaciones de autorización de forma automática al interceptar las solicitudes, evaluarlas en función de las políticas definidas y garantizar que solo los usuarios autorizados puedan acceder a los recursos protegidos.

En este tema se explica cómo configurar la integración de Express, desde la creación de un almacén de políticas hasta la implementación y las pruebas del middleware de autorización. Si sigue estos pasos, puede añadir controles de autorización sólidos a su aplicación Express con cambios de código mínimos.

En este tema se hace referencia a los siguientes GitHub repositorios:

• cedar-policy/ authorization-for-expressjs: el middleware de autorización de Cedar para Express.js

• authorization-clients-jsverifiedpermissions/: los clientes de autorización de permisos verificados para JavaScript

• verifiedpermissions/examples/express-petstore: ejemplo de implementación con el middleware Express.js

Requisitos previos

Antes de implementar la integración de Express, asegúrese de tener:

• Una AWS cuenta con acceso a permisos verificados

• Node.js y npm instalados

• Una aplicación Express.js

• Un proveedor de identidad OpenID Connect (OIDC) (como Amazon Cognito)

• AWS CLIconfigurado con los permisos adecuados

Configuración de la integración

Paso 1: Crear un almacén de políticas

Cree un almacén de políticas mediante AWS CLI:

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

nota

Guarde el ID del almacén de políticas devuelto en la respuesta para usarlo en los pasos siguientes.

Paso 2: Instalar las dependencias

Instale los paquetes necesarios en su aplicación Express:

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

Configuración de la autorización

Paso 1: Genere y cargue el esquema de Cedar

Un esquema define el modelo de autorización de una aplicación, incluidos los tipos de entidades de la aplicación y las acciones que los usuarios pueden realizar. Se recomienda definir un espacio de nombres para el esquema. En este ejemplo, usaremos YourNamespace. Adjunta el esquema a los almacenes de políticas de permisos verificados y, cuando se agregan o modifican políticas, el servicio las valida automáticamente para compararlas con el esquema.

El @cedar-policy/authorization-for-expressjs paquete puede analizar las especificaciones de OpenAPI de su aplicación y generar un esquema de Cedar. Específicamente, el objeto paths es obligatorio en su especificación.

Si no tiene una especificación de OpenAPI, puede seguir las instrucciones rápidas del express-openapi-generatorpaquete para generar una especificación de OpenAPI.

Genere un esquema a partir de su especificación de OpenAPI:

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

A continuación, formatee el esquema de Cedar para usarlo con. AWS CLI Para obtener más información sobre el formato específico requerido, consulteEsquema del almacén de políticas de Amazon Verified Permissions.. Si necesitas ayuda para formatear el esquema, hay un script llamado prepare-cedar-schema.sh en el repositorio GitHubverifiedpermissions/examples. El siguiente es un ejemplo de llamada a ese script que genera el esquema formateado de permisos verificados en el archivo. v2.cedarschema.forAVP.json

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

Cargue el esquema formateado a su almacén de políticas y sustitúyalo por su policy-store-id ID de almacén de políticas:

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

Paso 2: Crear políticas de autorización

Si no se configura ninguna política, Cedar deniega todas las solicitudes de autorización. La integración del marco Express ayuda a iniciar este proceso mediante la generación de políticas de ejemplo basadas en el esquema generado anteriormente.

Cuando utilice esta integración en sus aplicaciones de producción, le recomendamos que cree nuevas políticas utilizando herramientas de infraestructura como código (IaaC). Para obtener más información, consulte Creación de recursos de Amazon Verified Permissions con AWS CloudFormation.

Genere ejemplos de políticas de Cedar:

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

Esto generará ejemplos de políticas en el /policies directorio. A continuación, puede personalizar estas políticas en función de sus casos de uso. Por ejemplo:

// 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
);

Formatee las políticas para usarlas con AWS CLI. Para obtener más información sobre el formato requerido, consulte create-policy en la AWS CLI referencia. Si necesitas ayuda para formatear las políticas, hay un script llamado convert_cedar_policies.sh en el repositorio GitHubverifiedpermissions/examples. La siguiente es una llamada a ese script:

./scripts/convert_cedar_policies.sh

Sube las políticas formateadas a Verified Permissions y policy_1.json sustitúyelas por la ruta y el nombre del archivo de políticas y policy-store-id por el ID del almacén de políticas:

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

Paso 3: Conectar un proveedor de identidad

De forma predeterminada, el middleware del autorizador de permisos verificados lee un token web JSON (JWT) incluido en el encabezado de autorización de la solicitud de API para obtener información del usuario. Los permisos verificados pueden validar el token además de realizar una evaluación de la política de autorización.

Cree un archivo de configuración de origen de identidad con un nombre identity-source-configuration.txt similar al siguiente con su userPoolArn manoclientId:

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

Cree la fuente de identidad ejecutando el siguiente AWS CLI comando, policy-store-id sustituyéndolo por su ID de almacén 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

Implementación del middleware de autorización

Actualice su aplicación Express para incluir el middleware de autorización. En este ejemplo, utilizamos identificadores de identidad, pero usted también puede utilizar identificadores de acceso. Para obtener más información, consulte authorization-for-expressjsenGitHub.

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);

Probando la integración

Para probar la implementación de la autorización, realiza solicitudes a los puntos finales de la API con diferentes tokens de usuario. El middleware de autorización evaluará automáticamente cada solicitud en función de las políticas que haya definido.

Por ejemplo, si ha configurado diferentes grupos de usuarios con diferentes permisos:

• Administradores: acceso completo a todos los recursos y funciones de administración

• Empleados: pueden ver, crear y actualizar los recursos

• Clientes: solo pueden ver los recursos

Puede validar que las políticas de permisos funcionan según lo esperado iniciando sesión con diferentes usuarios e intentando realizar varias operaciones. En la terminal de la aplicación Express, puede ver el resultado del registro que proporciona detalles adicionales sobre las decisiones de autorización.

Solución de problemas

Si tiene errores de autorización, intente lo siguiente:

• Compruebe que el ID del almacén de políticas sea correcto

• Asegúrese de que su fuente de identidad esté configurada correctamente

• Compruebe que sus políticas tengan el formato correcto

• Valide que sus tokens JWT sean válidos

Pasos a seguir a continuación

Tras implementar la integración básica, considere lo siguiente:

• Implementar mapeadores personalizados para escenarios de autorización específicos

• Configurar la supervisión y el registro de las decisiones de autorización

• Crear políticas adicionales para diferentes roles de usuario