インバウンドフェデレーション Lambda トリガー

インバウンドフェデレーショントリガーは、外部 ID プロバイダーとの認証プロセス中にフェデレーションユーザー属性を変換します。ユーザーが設定された ID プロバイダーを介して認証する場合、このトリガーにより、認証プロセスでデータを傍受して変換することで外部 SAML プロバイダーと OIDC プロバイダーからのレスポンスを変更でき、Amazon Cognito ユーザープールがフェデレーティッドユーザーとその属性を処理する方法をプログラムで制御できます。

このトリガーを使用して、新しいユーザーを作成する前、または既存のフェデレーティッドユーザープロファイルを更新する前に、属性を追加、上書き、または抑制します。このトリガーは、raw ID プロバイダー属性を入力として受け取り、Amazon Cognito がユーザープロファイルに適用する変更された属性を返します。

フローの概要

ユーザーが外部 ID プロバイダーで認証されると、Amazon Cognito はユーザープロファイルを作成または更新する前にインバウンドフェデレーショントリガーを呼び出します。トリガーは ID プロバイダーから raw 属性を受け取り、Amazon Cognito がそれらを保存する前に変換できます。このフローは、フェデレーションを通じて再度サインインする新しいフェデレーティッドユーザーと既存のユーザーの両方に発生します。

インバウンドフェデレーション Lambda トリガーパラメータ

Amazon Cognito がこの Lambda 関数に渡すリクエストは、以下のパラメータと Amazon Cognito がすべてのリクエストに追加する共通パラメータを組み合わせたものです。

JSON

{
    "version": "string",
    "triggerSource": "InboundFederation_ExternalProvider",
    "region": AWSRegion,
    "userPoolId": "string",
    "userName": "string",
    "callerContext": {
        "awsSdkVersion": "string",
        "clientId": "string"
    },
    "request": {
        "providerName": "string",
        "providerType": "string",
        "attributes": {
            "tokenResponse": {
                "access_token": "string",
                "token_type": "string",
                "expires_in": "string"
            },
            "idToken": {
                "sub": "string",
                "email": "string",
                "email_verified": "string"
            },
            "userInfo": {
                "email": "string",
                "given_name": "string",
                "family_name": "string"
            },
            "samlResponse": {
                "string": "string"
            }
        }
    },
    "response": {
        "userAttributesToMap": {
            "string": "string"
        }
    }
}

インバウンドフェデレーションリクエストパラメータ

providerName

外部 ID プロバイダーの名前。

providerType

外部 ID プロバイダーのタイプ。有効な値: OIDC、SAML、、Facebook、GoogleSignInWithApple、LoginWithAmazon。

属性

処理前に ID プロバイダーから受け取った raw 属性。構造はプロバイダータイプによって異なります。

attributes.tokenResponse

/token エンドポイントからの OAuth トークンレスポンスデータ。OIDC およびソーシャルプロバイダーでのみ使用できます。access_token、id_token、、refresh_token、token_typeexpires_in、および が含まれますscope。

attributes.idToken

デコードおよび検証された ID トークン JWT クレーム。OIDC およびソーシャルプロバイダーでのみ使用できます。(一意のユーザー識別子)email、、sub、 (iss発行者)name、 aud (対象者）、 exp (有効期限）、 iat (発行時間) などの検証済みユーザー ID 情報が含まれます。

attributes.userInfo

UserInfo エンドポイントからの拡張ユーザープロファイル情報。OIDC およびソーシャルプロバイダーでのみ使用できます。given_name、、family_name、picture、 などのプロバイダー固有のフィールドなどaddress、詳細なプロファイル属性が含まれます。IdP が UserInfo エンドポイントをサポートしていない場合、またはエンドポイント呼び出しが失敗した場合、空になる可能性があります。

attributes.samlResponse

SAML アサーション属性。SAML プロバイダーでのみ使用できます。SAML レスポンスの属性が含まれます。

インバウンドフェデレーションレスポンスパラメータ

userAttributesToMap

ユーザープロファイルに適用するユーザー属性。

重要

変更しない属性を含め、レスポンスに保持するすべてのユーザー属性を含める必要があります。userAttributesToMap レスポンスに含まれていない属性は削除され、ユーザープロファイルに保存されません。これは、変更された属性と変更されていない属性の両方に適用されます。

空のレスポンス動作

に空のオブジェクトを返した場合{}userAttributesToMap、ID プロバイダーからのすべての元の属性は変更されません。これは、Lambda 関数が実行されなかったかのように、no-op として機能します。これは、削除される属性を省略する場合とは異なります。

プロバイダー固有の属性

の構造は、 request.attributesによって異なりますproviderType。OIDC およびソーシャルプロバイダーにはtokenResponse、、idToken、 userInfo オブジェクトが含まれます。SAML プロバイダーには samlResponse オブジェクトのみが含まれます。

インバウンドフェデレーションの例: グループメンバーシップ管理

この例では、フェデレーティッド ID プロバイダーグループを Amazon Cognito ユーザープールグループにマッピングする方法を示します。この関数は、フェデレーティッドレスポンスからグループメンバーシップを抽出し、対応する Amazon Cognito グループにユーザーを自動的に追加するため、認証後のトリガーが不要になります。

Node.js

exports.handler = async (event) => {
    const { providerType, attributes } = event.request;
    
    // Extract user attributes based on provider type
    let userAttributesFromIdp = {};
    if (providerType === 'SAML') {
        userAttributesFromIdp = attributes.samlResponse || {};
    } else {
        // For OIDC and Social providers, merge userInfo and idToken
        userAttributesFromIdp = {
            ...(attributes.userInfo || {}),
            ...(attributes.idToken || {})
        };
    }
    
    // Extract groups from federated response
    const federatedGroups = userAttributesFromIdp.groups?.split(',') || [];
    
    // Map federated groups to Cognito groups
    const groupMapping = {
        'Domain Admins': 'Administrators',
        'Engineering': 'Developers',
        'Sales': 'SalesTeam'
    };
    
    // Filter to only in-scope groups
    const mappedGroups = federatedGroups
        .map(group => groupMapping[group.trim()])
        .filter(group => group); // Remove undefined values
    
    // Pass through attributes with mapped groups as custom attribute
    const attributesToMap = {
        ...userAttributesFromIdp,
        'custom:user_groups': mappedGroups.join(',')
    };
    
    // Remove original groups attribute
    delete attributesToMap.groups;
    
    event.response.userAttributesToMap = attributesToMap;
    return event;
};

Amazon Cognito は Lambda 関数にイベント情報を渡します。関数はレスポンスで、同じイベントオブジェクトを変更と共に Amazon Cognito に返します。Lambda コンソールで、Lambda トリガーに関連するデータを使用したテストイベントをセットアップできます。以下は、このコードサンプルのテストイベントです。

JSON

{
    "userPoolId": "us-east-1_XXXXXXXXX",
    "request": {
        "providerName": "CorporateAD",
        "providerType": "SAML",
        "attributes": {
            "samlResponse": {
                "email": "[e-mail]",
                "given_name": "Jane",
                "family_name": "Smith",
                "groups": "Engineering,Domain Admins",
                "department": "Engineering"
            }
        }
    },
    "response": {
        "userAttributesToMap": {}
    }
}

インバウンドフェデレーションの例: 大きな属性を切り捨てる

この例では、Amazon Cognito のストレージ制限を超える属性値を切り捨てる方法を示します。この関数は、ID プロバイダーの各属性をチェックします。属性値が 2048 文字を超える場合、値は切り捨てられ、切り捨てを示す省略記号が追加されます。他のすべての属性は変更されずに渡されます。

Node.js

exports.handler = async (event) => {
    const MAX_ATTRIBUTE_LENGTH = 2048;
    
    // Get the identity provider attributes based on provider type
    const { providerType, attributes } = event.request;
    let idpAttributes = {};
    
    if (providerType === 'SAML') {
        idpAttributes = attributes.samlResponse || {};
    } else {
        // For OIDC and Social providers, merge userInfo and idToken
        idpAttributes = {
            ...(attributes.userInfo || {}),
            ...(attributes.idToken || {})
        };
    }
    
    const userAttributes = {};
    
    // Process each attribute
    for (const [key, value] of Object.entries(idpAttributes)) {
        if (typeof value === 'string' && value.length > MAX_ATTRIBUTE_LENGTH) {
            // Truncate the value and add ellipsis
            userAttributes[key] = value.substring(0, MAX_ATTRIBUTE_LENGTH - 3) + '...';
            console.log(`Truncated attribute ${key} from ${value.length} to ${userAttributes[key].length} characters`);
        } else {
            // Keep the original value
            userAttributes[key] = value;
        }
    }
    
    // Return the modified attributes
    event.response.userAttributesToMap = userAttributes;
    return event;
};

Amazon Cognito は Lambda 関数にイベント情報を渡します。関数はレスポンスで、同じイベントオブジェクトを変更と共に Amazon Cognito に返します。Lambda コンソールで、Lambda トリガーに関連するデータを使用したテストイベントをセットアップできます。以下は、このコードサンプルのテストイベントです。

JSON

{
    "version": "string",
    "triggerSource": "InboundFederation_ExternalProvider",
    "region": "us-east-1",
    "userPoolId": "us-east-1_XXXXXXXXX",
    "userName": "ExampleProvider_12345",
    "callerContext": {
        "awsSdkVersion": "string",
        "clientId": "string"
    },
    "request": {
        "providerName": "ExampleProvider",
        "providerType": "OIDC",
        "attributes": {
            "tokenResponse": {
                "access_token": "abcDE...",
                "token_type": "Bearer",
                "expires_in": "3600"
            },
            "idToken": {
                "sub": "12345",
                "email": "[e-mail]"
            },
            "userInfo": {
                "email": "[e-mail]",
                "given_name": "Example",
                "family_name": "User",
                "bio": "This is a very long biography that contains more than 2048 characters..."
            }
        }
    },
    "response": {
        "userAttributesToMap": {}
    }
}

インバウンドフェデレーションの例: フェデレーションイベントのログ記録

この例では、モニタリングとデバッグのためにフェデレーティッド認証イベントを記録する方法を示します。このサンプル関数は、フェデレーティッドユーザーとその属性に関する詳細情報をキャプチャし、認証プロセスを可視化します。

Node.js

exports.handler = async (event) => {
    const { providerName, providerType, attributes } = event.request;
    
    // Extract user attributes based on provider type
    let userAttributesFromIdp = {};
    if (providerType === 'SAML') {
        userAttributesFromIdp = attributes.samlResponse || {};
    } else {
        // For OIDC and Social providers, merge userInfo and idToken
        userAttributesFromIdp = {
            ...(attributes.userInfo || {}),
            ...(attributes.idToken || {})
        };
    }
    
    // Log federated authentication details
    console.log(JSON.stringify({
        timestamp: new Date().toISOString(),
        providerName,
        providerType,
        userEmail: userAttributesFromIdp.email,
        attributeCount: Object.keys(userAttributesFromIdp).length,
        attributes: userAttributesFromIdp
    }));
    
    // Pass through all attributes unchanged
    event.response.userAttributesToMap = userAttributesFromIdp;
    return event;
};

Amazon Cognito は Lambda 関数にイベント情報を渡します。関数はレスポンスで、同じイベントオブジェクトを変更と共に Amazon Cognito に返します。Lambda コンソールで、Lambda トリガーに関連するデータを使用したテストイベントをセットアップできます。以下は、このコードサンプルのテストイベントです。

JSON

{
    "version": "string",
    "triggerSource": "InboundFederation_ExternalProvider",
    "region": "us-east-1",
    "userPoolId": "us-east-1_XXXXXXXXX",
    "userName": "CorporateAD_john.doe",
    "callerContext": {
        "awsSdkVersion": "string",
        "clientId": "string"
    },
    "request": {
        "providerName": "CorporateAD",
        "providerType": "SAML",
        "attributes": {
            "samlResponse": {
                "email": "[e-mail]",
                "given_name": "John",
                "family_name": "Doe",
                "department": "Engineering",
                "employee_id": "EMP12345"
            }
        }
    },
    "response": {
        "userAttributesToMap": {}
    }
}

予想される CloudWatch Logs 出力:

JSON

{
    "timestamp": "2025-01-14T21:17:40.153Z",
    "providerName": "CorporateAD",
    "providerType": "SAML",
    "userEmail": "[e-mail]",
    "attributeCount": 5,
    "attributes": {
        "email": "[e-mail]",
        "given_name": "John",
        "family_name": "Doe",
        "department": "Engineering",
        "employee_id": "EMP12345"
    }
}