跳转到内容

网站身份提供商

网站身份验证创建一个 Amazon Cognito 用户池,默认情况下只有在该池中拥有用户名和密码的用户才能登录。如果您的员工或客户已经在身份提供商(IdP)(如 Okta、Auth0 或 Microsoft Entra ID)拥有账户,他们就需要为您的网站创建第二个账户。

使用 --federation=oidc 运行 ts#website#auth 可以让您将外部 OpenID Connect(OIDC)身份提供商添加到用户池。您在基础设施代码中列出身份提供商:CDK 中 UserIdentity 的 oidcIdentityProviders 属性,或 Terraform 中 user_identity 模块的 oidc_identity_providers 变量。登录页面随后会在用户名和密码表单旁边显示每个身份提供商的按钮。

  • 您的网站仍然将用户发送到 Cognito 登录页面。该页面现在有一个以每个身份提供商命名的按钮。
  • 选择按钮的用户在该身份提供商处登录。身份提供商将他们发送回 Cognito 的重定向 URI,https://<cognito domain>/oauth2/idpresponse。
  • Cognito 在您的用户池中为他们创建一个用户(联合用户),并将您映射的声明(例如 email)复制到用户的属性中。
  • 然后 Cognito 颁发与本地用户相同类型的令牌。您的 API、代理和身份池无需任何更改即可接受它们。

在池中拥有用户名和密码的用户仍然可以登录。

添加身份提供商可能会让比您预期更多的人进入您的网站。ts#website#auth 的 allowSignup 选项不适用于联合用户。Cognito 在某人首次通过身份提供商登录时创建联合用户,即使用户池不允许用户自行注册。每个联合用户还会获得身份池的已认证角色,因此他们可以像任何已登录用户一样调用您的 API 和代理。

身份提供商适用于整个用户池。使用该池的每个网站都会显示它们的按钮并接受它们的用户。

因此,身份提供商决定谁可以登录。设置它以便仅让需要您网站的人登录:

  • Microsoft Entra ID:在应用程序的企业应用程序属性中,将”需要分配?“设置为”是”,并仅分配需要访问的用户或组。使用默认值”否”时,租户中的每个用户都可以登录。
  • Okta:仅将应用程序分配给需要访问的组。
  • Auth0:在应用程序使用的每个连接上禁用注册,并仅为应用程序启用其用户需要访问的连接。否则,任何通过已启用连接(例如社交连接)注册的人都可以登录。

使用 --federation=oidc 运行 ts#website#auth 生成器。您可以在尚未进行身份验证的网站上运行它,也可以在已经具有身份验证的网站上运行它。两者给出相同的结果。

运行此生成器@aws/nx-plugin:ts#website#auth

pnpm nx g @aws/nx-plugin:ts#website#auth --federation=oidc
构建你的命令6

必需

生成器不添加任何身份提供商。列表从空开始,因此在您添加条目之前,登录的工作方式与以前相同。您将身份提供商添加到基础设施代码中,因此添加第二个身份提供商不需要再次运行生成器。

使用 --federation=oidc 再次运行生成器不会更改任何文件。使用 --federation=none 或不使用 --federation 运行它会保留已经存在的联合。

为每个身份提供商添加一个条目,然后部署。客户端密钥永远不会进入您的代码。您将其存储在 AWS Secrets Manager 中并提供其名称,如设置您的身份提供商所述。

在您的堆栈中将身份提供商传递给 UserIdentity:

packages/infra/src/stacks/application-stack.ts
import { MyWebsite, UserIdentity } from '@my-scope/common-constructs';
const identity = new UserIdentity(this, 'Identity', {
oidcIdentityProviders: [
{
name: 'Okta',
issuerUrl: 'https://example.okta.com',
clientId: '0oa1example',
clientSecretName: 'okta-oidc-client-secret',
},
{
name: 'Entra',
issuerUrl: 'https://login.microsoftonline.com/<tenant-id>/v2.0',
clientId: '11111111-2222-3333-4444-555555555555',
clientSecretName: 'entra-oidc-client-secret',
identifiers: ['example.com'],
},
],
});
new MyWebsite(this, 'MyWebsite');

OidcIdentityProviderProps(每个条目的类型)从您的共享构造包中导出,因此您可以在其他地方构建列表并导入该类型。

列表中的每个身份提供商都具有这些属性。生成器选项在网站身份验证中描述。

CDK propTerraform attributeRequiredDefaultDescription
namenameYes显示在登录按钮上。Cognito 使用小写形式为联合用户名添加前缀(<name>_<sub>)。3-32 个字母、数字和连字符,以字母开头。不能是 COGNITO。在列表中唯一,忽略大小写。在 CDK 中,它必须是文字字符串,而不是令牌。
issuerUrlissuer_urlYes颁发者,与身份提供商令牌的 iss 声明中显示的完全一致。必须使用 https://。
clientIdclient_idYes在身份提供商处注册的应用程序的客户端 ID。
clientSecretNameclient_secret_nameYes保存客户端密钥作为纯字符串的 Secrets Manager 密钥的名称。名称,而不是 ARN。
scopesscopesNoopenid、email、profile要请求的 OAuth 范围。必须包含 openid。
attributeMappingattribute_mappingNoemail、given_name 和 family_name,每个都映射到具有相同名称的声明用户池属性到身份提供商声明。请参阅属性映射。
identifiersidentifiersNoNone标识符,例如电子邮件域,Cognito 可以使用它们将用户发送到此身份提供商。

供应的代码在部署任何内容之前检查每个条目:

当您使用违反规则的条目创建 UserIdentity 时,它会抛出异常,因此 cdk synth 失败。基础设施项目的构建运行 cdk synth。消息会命名该条目,例如 UserIdentity: oidcIdentityProviders[1] (Entra): Microsoft Entra ID issuers have no trailing slash. Use https://login.microsoftonline.com/<tenant-id>/v2.0。

令牌值(例如从 AWS Systems Manager Parameter Store 读取的值)不会被检查。错误的值会导致部署失败而不是合成失败。name 不能是令牌。

规则:

  • name:3-32 个字母、数字和连字符,以字母开头。不能是任何大小写的 COGNITO,因为 Cognito 将其保留用于使用用户池本身登录。
  • 名称在列表中是唯一的,忽略大小写,因为 Cognito 使用小写名称为联合用户名添加前缀。例如,Okta 和 OKTA 不能同时在列表中。test-idp 和 testidp 可以,因为它们的前缀不同。
  • 颁发者使用 https:// 并且没有查询、片段、用户名、密码或空格。在 CDK 中,它还必须解析为 URL。在 Terraform 中,正则表达式检查它,它接受一些 CDK 拒绝的格式错误的 URL。
  • Microsoft Entra ID:多租户颁发者(common、organizations、consumers 和 9188040d-6c67-4c5b-b112-36a304b66dad)被拒绝,并且颁发者不得以斜杠结尾。
  • Auth0:*.auth0.com 上的颁发者必须以斜杠结尾。
  • 客户端 ID 不为空。
  • 密钥名称为 1-512 个字母、数字和 / _ + = . @ -。这些是 Secrets Manager 命名规则,因此 ARN 被拒绝。
  • 范围包括 openid。在 CDK 中,每个范围还必须非空且没有空格。
  • 属性映射键和值遵循属性映射中的规则。
  • 最多 50 个标识符。每个标识符为 1-40 个字母、数字、空格或 _ + = . @ -。

使用 --federation=oidc,生成器为您选择的 iac 提供商添加这些文件和编辑:

  • 文件夹packages/common/constructs/src/core
    • oidc-identity-providers.ts OidcIdentityProviders 构造、其属性和验证
    • index.ts 现在导出 oidc-identity-providers.ts
    • user-identity.ts 现在具有 oidcIdentityProviders 属性并创建身份提供商

编辑让用户池的 Web 客户端(您的网站登录所通过的 Cognito 应用客户端)接受身份提供商:

packages/common/constructs/src/core/user-identity.ts
import {
OidcIdentityProviders,
type OidcIdentityProviderProps,
} from './oidc-identity-providers.js';
readonly mfaSecondFactor?: MfaSecondFactor;
/**
* OpenID Connect identity providers users can sign in through, next to the user pool's own sign-in.
* Applies to every website that uses this user pool.
* ...
*/
readonly oidcIdentityProviders?: OidcIdentityProviderProps[];
}
mfaSecondFactor = { sms: true, otp: true },
oidcIdentityProviders = [],
}: UserIdentityProps = {},
this.userPoolDomain = this.createUserPoolDomain(this.userPool);
new OidcIdentityProviders(this, 'OidcIdentityProviders', {
userPool: this.userPool,
userPoolDomain: this.userPoolDomain,
providers: oidcIdentityProviders,
});
this.userPoolClient = this.createUserPoolClient(this.userPool);

UserIdentity 在 Web 客户端之前创建身份提供商,因此 Web 客户端列出它们,然后是 COGNITO。

生成器不会覆盖您对新文件的编辑。如果您更改了 user-identity.ts 或 main.tf 或 identity.tf,使得生成器无法再识别它,生成器会保持这些文件不变。它仍然会添加新文件,并打印出需要手动添加的行。

添加身份提供商的部署会从 Secrets Manager 读取其客户端密钥。如果密钥不存在,部署将失败。

CloudFormation 使用堆栈的执行角色读取密钥,默认为 cdk-hnb659fds-cfn-exec-role-<account>-<region>。该角色需要对密钥具有 secretsmanager:GetSecretValue 权限,如果密钥使用客户托管的 AWS KMS 密钥加密,还需要对密钥具有 kms:Decrypt 权限。

按此顺序执行以下步骤。生成器完成时也会打印这些步骤。

  1. 使用 --federation=oidc 运行 ts#website#auth,并部署一次。
  2. 找到您的用户池的重定向 URI。该池的所有身份提供商都使用相同的 URI。

包含 UserIdentity 的堆栈有一个输出,其键以 <id>OidcIdentityProvidersIdpRedirectUri 开头,其中 <id> 是您给 UserIdentity 的构造 ID,例如 IdentityOidcIdentityProvidersIdpRedirectUri。您也可以在部署之前根据您为 ts#website#auth 选择的 cognitoDomain、您的 AWS 账户 ID 和您的区域计算出来:

https://<cognitoDomain>-<account>.auth.<region>.amazoncognito.com/oauth2/idpresponse
  1. 在身份提供商处使用该重定向 URI 注册一个应用程序,并记下其客户端 ID 和客户端密钥。仅在身份提供商处注册此 /oauth2/idpresponse URI。您网站自己的 URL 是在 Cognito 中注册的,而不是在身份提供商处。

  2. 将客户端密钥存储在 Secrets Manager 中。在文件中传递它,而不是作为命令行参数。参数会保留在您的 shell 历史记录中,并且同一台计算机的其他用户可以在命令运行时在进程列表中看到它:

    终端窗口
    (
    umask 077
    d=$(mktemp -d) || exit
    trap 'rm -rf "$d"' EXIT
    trap 'exit 1' HUP INT TERM
    unset CLIENT_SECRET
    IFS= read -rs CLIENT_SECRET || exit 1
    printf '%s' "$CLIENT_SECRET" > "$d/secret" || exit 1
    unset CLIENT_SECRET
    aws secretsmanager create-secret --name okta-oidc-client-secret --secret-string "file://$d/secret" --region <region>
    )

    这些命令在子 shell 中运行,位于括号之间。read 等待您粘贴客户端密钥并按 Enter,并且不显示它。两个 unset 命令将密钥排除在 aws 命令的环境之外,即使您之前导出了 CLIENT_SECRET。IFS= 和 -r 保持密钥与您粘贴的完全一致,包括两端的空格和反斜杠。mktemp -d 创建一个只有您可以打开的新目录(模式 700),printf 将密钥写入其中,末尾没有换行符。AWS CLI 从 file:// 后面命名的文件中读取 --secret-string 的值并原样传递,因此文件末尾的换行符会成为密钥的一部分。当子 shell 结束时,trap 命令会删除该目录。如果 aws 命令失败或您按 Ctrl-C,它们也会这样做。这些命令在 bash 和 zsh(Linux 和 macOS 上的默认 shell)中有效。对于 Windows,请参阅降低使用 AWS CLI 存储 AWS Secrets Manager 密钥的风险。

    将 --region 设置为您的堆栈区域。在添加身份提供商的部署之前,密钥必须存在于该区域。将密钥存储为纯字符串,而不是 JSON,因为 Cognito 接收整个密钥值作为客户端密钥。在 Secrets Manager 控制台中,选择 Plaintext,而不是 Key/value。

  3. 将身份提供商添加到列表中,将密钥的名称作为 clientSecretName(Terraform 中的 client_secret_name),如添加身份提供商所示。然后部署。

生成的用户池需要 email、given_name 和 family_name 属性。Cognito 在每次登录时从身份提供商的声明中填充它们。如果身份提供商没有发送其中之一,用户的首次登录将失败。因此,UserIdentity 和 Terraform 变量拒绝遗漏这三个属性中任何一个的属性映射。

attributeMapping(Terraform 中的 attribute_mapping)将用户池属性映射到声明。每个键是一个用户池属性,每个值是身份提供商声明的名称,长度为 1-128 个字符。您提供的映射会替换默认值。默认值将每个必需属性映射到具有相同名称的声明:

attributeMapping: { email: 'email', given_name: 'given_name', family_name: 'family_name' },
  • 键可以是任何标准属性,如 name 或 phone_number、phone_number_verified,或自定义属性,如 custom:department(custom: 后最多 20 个字母、数字或下划线)。键在 CDK 和 Terraform 中都使用 Cognito 属性名称。username 被拒绝。
  • Cognito 将映射的电子邮件地址视为未验证。仅从自己验证电子邮件地址的身份提供商映射 email_verified。否则,用户可能在身份提供商处设置他人的地址,并在您的池中将其标记为已验证。
  • 如果用户的电子邮件地址在身份提供商处更改,Cognito 会在用户下次登录时将新地址写入用户池。email_verified 保持为 false。
  • 自定义属性必须已存在于用户池中,并且必须是可变的。

Terraform 身份提供商资源(在 identity/oidc-identity-providers.tf 中)还设置了 Cognito 在返回身份提供商时添加的两个值:attribute_mapping 中的 username = "sub" 和 provider_details 中的 attributes_url_add_attributes = "false"。因为文件设置了它们,所以第一次部署后的第二次 terraform plan 不会显示对身份提供商的更改。如果第二次计划仍然显示另一个身份提供商的 provider_details 中有更改,请将该键添加到文件中,其值为计划显示 Cognito 返回的值。

以下设置来自各供应商的文档。Okta 已在 AWS 上使用 CDK 和 Terraform 进行了测试。Auth0 和 Microsoft Entra ID 设置已根据各供应商发布的 OpenID 发现文档进行了检查,但未进行实际登录测试。

已在 AWS 上使用 CDK 和 Terraform 进行测试。在 Okta 中创建一个 OIDC Web 应用程序,使用授权码授予和客户端密钥。将其登录重定向 URI 设置为设置您的身份提供商第 2 步中的 /oauth2/idpresponse 重定向 URI。它不需要注销重定向 URI。颁发者是您的 Okta 域名,https://<your-org>.okta.com,这是经过测试的形式。自定义授权服务器(如 https://<your-org>.okta.com/oauth2/default)也有颁发者,但该形式尚未经过测试。默认范围 openid email profile 返回 email、given_name 和 family_name,因此默认映射有效。每个用户需要在 Okta 中设置电子邮件、名字和姓氏。仅将应用程序分配给需要访问的用户或组。

已根据 Auth0 的发现文档进行检查,未进行实际登录测试。在 Auth0 中创建一个常规 Web 应用程序。颁发者是 https://<your-tenant>.auth0.com/,包括尾部斜杠。

Auth0 仅在用户的连接提供 given_name 和 family_name 时才返回它们。没有它们的连接的用户在您映射其他声明之前无法登录。

已根据 Microsoft 的发现文档进行检查,未进行实际登录测试。在 Entra ID 中注册一个单租户应用程序。颁发者是 https://login.microsoftonline.com/<tenant-id>/v2.0。供应的代码拒绝多租户颁发者(common、organizations 和 consumers),因为它们接受来自任何 Entra ID 租户的用户。它还拒绝租户 9188040d-6c67-4c5b-b112-36a304b66dad,该租户接受任何个人 Microsoft 账户。

颁发者不得以斜杠结尾:使用 /v2.0,而不是 /v2.0/。Entra ID 令牌中的 iss 声明没有斜杠,因此登录会失败。供应的代码拒绝带斜杠的形式。

将 email、given_name 和 family_name 作为可选声明添加到应用程序的 ID 令牌。Entra ID 仅在您这样做时才发送它们。每个用户需要设置 Mail 字段。否则 email 声明为空,用户的首次登录将失败,因为用户池需要 email。Entra ID 的 email 声明未经验证,因此不要从 Entra ID 映射 email_verified。

要使用另一个 Cognito 用户池作为身份提供商进行测试,请使用颁发者 https://cognito-idp.<region>.amazonaws.com/<user pool id>。为其应用客户端提供客户端密钥、授权码授予和范围 openid email profile。

  • 通过 sub 声明(用户在您的用户池中的唯一 ID)识别用户,而不是通过 email。联合用户是您池中的新用户,具有自己的 sub,即使他们的电子邮件与本地用户匹配。插件生成的代码使用 sub。
  • 使用单租户颁发者。多租户颁发者允许来自任何组织的用户登录。
  • 从生产阶段删除 http://localhost 回调 URL,如网站身份验证所述。联合不添加回调 URL。
  • 用户池中要求的 MFA(多因素身份验证)不适用于联合用户。Cognito 将他们的身份验证留给身份提供商,因此在身份提供商处强制执行 MFA。

  • 从您的网站注销仅结束 Cognito 会话。它不会结束用户在 OIDC 身份提供商处的会话,因此通过按钮的下一次登录可以在没有密码的情况下完成。在共享计算机上,用户还必须在身份提供商处注销。

  • 用户菜单显示 Cognito 用户名。对于联合用户,它是身份提供商名称、下划线和用户在身份提供商处的 sub,小写,例如 okta_00u1abcd。

  • 在身份提供商处删除或禁用用户仅会阻止他们通过它的下一次登录。Cognito 使用自己的刷新令牌续订令牌,不会询问身份提供商,网站在用户不注意的情况下续订令牌。因此,用户可以保持访问权限,直到刷新令牌过期,最多在他们上次登录后 30 天。要阻止用户获取新令牌,还要将他们从每个会话中注销并在用户池中禁用他们。他们的用户名是 <identity provider name in lowercase>_<sub>:

    终端窗口
    aws cognito-idp admin-user-global-sign-out --user-pool-id <user pool id> --username okta_<sub>
    aws cognito-idp admin-disable-user --user-pool-id <user pool id> --username okta_<sub>

    这已在 AWS 上进行了测试。在 admin-user-global-sign-out 和 admin-disable-user 之后,身份提供商仍然会让用户登录,但 Cognito 会拒绝他们。

    这些命令不会结束用户已经拥有的访问权限。admin-user-global-sign-out 撤销用户的刷新令牌,因此网站无法为他们获取新令牌,admin-disable-user 阻止他们的下一次登录。Cognito 已经颁发的 ID 和访问令牌在过期之前保持有效,默认情况下在颁发后一小时过期(ID 和访问令牌有效期)。身份池已经给网站的 AWS 凭证也在过期之前保持有效,在颁发后一小时过期(身份池身份验证流程)。在它们过期之前,用户仍然可以使用网站和身份池的已认证角色。

    Web 客户端上较短的刷新令牌有效期(CDK 中的 refreshTokenValidity,Terraform 中的 refresh_token_validity)会缩短被删除用户在您不运行这些命令时保持访问权限的时间。较短的 ID 和访问令牌有效期(CDK 中的 idTokenValidity 和 accessTokenValidity,Terraform 中的 id_token_validity 和 access_token_validity)会缩短在您运行命令后已颁发令牌保持有效的时间,但总会有一些时间。两者都尚未在 AWS 上测试。

Cognito 在身份提供商的设置中保存客户端密钥。任何被允许在您的用户池上调用 cognito-idp:DescribeIdentityProvider 的人都可以读取它。这是 Cognito 的工作方式,无论您使用哪个 IaC 提供商。

构造将密钥作为动态引用传递给 CloudFormation,{{resolve:secretsmanager:<clientSecretName>:SecretString:::}}。合成的模板仅包含该引用。CloudFormation 在创建或更新身份提供商时读取密钥。如果您轮换密钥,Cognito 仅在稍后部署中身份提供商资源更改时才获得新值。

CloudFormation 在身份提供商的设置(ProviderDetails)内解析引用,因此联合登录使用存储的密钥有效,部署的模板仍然仅保存引用。轮换后,没有其他更改的部署在 Cognito 中保留了旧密钥。两者都已在 AWS 上检查。

要将轮换的密钥发送到 Cognito:

在轮换后的部署中更改身份提供商资源。一种方法是将轮换的密钥存储在新名称下,并将 clientSecretName 设置为该名称。然后模板中的引用会更改,因此 CloudFormation 更新身份提供商并读取新密钥。之后删除旧密钥。这遵循 CloudFormation 动态引用文档,尚未在 AWS 上测试。

应用客户端是应用程序登录所通过的 Cognito 配置。生成器仅将身份提供商添加到网站的应用客户端(Web 客户端)。同一用户池中的另一个应用客户端仅在它也列出身份提供商时才接受联合用户。例如,您为 DCR 代理(允许 MCP 客户端,即使用模型上下文协议的 AI 工具,通过 Cognito 登录)创建的应用客户端需要它们。否则联合用户无法登录到您的 MCP 服务器。

在 UserIdentity 之后使用 identity.userPool.addClient(...) 创建的应用客户端,如果没有 supportedIdentityProviders,会列出池的每个身份提供商和 COGNITO。DCR 代理示例就是这样做的。如果您的应用客户端设置了 supportedIdentityProviders,请将池的身份提供商添加到它:

import { UserPoolClientIdentityProvider } from 'aws-cdk-lib/aws-cognito';
supportedIdentityProviders: [
UserPoolClientIdentityProvider.COGNITO,
...identity.userPool.identityProviders.map((p) =>
UserPoolClientIdentityProvider.custom(p.providerName),
),
],

具有 Cognito 身份验证的 TypeScript 代理的 <agent>-chat 目标从 AGENT_ACCESS_TOKEN 环境变量读取 Cognito 访问令牌。联合用户没有 Cognito 密码,因此 admin-initiate-auth 对他们不起作用。相反,登录到您的网站,打开浏览器的开发者工具,并从会话存储中的 oidc.user:... 条目复制 access_token。