Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# 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](https://github.com/cedar-policy/authorization-for-expressjs): el middleware de autorización de Cedar para Express.js
+ [authorization-clients-jsverifiedpermissions/](https://github.com/verifiedpermissions/authorization-clients-js): los clientes de autorización de permisos verificados para JavaScript
+ [verifiedpermissions/examples/express-petstore](https://github.com/verifiedpermissions/examples/tree/main/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](https://docs.aws.amazon.com/accounts/latest/reference/getting-started.html) con acceso a permisos verificados
+ [Node.js](https://nodejs.org/) y [npm instalados](https://docs.npmjs.com/)
+ Una aplicación [Express.js](https://expressjs.com/)
+ Un proveedor de identidad OpenID Connect (OIDC) (como) [Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/what-is-amazon-cognito.html)
+ [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html)configurado 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](https://docs.cedarpolicy.com/overview/terminology.html#term-namespaces) 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](https://swagger.io/specification/) 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-generator](https://github.com/nklisch/express-openapi-generator)paquete 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, consulte[Esquema del almacén de políticas de Amazon Verified Permissions.](schema.md). Si necesitas ayuda para formatear el esquema, hay un script llamado `prepare-cedar-schema.sh` en el repositorio [GitHubverifiedpermissions/examples](https://github.com/verifiedpermissions/examples/tree/main/express-petstore/start/scripts). 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 permisos verificados de Amazon con AWS CloudFormation](cloudformation-verified-permissions.md).
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::"|administrator",
action,
resource
);
// Defines permitted employee user group actions
permit (
principal in YourNamespace::UserGroup::"|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](https://docs.aws.amazon.com/cli/latest/reference/verifiedpermissions/create-policy.html) 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](https://github.com/verifiedpermissions/examples/tree/main/express-petstore/start/scripts). 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` mano`clientId`:
```
{
"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-expressjs](https://github.com/cedar-policy/authorization-for-expressjs)enGitHub.
```
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.
## Resolució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
## Siguientes pasos
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