概要前提条件と制限アーキテクチャツールベストプラクティスエピックトラブルシューティング関連リソース追加情報

Amazon Cognito にカスタム属性を送信し、トークンに挿入する

Carlos Alessandro ribeiro と Mauricio Mendoza、Amazon Web Services

概要

Amazon Cognito 認証プロセスにカスタム属性を送信すると、アプリケーションに追加のコンテキストが提供され、より詳細なアクセスコントロールが可能になり、ユーザープロファイルと認証要件の管理が容易になります。これらの機能は、さまざまなアプリケーションやシナリオで有用であり、アプリケーションの全体的なセキュリティと機能を向上させるのに役立ちます。

このパターンは、アプリケーションがアクセストークンまたは ID (ID) トークンに追加のコンテキストを提供する必要がある場合に、Amazon Cognito 認証プロセスにカスタム属性を送信する方法を示しています。Node.js をバックエンドアプリケーションとして使用します。アプリケーションは Amazon Cognito ユーザープールからユーザーを認証し、トークン生成に必要なカスタム属性を渡します。Amazon Cognito AWS Lambda のトリガーを使用して、コードの大幅なカスタマイズや多大な労力をかけずに認証プロセスをカスタマイズできます。

重要

このパターンのコードとサンプルは、デモンストレーションのみを目的としているため、本番ワークロードには推奨されません。本番ワークロードの場合、クライアント側で追加の設定が必要です。このパターンは、パイロットまたはproof-of-conceptの目的でのみ参照してください。

前提条件と制限

前提条件

アクティブな AWS アカウント
Amazon Cognito ユーザープールと AWS Lambda 関数を作成および管理するためのアクセス許可
AWS Command Line Interface （AWS CLI）、インストールおよび設定済み
Node.js をサポートする統合開発環境 (IDE)
Node.js バージョン 18 以降、インストール済み
npm バージョン 8 以降、インストール済み
TypeScript、インストール済み

制約事項

このパターンは、クライアント認証情報認証フローを介したアプリケーション統合には適用されません。
トークン生成前トリガーは、アクセストークンと ID トークンの一部の属性のみを追加または変更できます。詳細については、Amazon Cognito ドキュメントの「トークン生成前 Lambda トリガー」を参照してください。

アーキテクチャ

ターゲットアーキテクチャ

次の図は、このパターンのターゲットアーキテクチャを示しています。また、Node.js アプリケーションがバックエンドと連携してデータベースを更新する方法も示します。ただし、バックエンドデータベースの更新はこのパターンの範囲外です。

Amazon Cognito ユーザープールにカスタム属性を持つアクセストークンを発行する Node.js アプリケーション。

この図表は、次のワークフローを示しています：

Node.js アプリケーションは、カスタム属性を持つアクセストークンを Amazon Cognito ユーザープールに発行します。
Amazon Cognito ユーザープールは、アクセストークンと ID トークンをカスタマイズするトークン生成前の Lambda 関数を開始します。
Node.js アプリケーションは、Amazon API Gateway を介して API コールを行います。

注記

このアーキテクチャに表示される他のアーキテクチャコンポーネントは、例えばのみであり、このパターンの対象外です。

自動化とスケール

、、HashiCorp Terraform、またはサポートされているInfrastructure as Code (IaC) ツールを使用して、Amazon Cognito ユーザープール、 AWS Lambda 関数AWS CloudFormation AWS Cloud Development Kit (AWS CDK)、データベースインスタンス、およびその他のリソースのプロビジョニングを自動化できます。デプロイをスケールする場合は、継続的インテグレーションおよび継続的デリバリー (CI/CD) パイプラインを使用します。これにより、手動デプロイに関連するエラーを防ぐことができます。

ツール

AWS のサービス

「Amazon API Gateway」は、任意のスケールで REST、HTTP、WebSocket API を作成、公開、維持、監視、保護する上で役立ちます。
Amazon Cognito は、ウェブおよびモバイルアプリの認証、認可、ユーザー管理を提供します。
「Amazon Elastic Container Service (Amazon ECS)」は、クラスターでのコンテナの実行、停止、管理を支援する、高速でスケーラブルなコンテナ管理サービスです。
AWS Lambda は、サーバーのプロビジョニングや管理を行うことなくコードを実行できるコンピューティングサービスです。必要に応じてコードを実行し、自動的にスケーリングするため、課金は実際に使用したコンピューティング時間に対してのみ発生します。
AWS SDK for JavaScript は JavaScript API を提供します AWS のサービス。これを使用して、Node.js またはブラウザ用のライブラリまたはアプリケーションを構築できます。

その他のツール

Node.js は、スケーラブルなネットワークアプリケーションを構築するために設計されたイベント駆動型の JavaScript ランタイム環境です。
npm は Node.js 環境で動作するソフトウェアレジストリで、パッケージの共有や借用、プライベートパッケージのデプロイ管理に使用されます。

ベストプラクティス

以下のベストプラクティスを実装することをお勧めします。

シークレットと機密データ – アプリケーション内にシークレットや機密データを保存しないでください。、、または AWS Systems Manager Parameter Store などAWS AppConfig AWS Secrets Manager、アプリケーションがデータを取得できる外部システムを使用します。
標準化されたデプロイ — CI/CD パイプラインを使用してアプリケーションをデプロイします。AWS CodeBuild やなどのサービスを使用できますAWS CodePipeline。
トークンの有効期限 – アクセストークンの短い有効期限を設定します。
安全な接続を使用する – クライアントアプリケーションとバックエンド間のすべての通信は、SSL/TLS を使用して暗号化する必要があります。AWS Certificate Manager (ACM) を使用して SSL/TLS 証明書を生成および管理し、Amazon CloudFront または Elastic Load Balancing を使用して SSL/TLS の終了を処理します。
ユーザー入力の検証 – インジェクション攻撃やその他のセキュリティの脆弱性を防ぐために、すべてのユーザー入力が検証されていることを確認します。Amazon API Gateway やなどの入力検証ライブラリとサービスAWS WAFを使用して、一般的な攻撃ベクトルを防止します。
IAM ロールを使用する – AWS Identity and Access Management (IAM) ロールを使用して AWS リソースへのアクセスを制御し、承認されたユーザーのみがアクセスできるようにします。最小特権の原則に従い、各ユーザーにロールを実行するために必要なアクセス許可のみがあることを確認します。
パスワードポリシーを使用する – 最小長、複雑さ、有効期限などのセキュリティ要件を満たすパスワードポリシーを設定します。Secrets Manager または AWS Systems Manager Parameter Store を使用して、パスワードを安全に保存および管理します。
多要素認証 (MFA) を有効にする – すべてのユーザーが MFA を有効にしてセキュリティを強化し、不正アクセスのリスクを軽減します。AWS IAM Identity Center または Amazon Cognito を使用して、MFA やその他の認証方法を有効にします。
機密情報を安全に保存する – AWS Key Management Service （AWS KMS）やその他の暗号化サービスを使用して、パスワードやアクセストークンなどの機密情報を安全に保存します。
強力な認証方法を使用する – 認証プロセスのセキュリティを強化するには、生体認証や多要素認証などの強力な認証方法を使用します。
疑わしいアクティビティのモニタリング – AWS CloudTrailおよびその他のモニタリングツールを使用して、疑わしいアクティビティや潜在的なセキュリティ脅威をモニタリングします。異常なアクティビティの自動アラートを設定し、Amazon GuardDuty またはを使用して潜在的な脅威を検出AWS Security Hubします。
セキュリティポリシーを定期的に見直して更新する – セキュリティポリシーと手順を定期的に見直して更新し、変化するセキュリティ要件とベストプラクティスを満たしていることを確認します。を使用して AWS Config 、セキュリティポリシーと手順の変更を追跡および監査します。
自動サインアップ – Amazon Cognito ユーザープールへの自動サインアップを有効にしないでください。詳細については、Amazon Cognito ユーザープールによるユーザーサインアップ詐欺と SMS ポンピングのリスクを軽減する」（AWS ブログ記事) を参照してください。

その他のベストプラクティスについては、Amazon Cognito ドキュメントの「Amazon Cognito ユーザープールのセキュリティのベストプラクティス」を参照してください。 Amazon Cognito

エピック

タスク	説明	必要なスキル
ユーザープールを作成します。	CLI ターミナルで、次のコマンドを入力して Amazon Cognito ユーザープールを作成します。 `aws cognito-idp create-user-pool \ --pool-name <MyUserPool>` 次のコマンドを入力して、SDK for JavaScript で使用するクライアント ID とシークレットを作成します。 `aws cognito-idp create-user-pool-client \ --user-pool-id <UserPoolID> \ --client-name <MyNewClient> \ --no-generate-secret \ --explicit-auth-flows "USER_PASSWORD_AUTH" "ADMIN_NO_SRP_AUTH"` でユーザープールを設定する方法の詳細と手順については AWS Management Console、「ユーザープールの開始方法」および「ユーザープールに機能とセキュリティオプションを追加する」を参照してください。 https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-next-steps.html ヒントコストを削減するには、Essentials プランまたは Lite プランを使用してこのパターンをテストします。詳細については、「Amazon Cognito 料金」を参照してください。	アプリ開発者、AWS DevOps
ユーザープールにユーザーを追加します。	次のコマンドを入力して、Amazon Cognito ユーザープールに 1 人のユーザーを作成します。 `aws cognito-idp sign-up \ --client-id <ClientID> \ --username <jane@example.com> \ --password <PASSWORD> \ --user-attributes Name="email",Value="<jane@example.com>" Name="name",Value="<Jane>"`	アプリ開発者、AWS DevOps
アプリケーションクライアントをユーザープールに追加します。	Amazon Cognitoコンソールに移動します。 [User pools] (ユーザープール) を選択します。前に作成したユーザープールを選択します。「アプリケーションの定義」で、認証および認可サービスを作成するアプリケーションシナリオに最適なアプリケーションタイプを選択します。「アプリケーションの名前」で、わかりやすい名前を入力するか、デフォルト名に進みます。「戻り URL の追加」に、ユーザーが認証を完了した後ののアプリケーションへのリダイレクトパスを入力します。アプリケーションの作成を選択します。アドバンストオプションは、アプリケーションクライアントの作成後に設定できます。	AWS システム管理者、AWS 管理者、AWS DevOps、アプリ開発者
トークン生成前の Lambda トリガーを作成します。	Lambda コンソールの [関数] ページを開きます。 [関数の作成] を選択してください。 [一から作成] を選択します。 Basic informationpane の forFunction name に「」と入力します`myPreTokenGenerationLambdaFunction`。ランタイムの場合は、Node.js 22 を選択します。 Leavearchitectureset tox86_64。 [関数の作成] を選択してください。 Code タブの Code Source の下に、このパターンの Additional resources セクションからサンプル Lambda 関数を入力します。この Lambda 関数は、カスタム属性を ID トークンとアクセストークンに挿入します。	AWS DevOps、アプリケーション開発者
ユーザープールのワークフローをカスタマイズします。	Amazon Cognitoコンソールに移動します。 [User pools] (ユーザープール) を選択します。前に作成したユーザープールを選択します。左側のナビゲーションペインの Authentication で、Extensions を選択します。 Lambda トリガーの追加を選択します。トークン生成前トリガーを追加または編集します。トリガータイプで、認証を選択します。認証で、トークン生成前トリガーを選択します。 Lambda 関数を指定するには、を選択します`myPreTokenGenerationLambdaFunction`。 Lambda トリガーの追加を選択します。基本機能のトリガーイベントバージョン + ユーザー ID のアクセストークンのカスタマイズまたはユーザー ID とマシン ID のアクセストークンのカスタマイズを選択します。この設定により、Amazon Cognito が関数に送信するリクエストパラメータが更新され、アクセストークンをカスタマイズするためのフィールドが含まれるようになります。詳細については、Amazon Cognito ドキュメントの「Lambda トリガーを使用したユーザープールワークフローのカスタマイズ」を参照してください。	AWS DevOps、アプリケーション開発者

タスク	説明	必要なスキル
Node.js アプリケーションを作成します。	ターミナルで、次のコマンドを入力します。 `mkdir my-app cd my-app npm init -y npm install --save-dev typescript npm i --save-dev @types/node npm i amazon-cognito-identity-js npx tsc --init mkdir src touch src/index.ts` `package.json`ファイルを変更して TypeScript コンパイルスクリプトを含めます。 `"scripts": { "start": "node src/index.js", "build": "tsc" },`	アプリ開発者
認証ロジックを実装します。	`index.ts` ファイルを開きます。このパターンの「追加リソース」セクションにあるサンプル Typescript を貼り付けます。 `index.ts` ファイルを保存して閉じます。注記独自の TypeScript ファイルを作成することも、ユースケースに応じて提供されたサンプルを変更することもできます。	アプリ開発者
環境変数と設定ファイルを設定します。	ターミナルで、次のコマンドを入力して環境変数を作成します。 `export USERNAME="<COGNITO_USER_NAME>" export PASSWORD="<COGNITO_USER_PASSWORD>" export USER_POOL_ID="<COGNITO_USER_ID>" export CLIENT_ID="<COGNITO_CLIENT_ID>"` 重要シークレットをハードコードしたり、認証情報を公開したりしないでください。	アプリ開発者
アプリケーションを実行します。	次のコマンドを入力してアプリケーションを実行し、アプリケーションが動作していることを確認します。 `npm run build npm start`	アプリ開発者
カスタム属性がトークンに挿入されていることを確認します。	IDE のデバッグ機能を使用して、アクセストークンと ID トークンを表示します。カスタム属性が追加されていることを確認します。サンプルトークンについては、このパターンの追加情報「追加情報」セクションを参照してください。	アプリ開発者

トラブルシューティング

問題	ソリューション
ユーザーの認証時に無効なクライアント ID	このエラーは通常、生成されたクライアントシークレットでクライアント ID を使用している場合に発生します。シークレットをアタッチせずにクライアント ID を作成する必要があります。詳細については、「アプリケーションクライアントでのアプリケーション固有の設定」を参照してください。

問題

ソリューション

ユーザーの認証時に無効なクライアント ID

このエラーは通常、生成されたクライアントシークレットでクライアント ID を使用している場合に発生します。シークレットをアタッチせずにクライアント ID を作成する必要があります。詳細については、「アプリケーションクライアントでのアプリケーション固有の設定」を参照してください。

追加情報

サンプル TypeScript ファイル

次のコードサンプルは、 AWS SDK を使用して Amazon Cognito にカスタム属性を送信することで認証プロセスを呼び出す TypeScript ファイルです。


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

このサンプルでは、SDK for JavaScript のAuthenticationDetailsモデルを使用して、ユーザー名、パスワード、およびを提供しますClientMetadada。Amazon Cognito での認証後、アクセストークンと ID トークンからクライアントメタデータを取得できます。

サンプル Lambda 関数

次のコードサンプルは、Amazon Cognito から生成前トークンにリンクされた Lambda 関数です。Amazon Cognito が使用するアクセストークンと ID トークンをカスタマイズするのに役立ちます。トークンは、アーキテクチャ間の統合を介して渡されます。このサンプルには、というカスタムクレーム属性customApplicationDataとというカスタムグループ名が含まれています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);
};

サンプルアクセストークン

アクセストークンをデコードして、追加されたカスタム属性を視覚化できます。以下は、アクセストークンのサンプルです。


{
  "sub": "6daf331f-4451-48b4-abde-774579299204",
  "cognito:groups": [
    "MyCustomGroup"
  ],
  "iss": "https://cognito-idp.<REGION>.amazonaws.com/<USERPOOL_ID>",
  "client_id": "<YOUR_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": "<USER_NAME>"
}

サンプル ID トークン

アクセストークンをデコードして、追加されたカスタム属性を視覚化できます。以下は、アクセストークンのサンプルです。


{
  "sub": "6daf331f-4451-48b4-abde-774579299204",
  "cognito:groups": [
    "MyCustomGroup"
  ],
  "iss": "https://cognito-idp.<REGION>.amazonaws.com/<USERPOOL_ID>",
  "cognito:username": "<USER_NAME>",
  "origin_jti": "acff7e91-09f9-4fde-8eec-38b0f8c47cdc",
  "customApplicationData": "Custom data from a custom application",
  "aud": "<YOUR_CLIENT_ID>",
  "event_id": "c5113a9c-1f01-435b-9b73-a5cd3e88514e",
  "token_use": "id",
  "auth_time": 1677979246,
  "exp": 1677982846,
  "iat": 1677979246,
  "jti": "f7ca006b-f25b-44d2-a7a4-6e6423f4201f",
  "email": "<USER_EMAIL>"
}

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

AWS Network Firewall から Slack チャネルにアラートを送信

AWS Private CA と AWS RAM を使用してプライベート証明書の管理を簡素化する