Amazon Cognito
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

配置用户池应用程序客户端

在创建用户池后,您可以创建一个应用程序客户端,以便使用内置网页来注册和登记用户。要使用 AWS 管理控制台添加应用程序客户端和 Amazon Cognito 托管域,请参阅添加应用程序以启用托管 Web UI

应用程序客户端设置概览

启用身份提供商

您可以选择身份提供商 (IdP) 来对用户进行身份验证。该服务可以由您的用户池或第三方(如 Facebook)来执行。要使用 IdP,先得启用它。可以启用多个 IdP,但必须至少启用一个。有关使用外部 IdP 的更多信息,请参阅通过第三方添加用户池登录

回调 URL

回调 URL 指示在用户成功登录之后将被重定向到哪里。选择至少一个回调 URL,且该 URL 应具有以下特点:

  • 是绝对 URI。

  • 已预先向客户端注册。

  • 不包含片段组件。

请参阅 OAuth 2.0 - 重定向终端节点

Amazon Cognito 需要基于 HTTPHTTPS,对于仅用于测试目的的 http://localhost 除外。

应用程序回调 URL(如 myapp://example)也受支持。

注销 URL

注销 URL 指示在您的用户注销后会被重定向到哪里。

允许的 OAuth 流程

Authorization code grant 流启动代码授予流,这会提供授权代码作为响应。此代码可用来与TOKEN 终端节点交换访问令牌。由于令牌绝不会直接向最终用户公开,因此它们不太可能被泄露。但是,后端需要自定义应用程序以将授权代码换成用户池令牌。

注意

出于安全原因,对于移动应用程序,强烈建议您仅将授权代码授予流程与 PKCE 一起使用。

Implicit grant 流允许客户端直接从AUTHORIZATION 终端节点获取访问令牌 (根据范围,可选择获取 ID 令牌)。如果您的应用程序无法启动 Authorization code grant 流,请选择此流。有关更多信息,请参阅 OAuth 2.0 规范

您可以同时启用授权代码授予隐式代码授予,然后按需使用每个授予。

Client credentials (客户端凭证) 流在机器对机器的通信中使用。利用该流,您可以请求访问令牌来访问自己的资源。当您的应用程序代表自己而不是代表用户来请求令牌时,使用此流。

注意

由于客户端凭证流不是代表用户使用的,所以只有自定义范围可以与该流一起使用。自定义范围就是您为自己的资源服务器定义的范围。请参阅 为您的用户池定义资源服务器

允许的 OAuth 范围

选择以下一个或多个 OAuth 范围来指定可以为访问令牌请求的访问权限。

  • phone 范围授予对 phone_numberphone_number_verified 声明的访问权限。此范围只能通过 openid 范围来请求。

  • email 范围授予对 emailemail_verified 声明的访问权限。此范围只能通过 openid 范围来请求。

  • openid 范围返回 ID 令牌中客户端可读取的所有用户属性。如果客户端未请求 openid 范围,则不返回 ID 令牌。

  • aws.cognito.signin.user.admin 范围授予对需要访问令牌的 Amazon Cognito 用户池 API 操作的访问权限,例如 UpdateUserAttributesVerifyUserAttribute

  • profile 范围授予对客户端可读取的所有用户属性的访问权限。

允许的自定义范围

自定义范围是您在 Resource Servers (资源服务器) 中为自己的资源服务器定义的范围。格式为:资源-服务器-标识符/范围。请参阅 为您的用户池定义资源服务器

有关 OAuth 范围的更多信息,请参阅标准 OIDC 范围列表。

配置应用程序客户端 (AWS 管理控制台)
  1. 转到 Amazon Cognito 控制台。系统可能会提示您输入 AWS 凭证。

  2. 选择 Manage User Pools

  3. 选择要编辑的用户池。

  4. 从控制台页面左侧的导航栏中选择应用程序客户端设置

  5. 选择 Cognito 用户池作为启用身份提供商之一,将其包括在您的 IdP 列表中。启用至少一个 IdP。

    注意

    要使用外部身份提供商 (IdP)(如 Facebook、Amazon 或 Google)以及通过 OpenID Connect (OIDC) 或 SAML IdP 登录,请首先配置它们,然后返回到应用程序客户端设置页面启用它们。有关更多信息,请参阅 通过第三方添加用户池登录

  6. 登录 URL 和注销 URL 部分中,键入回调 URL 并以逗号分隔。

    对于 Web 应用程序,该 URL 应以 https:// 开头,如 https://www.example.com。

    对于 iOS 或 Android 应用程序,您可以使用类似 myapp:// 的回调 URL。

    注意

    您必须先在控制台中或者使用 CLI 或 API 来注册回调和注销 URL,然后才能在用户池应用程序客户端中使用它们。

  7. 键入可选注销 URL 并以逗号分隔。

  8. 选择您的 OAuth 2.0 选项:

    • 授予授权代码

    • 隐式授予

    • 客户端凭证

      选择客户端凭证将清除其他选项,同时标准范围将不可用。

    1. 对于代码授予和隐式授予选项,从允许的 OAuth 范围选择您的范围。每个范围是包含一个或多个标准属性的集合。有关更多信息,请参阅 应用程序客户端设置概览

    2. 对于客户端凭证流,标准范围不可用。由于客户端凭证流不是代表用户使用的,所以只有自定义范围可用。自定义范围就是您为自己的资源服务器定义的范围。请参阅 为您的用户池定义资源服务器

  9. 选择 Save changes

配置应用程序客户端(AWS CLI 和 AWS API)

您可以使用 AWS CLI 创建、更新、描述和删除您的用户池应用程序客户端。

在这些示例中,用您的用户池和应用程序客户端 ID 值替换了“MyUserPoolID”和“MyAppClientID”。同样,您的参数值可能不同于这些示例中使用的值。

注意

回调和注销 URL 采用 JSON 格式,以防止 CLI 将它们视为远程参数文件:

--callback-urls '["https://example.com"]'

--logout-urls '["https://example.com"]'

更新用户池应用程序客户端(AWS CLI 和 AWS API)

aws cognito-idp update-user-pool-client --user-pool-id "MyUserPoolID" --client-id "MyAppClientID" --allowed-o-auth-flows-user-pool-client --allowed-o-auth-flows "code" "implicit" --allowed-o-auth-scopes "openid" --callback-urls '["https://example.com"]' --supported-identity-providers '["MySAMLIdP", "LoginWithAmazon"]'

如果命令成功,则 AWS CLI 会返回确认:

{ "UserPoolClient": { "ClientId": "MyClientID", "SupportedIdentityProviders": [ "LoginWithAmazon", "MySAMLIdP" ], "CallbackURLs": [ "https://example.com" ], "AllowedOAuthScopes": [ "openid" ], "ClientName": "Example", "AllowedOAuthFlows": [ "implicit", "code" ], "RefreshTokenValidity": 30, "CreationDate": 1524628110.29, "AllowedOAuthFlowsUserPoolClient": true, "UserPoolId": "MyUserPoolID", "LastModifiedDate": 1530055177.553 } }

请参阅 AWS CLI 命令参考了解更多信息:update-user-pool-client

AWS API:UpdateUserPoolClient

创建用户池应用程序客户端(AWS CLI 和 AWS API)

aws cognito-idp create-user-pool-client --user-pool-id MyUserPoolID --client-name myApp

请参阅 AWS CLI 命令参考了解更多信息:create-user-pool-client

AWS API:CreateUserPoolClient

获取有关用户池应用程序客户端的信息(AWS CLI 和 AWS API)

aws cognito-idp describe-user-pool-client --user-pool-id MyUserPoolID --client-id MyClientID

请参阅 AWS CLI 命令参考了解更多信息:describe-user-pool-client

AWS API:DescribeUserPoolClient

列出一个用户池中所有应用程序客户端的信息(AWS CLI 和 AWS API)

aws cognito-idp list-user-pool-clients --user-pool-id "MyUserPoolID" --max-results 3

请参阅 AWS CLI 命令参考了解更多信息:list-user-pool-clients

AWS API:ListUserPoolClients

删除用户池应用程序客户端(AWS CLI 和 AWS API)

aws cognito-idp delete-user-pool-client --user-pool-id "MyUserPoolID" --client-id "MyAppClientID"

请参阅 AWS CLI 命令参考了解更多信息:delete-user-pool-client

AWS API:DeleteUserPoolClient