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 :

Prérequis

Avant de mettre en œuvre l'intégration Express, assurez-vous de disposer des éléments suivants :

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"

É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 noms pour votre schéma. Dans cet exemple, nous utilisons YourNamespace. 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 de votre application et générer un schéma Cedar. Plus précisément, l'objet paths est requis dans votre spécification.

Si vous n'avez pas de spécification OpenAPI, vous pouvez suivre les instructions rapides du express-openapi-generatorpackage pour générer une spécification OpenAPI.

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/examples. Voici un exemple d'appel à ce script qui génère le schéma au format Verified Permissions dans le v2.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. Voici un appel à ce script :

./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-id policy-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-expressjsci-dessousGitHub.

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 :

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

Étapes suivantes

Après avoir implémenté l'intégration de base, pensez à :