如何通过OIDC协议为AWS Cognito用户池现有用户关联身份提供商

问题描述 #

尝试使用OIDC协议为AWS Cognito用户池中的现有用户添加身份提供商（IdP）时遇到困难。

问题现象 #

• 无法确定关联OIDC提供商到现有用户的合适方法
• 不清楚关联时需要使用的API操作及对应参数

现有预注册Lambda函数代码 #

const {
  CognitoIdentityProviderClient,
  ListUsersCommand,
  AdminLinkProviderForUserCommand,
} = require("@aws-sdk/client-cognito-identity-provider");

const cognitoClient = new CognitoIdentityProviderClient({});

exports.handler = async (event) => {
  if (event.triggerSource === "PreSignUp_ExternalProvider") {
    const {
      userPoolId,
      request: { userAttributes },
    } = event;
    const email = userAttributes["email"];

    // 检查邮箱是否已存在
    const userList = await cognitoClient.send(
      new ListUsersCommand({
        UserPoolId: userPoolId,
        Filter: `email = "${email}"`,
      })
    );

    if (userList.Users && userList.Users.length > 0) {
      const [providerName, providerUserId] = event.userName.split("_");

      let sourceProviderName;
      let providerAttributeName;

      switch (providerName) {
        case "google":
          sourceProviderName = "Google";
          providerAttributeName = "Cognito_Subject";
          break;
        case "azureadidp":
          sourceProviderName = "azureadidp";
          providerAttributeName = "sub";
          break;
        default:
          return event;
      }

      // 将提供商关联到现有用户
      await cognitoClient.send(
        new AdminLinkProviderForUserCommand({
          DestinationUser: {
            ProviderAttributeValue: userList.Users[0].Username,
            ProviderName: "Cognito",
          },
          SourceUser: {
            ProviderAttributeName: providerAttributeName,
            ProviderAttributeValue: providerUserId,
            ProviderName: sourceProviderName,
          },
          UserPoolId: userPoolId,
        })
      );
    } else {
      console.log("未找到用户，跳过关联操作。");
    }
  }
  return event;
};

已尝试的解决方法 #

• 最初使用AdminLinkProviderForUserCommand操作，但在确定正确参数时遇到问题
• 查阅AWS文档及在线资源，但未找到针对OIDC实现细节的清晰指导

正确实现步骤与参数说明 #

一、前置配置 #

1. 完成OIDC提供商在Cognito的配置
   • 已在用户池中创建对应OIDC提供商（如Google、Azure AD），填写好客户端ID、密钥、授权/令牌端点等信息
   • 确保用户池已启用该OIDC提供商的登录选项
2. 配置Lambda权限
   • 为执行预注册Lambda的IAM角色添加cognito-idp:AdminLinkProviderForUser和cognito-idp:ListUsers权限

二、核心API参数修正 #

你使用的AdminLinkProviderForUserCommand是正确的API，但参数需注意以下细节：

1. DestinationUser（目标Cognito现有用户）
   • ProviderName固定为"Cognito"
   • ProviderAttributeValue推荐使用用户的sub值（从ListUsersCommand返回的Users[0].Attributes中提取sub属性），比用户名更稳定
2. SourceUser（OIDC提供商用户）
   • ProviderName必须与用户池中配置的OIDC提供商名称完全一致（比如Google配置的名称是"Google"，Azure AD是你自定义的"azureadidp"）
   • ProviderAttributeName统一使用"sub"——这是OIDC协议中用户的唯一标识字段，代码中Google对应的"Cognito_Subject"是错误的
   • ProviderAttributeValue是OIDC返回的用户sub值，可从event.userName拆分获取（格式为提供商名称_sub值）

三、修正后的代码关键片段 #

switch (providerName) {
  case "google":
    sourceProviderName = "Google"; // 匹配用户池中的提供商名称
    providerAttributeName = "sub"; // 统一用OIDC的sub字段
    break;
  case "azureadidp":
    sourceProviderName = "azureadidp"; // 匹配用户池中的提供商名称
    providerAttributeName = "sub";
    break;
  default:
    return event;
}

// 获取现有用户的sub值（推荐用sub替代用户名）
const existingUserSub = userList.Users[0].Attributes.find(attr => attr.Name === 'sub').Value;

await cognitoClient.send(
  new AdminLinkProviderForUserCommand({
    DestinationUser: {
      ProviderAttributeValue: existingUserSub,
      ProviderName: "Cognito",
    },
    SourceUser: {
      ProviderAttributeName: providerAttributeName,
      ProviderAttributeValue: providerUserId,
      ProviderName: sourceProviderName,
    },
    UserPoolId: userPoolId,
  })
);

四、额外注意事项 #

• 邮箱唯一性：确保用户池已启用邮箱作为唯一标识，避免同一邮箱对应多个用户导致关联错误
• 错误处理：为AdminLinkProviderForUserCommand添加try-catch块，处理重复关联、权限不足等报错场景
• 测试验证：使用未关联过目标OIDC提供商的现有用户进行测试，避免重复关联报错

内容的提问来源于stack exchange，提问作者Prakash Mishra