Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Mengintegrasikan Express dengan Izin Terverifikasi Amazon
Integrasi Verified Permissions Express menyediakan pendekatan berbasis middleware untuk menerapkan otorisasi dalam aplikasi Express.js Anda. Dengan integrasi ini, Anda dapat melindungi titik akhir API menggunakan kebijakan otorisasi berbutir halus tanpa mengubah penangan rute yang ada. Integrasi menangani pemeriksaan otorisasi secara otomatis dengan mencegat permintaan, mengevaluasinya terhadap kebijakan yang Anda tetapkan, dan memastikan bahwa hanya pengguna yang berwenang yang dapat mengakses sumber daya yang dilindungi.
Topik ini memandu Anda melalui pengaturan integrasi Express, mulai dari membuat toko kebijakan hingga menerapkan dan menguji middleware otorisasi. Dengan mengikuti langkah-langkah ini, Anda dapat menambahkan kontrol otorisasi yang kuat ke aplikasi Express Anda dengan sedikit perubahan kode.
Repo berikut GitHub direferensikan di seluruh topik ini:
+ [cedar-policy/ authorization-for-expressjs](https://github.com/cedar-policy/authorization-for-expressjs) - Middleware otorisasi Cedar untuk Express.js
+ [verifiedpermissions/ authorization-clients-js](https://github.com/verifiedpermissions/authorization-clients-js) - Klien otorisasi Izin Terverifikasi untuk JavaScript
+ [verifiedpermissions/examples/express-petstore](https://github.com/verifiedpermissions/examples/tree/main/express-petstore) - Contoh implementasi menggunakan middleware Express.js
## Prasyarat
Sebelum Anda menerapkan integrasi Express, pastikan Anda memiliki:
+ [AWS Akun](https://docs.aws.amazon.com/accounts/latest/reference/getting-started.html) dengan akses ke Izin Terverifikasi
+ [Node.js](https://nodejs.org/) dan [npm diinstal](https://docs.npmjs.com/)
+ Aplikasi [Express.js](https://expressjs.com/)
+ Penyedia identitas OpenID Connect (OIDC) (seperti) [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)dikonfigurasi dengan izin yang sesuai
## Menyiapkan integrasi
### Langkah 1: Buat toko kebijakan
Buat toko kebijakan menggunakan AWS CLI:
```
aws verifiedpermissions create-policy-store --validation-settings "mode=STRICT"
```
**catatan**
Simpan ID penyimpanan kebijakan yang dikembalikan dalam respons untuk digunakan pada langkah selanjutnya.
### Langkah 2: Instal dependensi
Instal paket yang diperlukan di aplikasi Express Anda:
```
npm i --save @verifiedpermissions/authorization-clients-js
npm i --save @cedar-policy/authorization-for-expressjs
```
## Mengkonfigurasi otorisasi
### Langkah 1: Buat dan unggah skema Cedar
Skema mendefinisikan model otorisasi untuk aplikasi, termasuk jenis entitas dalam aplikasi dan tindakan yang diizinkan untuk dilakukan pengguna. Kami merekomendasikan mendefinisikan [namespace](https://docs.cedarpolicy.com/overview/terminology.html#term-namespaces) untuk skema Anda. Dalam contoh ini, kami menggunakan `YourNamespace`. Anda melampirkan skema Anda ke penyimpanan kebijakan Izin Terverifikasi, dan ketika kebijakan ditambahkan atau diubah, layanan secara otomatis memvalidasi kebijakan terhadap skema.
`@cedar-policy/authorization-for-expressjs`Paket ini dapat menganalisis [spesifikasi OpenAPI](https://swagger.io/specification/) aplikasi Anda dan menghasilkan skema Cedar. Secara khusus, objek jalur diperlukan dalam spesifikasi Anda.
Jika Anda tidak memiliki spesifikasi OpenAPI, Anda dapat mengikuti instruksi cepat [express-openapi-generator](https://github.com/nklisch/express-openapi-generator)paket untuk menghasilkan spesifikasi OpenAPI.
Buat skema dari spesifikasi OpenAPI Anda:
```
npx @cedar-policy/authorization-for-expressjs generate-schema --api-spec schemas/openapi.json --namespace YourNamespace --mapping-type SimpleRest
```
Selanjutnya, format skema Cedar untuk digunakan dengan. AWS CLI Untuk informasi selengkapnya tentang format spesifik yang diperlukan, lihat[Skema toko kebijakan Izin Terverifikasi Amazon](schema.md). Jika Anda memerlukan bantuan untuk memformat skema, ada skrip yang dipanggil `prepare-cedar-schema.sh` di repo [GitHubverifiedpermissions/examples](https://github.com/verifiedpermissions/examples/tree/main/express-petstore/start/scripts). Berikut ini adalah contoh panggilan ke skrip yang mengeluarkan skema diformat Izin Terverifikasi dalam file. `v2.cedarschema.forAVP.json`
```
./scripts/prepare-cedar-schema.sh v2.cedarschema.json v2.cedarschema.forAVP.json
```
Unggah skema yang diformat ke toko kebijakan Anda, ganti `policy-store-id` dengan ID toko kebijakan Anda:
```
aws verifiedpermissions put-schema \
--definition file://v2.cedarschema.forAVP.json \
--policy-store-id policy-store-id
```
### Langkah 2: Buat kebijakan otorisasi
Jika tidak ada kebijakan yang dikonfigurasi, Cedar menolak semua permintaan otorisasi. Integrasi kerangka kerja Express membantu mem-bootstrap proses ini dengan menghasilkan contoh kebijakan berdasarkan skema yang dihasilkan sebelumnya.
Saat menggunakan integrasi ini dalam aplikasi produksi Anda, sebaiknya buat kebijakan baru menggunakan alat infrastruktur sebagai kode (iAAC). Untuk informasi selengkapnya, lihat [Membuat sumber daya Izin Terverifikasi Amazon dengan AWS CloudFormation](cloudformation-verified-permissions.md).
Hasilkan contoh kebijakan Cedar:
```
npx @cedar-policy/authorization-for-expressjs generate-policies --schema v2.cedarschema.json
```
Ini akan menghasilkan kebijakan sampel di `/policies` direktori. Anda kemudian dapat menyesuaikan kebijakan ini berdasarkan kasus penggunaan Anda. Contoh:
```
// 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
);
```
Format kebijakan untuk digunakan dengan AWS CLI. *Untuk informasi lebih lanjut tentang format yang diperlukan, lihat [create-policy dalam referensi](https://docs.aws.amazon.com/cli/latest/reference/verifiedpermissions/create-policy.html).AWS CLI * Jika Anda memerlukan bantuan untuk memformat kebijakan, ada skrip yang dipanggil `convert_cedar_policies.sh` di repo [verifiedpermissions/examples](https://github.com/verifiedpermissions/examples/tree/main/express-petstore/start/scripts)GitHub. Berikut ini adalah panggilan ke skrip itu:
```
./scripts/convert_cedar_policies.sh
```
Unggah kebijakan yang diformat ke Izin Terverifikasi, ganti `policy_1.json` dengan jalur dan nama file kebijakan Anda dan `policy-store-id` dengan ID penyimpanan kebijakan Anda:
```
aws verifiedpermissions create-policy \
--definition file://{{policies/json/policy_1.json}} \
--policy-store-id policy-store-id
```
### Langkah 3: Hubungkan penyedia identitas
Secara default, middleware otorisasi Izin Terverifikasi membaca Token Web JSON (JWT) yang disediakan dalam header otorisasi permintaan API untuk mendapatkan informasi pengguna. Izin Terverifikasi dapat memvalidasi token selain melakukan evaluasi kebijakan otorisasi.
Buat file konfigurasi sumber identitas bernama `identity-source-configuration.txt` yang terlihat seperti berikut dengan file Anda `userPoolArn` dan`clientId`:
```
{
"cognitoUserPoolConfiguration": {
"userPoolArn": "arn:aws:cognito-idp:region:account:userpool/pool-id",
"clientIds": ["client-id"],
"groupConfiguration": {
"groupEntityType": "YourNamespace::UserGroup"
}
}
}
```
Buat sumber identitas dengan menjalankan AWS CLI perintah berikut, ganti `policy-store-id` dengan ID toko kebijakan Anda:
```
aws verifiedpermissions create-identity-source \
--configuration file://identity-source-configuration.txt \
--policy-store-id policy-store-id \
--principal-entity-type YourNamespace::User
```
## Menerapkan middleware otorisasi
Perbarui aplikasi Express Anda untuk menyertakan middleware otorisasi. Dalam contoh ini kami menggunakan token identitas, tetapi Anda juga dapat menggunakan token akses. Untuk informasi lebih lanjut, lihat [authorization-for-expressjs](https://github.com/cedar-policy/authorization-for-expressjs)diGitHub.
```
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);
```
## Menguji integrasi
Anda dapat menguji implementasi otorisasi Anda dengan membuat permintaan ke titik akhir API Anda dengan token pengguna yang berbeda. Middleware otorisasi akan secara otomatis mengevaluasi setiap permintaan terhadap kebijakan yang Anda tetapkan.
Misalnya, jika Anda telah menyiapkan grup pengguna yang berbeda dengan izin yang berbeda:
+ Administrator: Akses penuh ke semua sumber daya dan fungsi manajemen
+ Karyawan: Dapat melihat, membuat, dan memperbarui sumber daya
+ Pelanggan: Hanya dapat melihat sumber daya
Anda dapat memvalidasi bahwa kebijakan izin berfungsi seperti yang diharapkan dengan masuk ke pengguna yang berbeda dan mencoba berbagai operasi. Di terminal untuk aplikasi Express, Anda dapat melihat output log yang memberikan rincian tambahan tentang keputusan otorisasi.
## Pemecahan masalah
Jika Anda mengalami kegagalan otorisasi, coba yang berikut ini:
+ Verifikasi ID toko kebijakan Anda benar
+ Pastikan sumber identitas Anda dikonfigurasi dengan benar
+ Periksa apakah kebijakan Anda telah diformat dengan benar
+ Validasi bahwa token JWT Anda valid
## Langkah selanjutnya
Setelah menerapkan integrasi dasar, pertimbangkan:
+ Menerapkan pemetaan khusus untuk skenario otorisasi tertentu
+ Menyiapkan pemantauan dan pencatatan untuk keputusan otorisasi
+ Membuat kebijakan tambahan untuk peran pengguna yang berbeda