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:
+ [cedar-policy/ authorization-for-expressjs](https://github.com/cedar-policy/authorization-for-expressjs) — Die Cedar-Autorisierungs-Middleware für Express.js
+ verifiedpermissions/ — Die [Verified Permissions-Autorisierungsclients für authorization-clients-js](https://github.com/verifiedpermissions/authorization-clients-js) JavaScript
+ [verifiedpermissions/examples/express-petstore — Beispielimplementierung mit](https://github.com/verifiedpermissions/examples/tree/main/express-petstore) der Middleware Express.js
## Voraussetzungen
Bevor Sie die Express-Integration implementieren, stellen Sie sicher, dass Sie über Folgendes verfügen:
+ Ein [AWS Konto](https://docs.aws.amazon.com/accounts/latest/reference/getting-started.html) mit Zugriff auf verifizierte Berechtigungen
+ [Node.js](https://nodejs.org/) und [npm](https://docs.npmjs.com/) sind installiert
+ Eine [Express.js](https://expressjs.com/) -Anwendung
+ Ein OpenID Connect (OIDC) -Identitätsanbieter (wie) [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)mit den entsprechenden Berechtigungen konfiguriert
## 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"
```
**Anmerkung**
Speichern Sie die in der Antwort zurückgegebene Policy Store-ID zur Verwendung in nachfolgenden Schritten.
### 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](https://docs.cedarpolicy.com/overview/terminology.html#term-namespaces) 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, und wenn Richtlinien hinzugefügt oder geändert werden, validiert der Service die Richtlinien automatisch anhand des Schemas.
Das `@cedar-policy/authorization-for-expressjs` Paket kann die [OpenAPI-Spezifikationen](https://swagger.io/specification/) 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-generator](https://github.com/nklisch/express-openapi-generator)Pakets 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 unter[Speicherschema für Richtlinien von Amazon Verified Permissions](schema.md). Wenn Sie Hilfe beim Formatieren des Schemas benötigen, gibt es ein Skript, das `prepare-cedar-schema.sh` im Repo [GitHubverifiedpermissions/examples](https://github.com/verifiedpermissions/examples/tree/main/express-petstore/start/scripts) 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](cloudformation-verified-permissions.md).
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. Beispiel:
```
// 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
);
```
Formatieren Sie die Richtlinien für die Verwendung mit dem AWS CLI. *Weitere Informationen zum erforderlichen Format finden Sie unter [create-policy](https://docs.aws.amazon.com/cli/latest/reference/verifiedpermissions/create-policy.html) 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](https://github.com/verifiedpermissions/examples/tree/main/express-petstore/start/scripts) 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 aussieht`clientId`:
```
{
"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-expressjs](https://github.com/cedar-policy/authorization-for-expressjs)unterGitHub.
```
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:
+ Administratoren: Voller Zugriff auf alle Ressourcen und Verwaltungsfunktionen
+ Mitarbeiter: Können Ressourcen anzeigen, erstellen und aktualisieren
+ Kunden: Sie können nur Ressourcen anzeigen
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
Wenn die Autorisierung fehlschlägt, versuchen Sie Folgendes:
+ Stellen Sie sicher, dass Ihre Policy Store-ID korrekt ist
+ Stellen Sie sicher, dass Ihre Identitätsquelle richtig konfiguriert ist
+ Vergewissern Sie sich, dass Ihre Richtlinien korrekt formatiert sind
+ Stellen Sie sicher, dass Ihre JWT-Token gültig sind
## Nächste Schritte
Nach der Implementierung der Basisintegration sollten Sie Folgendes in Betracht ziehen:
+ Implementierung benutzerdefinierter Mapper für bestimmte Autorisierungsszenarien
+ Einrichtung der Überwachung und Protokollierung von Autorisierungsentscheidungen
+ Erstellung zusätzlicher Richtlinien für verschiedene Benutzerrollen