Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Integration von Express mit Amazon Verified Permissions

Die Verified Permissions Express-Integration bietet einen Middleware-basierten Ansatz zur Implementierung der Autorisierung in Ihren Express.js -Anwendungen. Mit dieser Integration können Sie Ihre API-Endpunkte mithilfe detaillierter Autorisierungsrichtlinien schützen, ohne Ihre vorhandenen Route-Handler ändern zu müssen. Die Integration wickelt Autorisierungsprüfungen automatisch ab, indem sie Anfragen abfängt, sie anhand Ihrer definierten Richtlinien bewertet und sicherstellt, dass nur autorisierte Benutzer auf geschützte Ressourcen zugreifen können.

Dieses Thema führt Sie durch die Einrichtung der Express-Integration, von der Erstellung eines Richtlinienspeichers bis hin zur Implementierung und zum Testen der Autorisierungs-Middleware. Wenn Sie diese Schritte befolgen, können Sie Ihrer Express-Anwendung mit minimalen Codeänderungen robuste Autorisierungskontrollen hinzufügen.

In diesem Thema GitHub wird immer wieder auf die folgenden Repos verwiesen:

Voraussetzungen

Bevor Sie die Express-Integration implementieren, stellen Sie sicher, dass Sie über Folgendes verfügen:

Einrichtung der Integration

Schritt 1: Erstellen Sie einen Richtlinienspeicher

Erstellen Sie einen Richtlinienspeicher mit dem AWS CLI:

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

Schritt 2: Abhängigkeiten installieren

Installieren Sie die erforderlichen Pakete in Ihrer Express-Anwendung:

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

Autorisierung konfigurieren

Schritt 1: Generieren Sie das Cedar-Schema und laden Sie es hoch

Ein Schema definiert das Autorisierungsmodell für eine Anwendung, einschließlich der Entitätstypen in der Anwendung und der Aktionen, die Benutzer ausführen dürfen. Wir empfehlen, einen Namespace für Ihr Schema zu definieren. In diesem Beispiel verwenden wir YourNamespace. Sie hängen Ihr Schema an Ihre Richtlinienspeicher für verifizierte Berechtigungen an. Wenn Richtlinien hinzugefügt oder geändert werden, validiert der Dienst die Richtlinien automatisch anhand des Schemas.

Das @cedar-policy/authorization-for-expressjs Paket kann die OpenAPI-Spezifikationen Ihrer Anwendung analysieren und ein Cedar-Schema generieren. Insbesondere ist das Paths-Objekt in Ihrer Spezifikation erforderlich.

Wenn Sie keine OpenAPI-Spezifikation haben, können Sie den Kurzanweisungen des express-openapi-generatorPakets folgen, um eine OpenAPI-Spezifikation zu generieren.

Generieren Sie ein Schema aus Ihrer OpenAPI-Spezifikation:

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

Formatieren Sie als Nächstes das Cedar-Schema für die Verwendung mit dem AWS CLI. Weitere Informationen zu dem jeweils erforderlichen Format finden Sie unterSpeicherschema für Richtlinien von Amazon Verified Permissions. Wenn Sie Hilfe beim Formatieren des Schemas benötigen, gibt es ein Skript, das prepare-cedar-schema.sh im Repo GitHubverifiedpermissions/examples aufgerufen wird. Im Folgenden finden Sie einen Beispielaufruf dieses Skripts, das das formatierte Schema Verified Permissions in der Datei ausgibt. v2.cedarschema.forAVP.json

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

Laden Sie das formatierte Schema in Ihren Richtlinienspeicher hoch und policy-store-id ersetzen Sie es durch Ihre Policy-Speicher-ID:

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

Schritt 2: Autorisierungsrichtlinien erstellen

Wenn keine Richtlinien konfiguriert sind, lehnt Cedar alle Autorisierungsanfragen ab. Die Express-Framework-Integration hilft dabei, diesen Prozess zu beschleunigen, indem sie Beispielrichtlinien generiert, die auf dem zuvor generierten Schema basieren.

Wenn Sie diese Integration in Ihren Produktionsanwendungen verwenden, empfehlen wir, mithilfe von IaaC-Tools (Infrastructure as a Code) neue Richtlinien zu erstellen. Weitere Informationen finden Sie unter Ressourcen mit Amazon Verified Permissions erstellen mit AWS CloudFormation.

Generieren Sie Cedar-Beispielrichtlinien:

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

Dadurch werden Beispielrichtlinien im /policies Verzeichnis generiert. Sie können diese Richtlinien dann an Ihre Anwendungsfälle anpassen. Zum Beispiel:

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

Formatieren Sie die Richtlinien für die Verwendung mit dem AWS CLI. Weitere Informationen zum erforderlichen Format finden Sie unter create-policy in der AWS CLI Referenz. Wenn Sie Hilfe beim Formatieren der Richtlinien benötigen, gibt es ein Skript, das convert_cedar_policies.sh im Repo GitHubverifiedpermissions/examples aufgerufen wird. Das Folgende ist ein Aufruf dieses Skripts:

./scripts/convert_cedar_policies.sh

Laden Sie die formatierten Richtlinien in Verified Permissions hoch und policy_1.json ersetzen Sie sie durch den Pfad und den Namen Ihrer Richtliniendatei sowie policy-store-id durch Ihre Policy-Store-ID:

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

Schritt 3: Einen Identitätsanbieter verbinden

Standardmäßig liest die Authorizer-Middleware Verified Permissions ein JSON Web Token (JWT), das im Autorisierungsheader der API-Anfrage bereitgestellt wird, um Benutzerinformationen abzurufen. Verified Permissions kann das Token zusätzlich zur Bewertung der Autorisierungsrichtlinien validieren.

Erstellen Sie eine Konfigurationsdatei für identity-source-configuration.txt die Identitätsquelle mit dem Namen userPoolArn und, die wie folgt aussiehtclientId:

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

Erstellen Sie die Identitätsquelle, indem Sie den folgenden AWS CLI Befehl ausführen und ihn policy-store-id durch Ihre Policy Store-ID ersetzen:

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

Implementierung der Autorisierungs-Middleware

Aktualisieren Sie Ihre Express-Anwendung so, dass sie die Autorisierungs-Middleware enthält. In diesem Beispiel verwenden wir Identitätstoken, aber Sie können auch Zugriffstoken verwenden. Weitere Informationen finden Sie authorization-for-expressjsunterGitHub.

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

Die Integration testen

Sie können Ihre Autorisierungsimplementierung testen, indem Sie Anfragen mit unterschiedlichen Benutzertoken an Ihre API-Endpunkte stellen. Die Autorisierungs-Middleware bewertet jede Anfrage automatisch anhand Ihrer definierten Richtlinien.

Wenn Sie beispielsweise verschiedene Benutzergruppen mit unterschiedlichen Berechtigungen eingerichtet haben:

Sie können überprüfen, ob die Berechtigungsrichtlinien erwartungsgemäß funktionieren, indem Sie sich mit verschiedenen Benutzern anmelden und verschiedene Vorgänge ausprobieren. Im Terminal für die Express-Anwendung finden Sie eine Protokollausgabe mit zusätzlichen Informationen zu den Autorisierungsentscheidungen.

Fehlerbehebung

Nächste Schritte

Nach der Implementierung der Basisintegration sollten Sie Folgendes in Betracht ziehen: