Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
Intégrer Express aux autorisations vérifiées d'Amazon
L'intégration de Verified Permissions Express fournit une approche basée sur un intergiciel pour implémenter l'autorisation dans vos applications Express.js. Grâce à cette intégration, vous pouvez protéger vos points de terminaison d'API à l'aide de politiques d'autorisation précises sans modifier vos gestionnaires de route existants. L'intégration gère automatiquement les contrôles d'autorisation en interceptant les demandes, en les évaluant par rapport à vos politiques définies et en garantissant que seuls les utilisateurs autorisés peuvent accéder aux ressources protégées.
Cette rubrique explique comment configurer l'intégration Express, de la création d'un magasin de politiques à la mise en œuvre et au test du middleware d'autorisation. En suivant ces étapes, vous pouvez ajouter des contrôles d'autorisation robustes à votre application Express avec un minimum de modifications de code.
Les GitHub dépôts suivants sont référencés dans cette rubrique :
-
cedar-policy/ authorization-for-expressjs
- Le middleware d'autorisation Cedar pour Express.js -
verifiedpermissions/ authorization-clients-js
- Les clients d'autorisation Verified Permissions pour JavaScript -
verifiedpermissions/examples/express-petstore
- Exemple d'implémentation à l'aide du middleware Express.js
Prérequis
Avant de mettre en œuvre l'intégration Express, assurez-vous de disposer des éléments suivants :
-
Un AWS compte avec accès aux autorisations vérifiées
-
Une application Express.js
-
Un fournisseur d'identité OpenID Connect (OIDC) (tel qu'Amazon Cognito)
-
AWS CLIconfiguré avec les autorisations appropriées
Configuration de l'intégration
Étape 1 : créer un magasin de politiques
Créez un magasin de politiques à l'aide de AWS CLI :
aws verifiedpermissions create-policy-store --validation-settings "mode=STRICT"
Note
Enregistrez l'ID du magasin de politiques renvoyé dans la réponse pour l'utiliser lors des étapes suivantes.
Étape 2 : Installation des dépendances
Installez les packages requis dans votre application Express :
npm i --save @verifiedpermissions/authorization-clients-js npm i --save @cedar-policy/authorization-for-expressjs
Configuration de l'autorisation
Étape 1 : générer et télécharger le schéma Cedar
Un schéma définit le modèle d'autorisation d'une application, y compris les types d'entités de l'application et les actions que les utilisateurs sont autorisés à effectuer. Nous vous recommandons de définir un espace de nomsYourNamespace
. Vous attachez votre schéma à vos magasins de politiques d'autorisations vérifiées, et lorsque des politiques sont ajoutées ou modifiées, le service valide automatiquement les politiques par rapport au schéma.
Le @cedar-policy/authorization-for-expressjs
package peut analyser les spécifications OpenAPI
Si vous n'avez pas de spécification OpenAPI, vous pouvez suivre les instructions rapides du express-openapi-generator
Générez un schéma à partir de votre spécification OpenAPI :
npx @cedar-policy/authorization-for-expressjs generate-schema --api-spec schemas/openapi.json --namespace
YourNamespace
--mapping-type SimpleRest
Ensuite, formatez le schéma Cedar pour l'utiliser avec AWS CLI. Pour plus d'informations sur le format spécifique requis, consultezSchéma de la boutique Amazon Verified Permissions Policy. Si vous avez besoin d'aide pour formater le schéma, un script est appelé prepare-cedar-schema.sh
dans le dépôt GitHubverifiedpermissions/examplesv2.cedarschema.forAVP.json
fichier.
./scripts/prepare-cedar-schema.sh v2.cedarschema.json v2.cedarschema.forAVP.json
Téléchargez le schéma formaté dans votre magasin de politiques, en le policy-store-id
remplaçant par l'ID de votre magasin de politiques :
aws verifiedpermissions put-schema \ --definition file://v2.cedarschema.forAVP.json \ --policy-store-id
policy-store-id
Étape 2 : créer des politiques d'autorisation
Si aucune politique n'est configurée, Cedar refuse toutes les demandes d'autorisation. L'intégration du framework Express permet de démarrer ce processus en générant des exemples de politiques basés sur le schéma généré précédemment.
Lorsque vous utilisez cette intégration dans vos applications de production, nous vous recommandons de créer de nouvelles politiques à l'aide des outils d'infrastructure en tant que code (iAAC). Pour de plus amples informations, veuillez consulter Création de ressources Amazon Verified Permissions avec AWS CloudFormation.
Générez des exemples de politiques Cedar :
npx @cedar-policy/authorization-for-expressjs generate-policies --schema v2.cedarschema.json
Cela générera des exemples de politiques dans le /policies
répertoire. Vous pouvez ensuite personnaliser ces politiques en fonction de vos cas d'utilisation. Par exemple :
// 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 );
Formatez les politiques à utiliser avec AWS CLI. Pour plus d'informations sur le format requis, voir create-policy dans la AWS CLI référence. Si vous avez besoin d'aide pour formater les politiques, un script est appelé convert_cedar_policies.sh
dans le référentiel GitHubverifiedpermissions/examples
./scripts/convert_cedar_policies.sh
Téléchargez les politiques formatées dans Verified Permissions, en les policy_1.json
remplaçant par le chemin et le nom de votre fichier de politiques et policy-store-id
par l'ID de votre magasin de politiques :
aws verifiedpermissions create-policy \ --definition file://
policies/json/policy_1.json
\ --policy-store-idpolicy-store-id
Étape 3 : Connecter un fournisseur d'identité
Par défaut, le middleware d'autorisation Verified Permissions lit un jeton Web JSON (JWT) fourni dans l'en-tête d'autorisation de la demande d'API pour obtenir des informations sur l'utilisateur. Les autorisations vérifiées peuvent valider le jeton en plus d'évaluer la politique d'autorisation.
Créez un fichier de configuration de source d'identité nommé identity-source-configuration.txt
qui ressemble à ce qui suit avec votre userPoolArn
et clientId
:
{ "cognitoUserPoolConfiguration": { "userPoolArn": "
arn:aws:cognito-idp:region:account:userpool/pool-id
", "clientIds": ["client-id
"], "groupConfiguration": { "groupEntityType": "YourNamespace::UserGroup" } } }
Créez la source d'identité en exécutant la AWS CLI commande suivante, en la policy-store-id
remplaçant par votre identifiant de magasin de politiques :
aws verifiedpermissions create-identity-source \ --configuration file://identity-source-configuration.txt \ --policy-store-id
policy-store-id
\ --principal-entity-type YourNamespace::User
Implémentation du middleware d'autorisation
Mettez à jour votre application Express pour inclure le middleware d'autorisation. Dans cet exemple, nous utilisons des jetons d'identité, mais vous pouvez également utiliser des jetons d'accès. Pour plus d'informations, voir authorization-for-expressjs
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);
Tester l'intégration
Vous pouvez tester l'implémentation de votre autorisation en envoyant des demandes à vos points de terminaison d'API avec différents jetons utilisateur. Le middleware d'autorisation évaluera automatiquement chaque demande par rapport à vos politiques définies.
Par exemple, si vous avez configuré différents groupes d'utilisateurs dotés d'autorisations différentes :
-
Administrateurs : accès complet à toutes les ressources et fonctions de gestion
-
Employés : peuvent consulter, créer et mettre à jour des ressources
-
Clients : peuvent uniquement consulter les ressources
Vous pouvez vérifier que les politiques d'autorisation fonctionnent comme prévu en vous connectant avec différents utilisateurs et en tentant diverses opérations. Dans le terminal de l'application Express, vous pouvez voir le résultat du journal qui fournit des informations supplémentaires sur les décisions d'autorisation.
Résolution des problèmes
- Si vous rencontrez des problèmes d'autorisation, essayez ce qui suit :
-
-
Vérifiez que l'identifiant de votre magasin de polices est correct
-
Assurez-vous que votre source d'identité est correctement configurée
-
Vérifiez que vos politiques sont correctement formatées
-
Validez que vos jetons JWT sont valides
-
Étapes suivantes
Après avoir implémenté l'intégration de base, pensez à :
-
Implémentation de mappeurs personnalisés pour des scénarios d'autorisation spécifiques
-
Configuration de la surveillance et de la journalisation des décisions d'autorisation
-
Création de politiques supplémentaires pour différents rôles d'utilisateur