Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Kirim atribut khusus ke Amazon Cognito dan masukkan ke dalam token *Carlos Alessandro Ribeiro dan Mauricio Mendoza, Amazon Web Services* ## Ringkasan Mengirim atribut khusus ke proses autentikasi Amazon Cognito dapat memberikan konteks tambahan ke aplikasi, mengaktifkan kontrol akses yang lebih terperinci, dan mempermudah pengelolaan profil pengguna dan persyaratan otentikasi. Fitur-fitur ini berguna dalam berbagai aplikasi dan skenario, dan mereka dapat membantu Anda meningkatkan keamanan dan fungsionalitas aplikasi secara keseluruhan. Pola ini menunjukkan cara mengirim atribut khusus ke proses otentikasi Amazon Cognito saat aplikasi perlu memberikan konteks tambahan ke [token akses atau token](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-access-token.html) [identitas (ID)](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-id-token.html). Anda menggunakan Node.js sebagai aplikasi backend. Aplikasi ini mengautentikasi pengguna dari kumpulan [pengguna Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools.html) dan meneruskan atribut khusus yang diperlukan untuk pembuatan token. Anda dapat menggunakan [AWS Lambda pemicu](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-working-with-lambda-triggers.html) untuk Amazon Cognito untuk menyesuaikan proses otentikasi Anda tanpa penyesuaian kode utama atau upaya yang signifikan. **penting** Kode dan sampel dalam pola ini tidak direkomendasikan untuk beban kerja produksi karena ditujukan untuk tujuan demonstrasi saja. Untuk beban kerja produksi, konfigurasi tambahan diperlukan di sisi klien. Gunakan pola ini sebagai referensi untuk pilot atau proof-of-concept tujuan saja. ## Prasyarat dan batasan **Prasyarat** + Aktif Akun AWS + Izin untuk membuat dan mengelola kumpulan dan fungsi pengguna Amazon Cognito AWS Lambda + AWS Command Line Interface (AWS CLI), [diinstal](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) dan [dikonfigurasi](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) + Lingkungan pengembangan terintegrasi (IDE) yang mendukung Node.js + Node.js versi 18 atau yang lebih baru, [diinstal](https://nodejs.org/en/download/) + [npm versi 8 atau yang lebih baru, diinstal](https://docs.npmjs.com/getting-started) + TypeScript, [dipasang](https://www.typescriptlang.org/download/) **Batasan** + Pola ini tidak berlaku untuk integrasi aplikasi melalui alur otentikasi Client Credentials. + Pemicu pembuatan pra-token hanya dapat menambah atau mengubah beberapa atribut token akses dan token identitas. Untuk informasi selengkapnya, lihat [Pemicu Lambda pra pembuatan token](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html) di dokumentasi Amazon Cognito. ## Arsitektur **Arsitektur target** Diagram berikut menunjukkan arsitektur target untuk pola ini. Ini juga menunjukkan bagaimana aplikasi Node.js dapat bekerja dengan backend untuk memperbarui database. Namun, pembaruan basis data backend berada di luar cakupan pola ini. ![Aplikasi Node.js yang mengeluarkan token akses dengan atribut khusus ke kumpulan pengguna Amazon Cognito.](http://docs.aws.amazon.com/id_id/prescriptive-guidance/latest/patterns/images/pattern-img/9f0855e6-77f9-48c2-846e-f9c317127e1f/images/8c52c88b-8954-4b4c-aed3-fd8c22f84c1d.png) Diagram menunjukkan alur kerja berikut: 1. Aplikasi Node.js mengeluarkan token akses dengan atribut khusus ke kumpulan pengguna Amazon Cognito. 1. Kumpulan pengguna Amazon Cognito memulai fungsi Lambda generasi pra-token, yang menyesuaikan akses dan token ID. 1. Aplikasi Node.js melakukan panggilan API melalui Amazon API Gateway. **catatan** Komponen arsitektur lain yang ditunjukkan dalam arsitektur ini misalnya saja dan berada di luar cakupan pola ini. **Otomatisasi dan skala** Anda dapat mengotomatiskan penyediaan kumpulan pengguna Amazon Cognito, AWS Lambda fungsi, instance database, dan sumber daya lainnya dengan menggunakan, [HashiCorp Terraform [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)](https://www.terraform.io/docs), atau alat infrastruktur [AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/v2/guide/home.html)sebagai kode (IAc) yang didukung. Jika Anda ingin menskalakan penerapan Anda, gunakan pipeline integrasi berkelanjutan dan pengiriman berkelanjutan (CI/CD), yang membantu mencegah kesalahan yang terkait dengan penerapan manual. ## Alat **Layanan AWS** + [Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html) membantu Anda membuat, menerbitkan, memelihara, memantau, dan mengamankan REST, HTTP, dan WebSocket APIs dalam skala apa pun. + [Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/what-is-amazon-cognito.html) menyediakan otentikasi, otorisasi, dan manajemen pengguna untuk aplikasi web dan seluler. + [Amazon Elastic Container Service (Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html)) adalah layanan manajemen kontainer yang cepat dan dapat diskalakan yang membantu Anda menjalankan, menghentikan, dan mengelola kontainer di klaster. + [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)adalah layanan komputasi yang membantu Anda menjalankan kode tanpa perlu menyediakan atau mengelola server. Ini menjalankan kode Anda hanya bila diperlukan dan skala secara otomatis, jadi Anda hanya membayar untuk waktu komputasi yang Anda gunakan. + [AWS SDK untuk JavaScript](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html)menyediakan JavaScript API untuk Layanan AWS. Anda dapat menggunakannya untuk membangun pustaka atau aplikasi untuk Node.js atau browser. **Alat-alat lainnya** + [Node.js](https://nodejs.org/en/docs/) adalah lingkungan JavaScript runtime berbasis peristiwa yang dirancang untuk membangun aplikasi jaringan yang dapat diskalakan. + [npm](https://docs.npmjs.com/about-npm) adalah registri perangkat lunak yang berjalan di lingkungan Node.js dan digunakan untuk berbagi atau meminjam paket dan mengelola penyebaran paket pribadi. ## Praktik terbaik Kami menyarankan Anda menerapkan praktik terbaik berikut: + **Rahasia dan data sensitif** — Jangan menyimpan rahasia atau data sensitif dalam aplikasi. Gunakan sistem eksternal tempat aplikasi dapat menarik data dari, seperti [AWS AppConfig[AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)](https://docs.aws.amazon.com/appconfig/latest/userguide/what-is-appconfig.html), atau [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html). + **Penerapan standar** — Gunakan CI/CD pipeline untuk menyebarkan aplikasi Anda. Anda dapat menggunakan layanan seperti [AWS CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/welcome.html)dan [AWS CodePipeline](https://docs.aws.amazon.com/codepipeline/latest/userguide/welcome.html). + **Token kedaluwarsa** — Tetapkan tanggal kedaluwarsa singkat untuk token akses. + **Gunakan koneksi aman** — Semua komunikasi antara aplikasi klien dan backend harus dienkripsi dengan menggunakan SSL/TLS. Gunakan [AWS Certificate Manager (ACM)](https://docs.aws.amazon.com/acm/latest/userguide/acm-overview.html) untuk membuat dan mengelola SSL/TLS sertifikat, dan gunakan [Amazon CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Introduction.html) atau [Elastic Load](https://docs.aws.amazon.com/elasticloadbalancing/latest/userguide/what-is-load-balancing.html) Balancing untuk SSL/TLS menangani penghentian. + **Validasi input pengguna** — Pastikan semua input pengguna divalidasi untuk mencegah serangan injeksi dan kerentanan keamanan lainnya. Gunakan pustaka validasi input dan layanan seperti Amazon API Gateway dan [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/what-is-aws-waf.html#waf-intro)untuk mencegah vektor serangan umum. + **Gunakan peran IAM — Gunakan peran AWS Identity and Access Management ** [(IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) untuk mengontrol akses ke AWS sumber daya dan memastikan bahwa hanya pengguna yang berwenang yang memiliki akses. Ikuti prinsip hak istimewa paling sedikit dan pastikan bahwa setiap pengguna hanya memiliki izin yang diperlukan untuk melakukan peran mereka. + **Gunakan kebijakan kata sandi** — Konfigurasikan kebijakan kata sandi yang memenuhi persyaratan keamanan Anda, seperti panjang minimum, kompleksitas, dan kedaluwarsa. Gunakan Secrets Manager atau AWS Systems Manager Parameter Store untuk menyimpan dan mengelola kata sandi dengan aman. + **Aktifkan otentikasi multi-faktor (MFA) —** Aktifkan MFA bagi semua pengguna untuk menyediakan lapisan keamanan tambahan dan mengurangi risiko akses yang tidak sah. Gunakan [AWS IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html)atau Amazon Cognito untuk mengaktifkan MFA dan metode otentikasi lainnya. + **Simpan informasi sensitif dengan aman** — Simpan informasi sensitif, seperti kata sandi dan token akses, dengan aman menggunakan [AWS Key Management Service (AWS KMS)](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html) atau layanan enkripsi lainnya. + **Gunakan metode otentikasi yang kuat** — Untuk meningkatkan keamanan proses otentikasi, gunakan metode otentikasi yang kuat, seperti otentikasi biometrik atau otentikasi multi-faktor. + **Memantau aktivitas yang mencurigakan** — Gunakan [AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html)dan alat pemantauan lainnya untuk memantau aktivitas mencurigakan dan potensi ancaman keamanan. Siapkan peringatan otomatis untuk aktivitas yang tidak biasa, dan gunakan [Amazon GuardDuty](https://docs.aws.amazon.com/guardduty/latest/ug/what-is-guardduty.html) atau [AWS Security Hub CSPM](https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub.html)untuk mendeteksi potensi ancaman. + **Tinjau dan perbarui kebijakan keamanan** secara berkala — Tinjau dan perbarui kebijakan dan prosedur keamanan Anda secara teratur untuk memastikan bahwa kebijakan tersebut memenuhi persyaratan keamanan dan praktik terbaik Anda yang berubah. Gunakan AWS Config untuk melacak dan mengaudit perubahan pada kebijakan dan prosedur keamanan Anda. + **Pendaftaran otomatis** — Jangan aktifkan pendaftaran otomatis ke kumpulan pengguna Amazon Cognito. Untuk informasi selengkapnya, lihat [Mengurangi risiko penipuan pendaftaran pengguna dan pemompaan SMS dengan kumpulan pengguna Amazon Cognito](https://aws.amazon.com/blogs/security/reduce-risks-of-user-sign-up-fraud-and-sms-pumping-with-amazon-cognito-user-pools/)AWS (posting blog). Untuk praktik terbaik tambahan, lihat [Praktik terbaik keamanan untuk kumpulan pengguna Amazon Cognito di dokumentasi](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-security-best-practices.html) Amazon Cognito. ## Epik ### Siapkan sumber AWS daya | Tugas | Deskripsi | Keterampilan yang dibutuhkan | | --- | --- | --- | | Membuat pengguna. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/id_id/prescriptive-guidance/latest/patterns/send-custom-attributes-cognito.html)Untuk informasi selengkapnya dan petunjuk tentang cara menyiapkan kumpulan pengguna di Konsol Manajemen AWS, lihat [Memulai kumpulan pengguna dan Menambahkan](https://docs.aws.amazon.com/cognito/latest/developerguide/getting-started-user-pools.html) [lebih banyak fitur dan opsi keamanan ke kumpulan pengguna Anda](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-next-steps.html).Untuk mengurangi biaya, gunakan paket Essentials atau paket Lite untuk menguji pola ini. Untuk informasi selengkapnya, lihat [harga Amazon Cognito](https://aws.amazon.com/cognito/pricing/). | Pengembang aplikasi, AWS DevOps | | Tambahkan pengguna ke kumpulan pengguna. | Masukkan perintah berikut untuk membuat satu pengguna di kumpulan pengguna Amazon Cognito:
aws cognito-idp sign-up \
   --client-id  \
   --username  \
   --password  \
   --user-attributes Name="email",Value="" Name="name",Value=""
| Pengembang aplikasi, AWS DevOps | | Tambahkan klien aplikasi ke kumpulan pengguna. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/id_id/prescriptive-guidance/latest/patterns/send-custom-attributes-cognito.html) | Administrator sistem AWS, administrator AWS, AWS DevOps, Pengembang aplikasi | | Buat pemicu Lambda untuk pembuatan pra-token. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/id_id/prescriptive-guidance/latest/patterns/send-custom-attributes-cognito.html) | AWS DevOps, Pengembang aplikasi | | Sesuaikan alur kerja kumpulan pengguna. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/id_id/prescriptive-guidance/latest/patterns/send-custom-attributes-cognito.html)Untuk informasi selengkapnya, lihat [Menyesuaikan alur kerja kumpulan pengguna dengan pemicu Lambda di](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-working-with-lambda-triggers.html) dokumentasi Amazon Cognito. | AWS DevOps, Pengembang aplikasi | ### Buat aplikasi Node.js | Tugas | Deskripsi | Keterampilan yang dibutuhkan | | --- | --- | --- | | Buat aplikasi Node.js. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/id_id/prescriptive-guidance/latest/patterns/send-custom-attributes-cognito.html) | Pengembang aplikasi | | Menerapkan logika otentikasi. | [See the AWS documentation website for more details](http://docs.aws.amazon.com/id_id/prescriptive-guidance/latest/patterns/send-custom-attributes-cognito.html)Anda dapat membuat TypeScript file Anda sendiri atau memodifikasi sampel yang disediakan sesuai kebutuhan untuk kasus penggunaan Anda. | Pengembang aplikasi | | Konfigurasikan variabel lingkungan dan file konfigurasi. | Di terminal, masukkan perintah berikut untuk membuat variabel lingkungan:
export USERNAME=""
export PASSWORD=""
export USER_POOL_ID=""
export CLIENT_ID=""
Jangan membuat hardcode rahasia atau mengekspos kredensialmu. | Pengembang aplikasi | | Jalankan aplikasi. | Masukkan perintah berikut untuk menjalankan aplikasi dan konfirmasikan bahwa itu berfungsi:
npm run build
npm start
| Pengembang aplikasi | | Konfirmasikan bahwa atribut khusus disuntikkan ke token. | Gunakan fitur debugging untuk IDE Anda untuk melihat akses dan token ID. Konfirmasikan bahwa atribut kustom telah ditambahkan. Untuk contoh token, lihat bagian [Informasi tambahan](#send-custom-attributes-cognito-additional) dari pola ini. | Pengembang aplikasi | ## Pemecahan masalah | Isu | Solusi | | --- | --- | | ID klien tidak valid saat mencoba mengautentikasi pengguna | Kesalahan ini biasanya terjadi ketika Anda menggunakan ID klien dengan rahasia klien yang dihasilkan. Anda harus membuat ID klien tanpa rahasia yang melekat padanya. Untuk informasi selengkapnya, lihat [Pengaturan khusus aplikasi dengan klien aplikasi](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-client-apps.html). | ## Sumber daya terkait + [Menyesuaikan alur kerja kumpulan pengguna dengan pemicu Lambda (](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools-working-with-aws-lambda-triggers.html)dokumentasi Amazon Cognito) + [Pemicu Lambda generasi pra token (dokumentasi](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html) Amazon Cognito) + [CognitoIdentityProviderClient](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cognito-identity-provider/)(AWS SDK untuk JavaScript dokumentasi) + [cognito-idp](https://awscli.amazonaws.com/v2/documentation/api/2.0.34/reference/cognito-idp/index.html#cli-aws-cognito-idp) (dokumentasi)AWS CLI ## Informasi tambahan **Contoh TypeScript berkas** Contoh kode berikut adalah TypeScript file yang memanggil proses otentikasi menggunakan AWS SDK untuk mengirim atribut kustom ke Amazon Cognito: ``` import * as AmazonCognitoIdentity from "amazon-cognito-identity-js"; const userPoolId: string = process.env.USER_POOL_ID ?? ''; const clientId: string = process.env.CLIENT_ID ?? ''; const poolData = { UserPoolId: userPoolId, ClientId: clientId }; const userPool = new AmazonCognitoIdentity.CognitoUserPool(poolData); export const loginWithCognitoSDK = function (userName: string, password: string) { const authenticationDetails = new AmazonCognitoIdentity.AuthenticationDetails({ Username: userName, Password: password, ClientMetadata: { customGroup: "MyCustomGroup", customApplicationData: "Custom data from a custom application" } }); const userData = { Username: userName, Pool: userPool }; const cognitoUser = new AmazonCognitoIdentity.CognitoUser(userData); // Authenticate the user using the authenticationDetails object cognitoUser.authenticateUser(authenticationDetails, { onSuccess: function (result: any) {}, onFailure: function (err: any) {}, }); } loginWithCognitoSDK(process.env.USERNAME ?? '', process.env.PASSWORD ?? ''); ``` Sampel menggunakan `AuthenticationDetails` model dari SDK JavaScript untuk memberikan nama pengguna, kata sandi, dan file. `ClientMetadada` Setelah otentikasi di Amazon Cognito, metadata klien dapat diambil dari token akses dan ID. **Contoh fungsi Lambda** Contoh kode berikut adalah fungsi Lambda yang ditautkan ke [Token Pra-Generasi dari Amazon](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools-working-with-aws-lambda-triggers.html) Cognito. Ini membantu Anda menyesuaikan token akses dan token ID yang digunakan Amazon Cognito. Token dilewatkan melalui integrasi antara arsitektur Anda. Contoh ini mencakup atribut klaim kustom yang dipanggil `customApplicationData` dan nama grup kustom yang disebut`MyCustomGroup`: ``` export const handler = async(event, context, callback) => { event.response = { claimsOverrideDetails: { claimsToAddOrOverride: { customApplicationData: event.request.clientMetadata.customApplicationData }, groupOverrideDetails: { groupsToOverride: [event.request.clientMetadata.customGroup] } } }; callback(null, event); }; ``` **Contoh token akses** Anda dapat memecahkan kode token akses untuk memvisualisasikan atribut kustom yang ditambahkan. Berikut ini adalah contoh token akses: ``` { "sub": "6daf331f-4451-48b4-abde-774579299204", "cognito:groups": [ "MyCustomGroup" ], "iss": "https://cognito-idp..amazonaws.com/", "client_id": "", "origin_jti": "acff7e91-09f9-4fde-8eec-38b0f8c47cdc", "event_id": "c5113a9c-1f01-435b-9b73-a5cd3e88514e", "token_use": "access", "scope": "aws.cognito.signin.user.admin", "auth_time": 1677979246, "exp": 1677982846, "iat": 1677979246, "jti": "5c9c2708-a871-4428-bd9b-18ad261bea90", "username": "" } ``` **Contoh ID token** Anda dapat memecahkan kode token akses untuk memvisualisasikan atribut kustom yang ditambahkan. Berikut ini adalah contoh token akses: ``` { "sub": "6daf331f-4451-48b4-abde-774579299204", "cognito:groups": [ "MyCustomGroup" ], "iss": "https://cognito-idp..amazonaws.com/", "cognito:username": "", "origin_jti": "acff7e91-09f9-4fde-8eec-38b0f8c47cdc", "customApplicationData": "Custom data from a custom application", "aud": "", "event_id": "c5113a9c-1f01-435b-9b73-a5cd3e88514e", "token_use": "id", "auth_time": 1677979246, "exp": 1677982846, "iat": 1677979246, "jti": "f7ca006b-f25b-44d2-a7a4-6e6423f4201f", "email": "" } ```