使用 Amazon Cognito 使用者集區 API 和使用者集區端點 - Amazon Cognito
使用者集區 API 身分驗證

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 Amazon Cognito 使用者集區 API 和使用者集區端點

當您想要註冊、登入和管理使用者集區中的使用者，您有兩種選擇。

  1. 您的使用者集區端點包括託管 UI 和聯合端點。在您為使用者集區選擇網域時，會共同組成 Amazon Cognito 啟用的公開網頁套件。若要快速入門 Amazon Cognito 使用者集區的身分驗證和授權功能，包括用於註冊、登入、密碼管理和多重要素驗證 (MFA) 的頁面，請使用託管 UI 的內建使用者介面。其他使用者集區端點有助於通過第三方身分提供者 (IdP) 的身分驗證。執行的服務包括下列項目。

    1. 服務提供者回呼來自 IdP 的已驗證宣告的端點，例如 saml2/idpresponse 和 oauth2/idpresponse。當 Amazon Cognito 是應用程式和 IdP 之間的中繼服務提供者 (SP) 時，回呼端點代表該服務。

    2. 提供環境相關資訊的端點，例如 oauth2/userInfo 和 jwks.json。當您的應用程式使用 AWS SDK 和 OAuth 2.0 資料庫驗證權杖或取得使用者設定檔資料時會使用這些端點。

  2. Amazon Cognito 使用者集區 API 是可讓您的網頁或行動應用程式在您自己的自訂前端中收集登入資訊，以驗證使用者的一套工具。使用者集區 API 驗證會產生下列 JSON Web 權杖。

    1. 使用者具有驗證屬性宣告的身分權杖。

    2. 存取權杖授權使用者向 AWS服務端點建立權杖授權的 API 請求。

      注意

      預設中，來自使用者集區 API 身分驗證的存取權杖僅包含 aws.cognito.signin.user.admin 範圍。如果您想要產生具有其他範圍的存取權杖，例如授權對第三方 API 的請求，請透過使用者集區端點在驗證時要求範圍，或在 產生權杖前 Lambda 觸發程序 中新增自訂範圍。存取權杖自訂會增加您 AWS 帳單的成本。

您可以將通常透過使用者集區端點登入的聯合身分使用者連結至您使用者集區的本機身分使用者。本機使用者僅存在於您的使用者集區目錄中，不會透過外部 IdP 進行聯合。如果您在 AdminLinkProviderForUser API 請求中將其聯合身分連結至本機使用者，則他們可以使用使用者集區 API 登入。如需更多詳細資訊，請參閱 將聯合身分使用者連結至現有的使用者描述檔。

Amazon Cognito 使用者集區 API 有雙重用途。它會建立和設定您的 Amazon Cognito 使用者集區資源。例如，您可以建立使用者集區、新增 AWS Lambda 觸發程序，以及設定託管 UI 網域。使用者集區 API 也為本機和連結使用者執行註冊、登入和其他使用者操作。

Amazon Cognito 使用者集區 API 的範例案例

  1. 您的使用者選擇您在應用中建立的「建立帳戶」按鈕。他們輸入電子郵件地址和密碼。

  2. 您的應用程式傳送 SignUp API 請求，並在使用者集區中建立新使用者。

  3. 您的應用程式提示使用者輸入電子郵件確認碼。您的使用者輸入他們在電子郵件訊息中收到的代碼。

  4. 您的應用程式傳送帶有使用者確認代碼的 ConfirmSignUp API 請求。

  5. 您的應用程式會提示您的使用者輸入其使用者名稱和密碼，然後輸入其資訊。

  6. 您的應用程式傳送 InitiateAuth API 請求並儲存 ID 權杖、存取權杖和重新整理權杖。您的應用程式會呼叫 OIDC 程式庫以管理使用者權杖並維持該使用者的持久性工作階段。

在 Amazon Cognito 使用者集區 API 中，您無法登入透過 IdP 聯合的使用者。您必須透過使用者集區端點驗證這些使用者。如需包含託管 UI 之使用者集區端點的詳細資訊，請參閱 使用者集區聯合端點和託管 UI 參考。您的聯合身分使用者可以從託管 UI 中開始並選取其 IdP，或者您可以略過託管 UI ，並將使用者直接傳送至您的 IdP 來登入。當您對 授權端點 的 API 請求包含 IdP 參數時，Amazon Cognito 會以無訊息方式將您的使用者重新導向至 IdP 登入頁面。

使用者集區端點的範例案例

  1. 您的使用者選擇您在應用程式中建立的「建立帳戶」按鈕。

  2. 您向使用者顯示已註冊開發人員憑證的社交身分提供者清單。您的使用者選擇 Apple。

  3. 您的應用程式會以提供者名稱 SignInWithApple 向 授權端點 展開請求。

  4. 您使用者的瀏覽器會開啟 Apple OAuth 授權頁面。您的使用者選擇允許 Amazon Cognito 讀取其設定檔資訊。

  5. Amazon Cognito 確認 Apple 存取權杖並查詢使用者的 Apple 設定檔。

  6. 您的使用者會向您的應用程式提供 Amazon Cognito 授權碼。

  7. 您的應用程式與 權杖端點 交換授權碼，並儲存 ID 權杖、存取權杖和重新整理權杖。您的應用程式會呼叫 OIDC 程式庫以管理使用者權杖並維持該使用者的持久性工作階段。

本指南中所述的使用者集區 API 和使用者集區端點支援各種案例。以下各節將探討使用者集區 API 如何進一步劃分為支援您註冊、登入和資源管理需求的類別。

Amazon Cognito 使用者集區經身分驗證和未進行身分驗證的 API 操作

Amazon Cognito 使用者集區 API (同時是資源管理介面和面向使用者的身分驗證和授權介面) 根據其操作結合授權模型。根據 API 操作，您可能必須提供 IAM 憑證、存取權杖、工作階段權杖、用戶端秘密，或是以上的組合來提供授權。對於許多使用者身分驗證和授權操作，您可以選擇經身分驗證和未進行身分驗證的請求版本。對於分發給使用者的應用程式 (例如行動應用程式) 而言，未進行身分驗證的操作是最佳安全實務；您不需要在程式碼中加入任何秘密。

您只能在 以 IAM 身分驗證的管理操作 和 以 IAM 身分驗證的使用者操作 的 IAM 政策中指派許可。

以 IAM 身分驗證的管理操作會修改和檢視您的使用者集區和應用程式用戶端設定，就像在 AWS Management Console。

例如，若要修改 UpdateUserPool API 請求中的使用者集區，您必須出示 AWS 憑證和 IAM 許可才能更新資源。

若要在 AWS Command Line Interface (AWS CLI) 或 AWS SDK 中授權這些請求，請使用環境變數或用戶端設定來設定環境，將 IAM 憑證新增至請求。如需詳細資訊，請參閱 AWS 一般參考 中的使用 AWS 憑證存取 AWS。您也可以將請求直接傳送到 Amazon Cognito 使用者集區 API 的服務端點。您必須使用內嵌在請求標頭中的 AWS 憑證來授權或簽署這些請求。如需相關資訊，請參閱簽署 AWS API 請求。

以 IAM 身分驗證的管理操作
AddCustomAttributes
CreateGroup
CreateIdentityProvider
CreateResourceServer
CreateUserImportJob
CreateUserPool
CreateUserPoolClient
CreateUserPoolDomain
DeleteGroup
DeleteIdentityProvider
DeleteResourceServer
DeleteUserPool
DeleteUserPoolClient
DeleteUserPoolDomain
DescribeIdentityProvider
DescribeResourceServer
DescribeRiskConfiguration
DescribeUserImportJob
DescribeUserPool
DescribeUserPoolClient
DescribeUserPoolDomain
GetCSVHeader
GetGroup
GetIdentityProviderByIdentifier
GetSigningCertificate
GetUICustomization
GetUserPoolMfaConfig
ListGroups
ListIdentityProviders
ListResourceServers
ListTagsForResource
ListUserImportJobs
ListUserPoolClients
ListUserPools
ListUsers
ListUsersInGroup
SetRiskConfiguration
SetUICustomization
SetUserPoolMfaConfig
StartUserImportJob
StopUserImportJob
TagResource
UntagResource
UpdateGroup
UpdateIdentityProvider
UpdateResourceServer
UpdateUserPool
UpdateUserPoolClient
UpdateUserPoolDomain

以 IAM 身分驗證的使用者操作註冊、登入、管理憑證、修改及檢視您的使用者。

例如，您可以擁有一個支援 Web 前端的伺服器端應用程式層。您的伺服器端應用程式是您信任的 OAuth 機密用戶端，可獲得 Amazon Cognito 資源的特殊權限存取權。若要在應用程式中註冊使用者，您的伺服器可以在 AdminCreateUser API 請求中包含 AWS 憑證。有關 OAuth 用戶端類型的詳細資訊，請參閱 OAuth 2.0 授權架構中的用戶端類型。

若要在 AWS CLI 或 AWS SDK 中授權這些請求，請使用環境變數或用戶端設定來設定伺服器端應用程式環境，將 IAM 憑證新增至請求。如需詳細資訊，請參閱 AWS 一般參考 中的使用 AWS 憑證存取 AWS。您也可以將請求直接傳送到 Amazon Cognito 使用者集區 API 的服務端點。您必須使用內嵌在請求標頭中的 AWS 憑證來授權或簽署這些請求。如需相關資訊，請參閱簽署 AWS API 請求。

如果您的應用程式用戶端具有用戶端秘密，您必須同時提供 IAM 憑證，並根據操作提供 SecretHash 參數或 AuthParameters 中的 SECRET_HASH 值。如需更多詳細資訊，請參閱 運算私密雜湊值。

以 IAM 身分驗證的使用者操作
AdminAddUserToGroup
AdminConfirmSignUp
AdminCreateUser
AdminDeleteUser
AdminDeleteUserAttributes
AdminDisableProviderForUser
AdminDisableUser
AdminEnableUser
AdminForgetDevice
AdminGetDevice
AdminGetUser
AdminInitiateAuth
AdminLinkProviderForUser
AdminListDevices
AdminListGroupsForUser
AdminListUserAuthEvents
AdminRemoveUserFromGroup
AdminResetUserPassword
AdminRespondToAuthChallenge
AdminSetUserMFAPreference
AdminSetUserPassword
AdminSetUserSettings
AdminUpdateAuthEventFeedback
AdminUpdateDeviceStatus
AdminUpdateUserAttributes
AdminUserGlobalSignOut

未經身分驗證的使用者操作為您的使用者註冊、登入及啟動密碼重設。當您希望網際網路上的任何人註冊並登入您的應用程式，請使用未經身分驗證或公有 API 操作。

例如，要在您的應用程式中註冊使用者，您可以分發 OAuth 公有用戶端，該用戶端不提供對秘密的特殊存取權限。您可以未經身分驗證的 API 操作 SignUp 註冊此使用者。

若要在您使用 AWS SDK 開發的公有用戶端中傳送這些請求，您不需要設定任何憑證。您也可以將請求直接傳送到 Amazon Cognito 使用者集區 API 的服務端點，不需要額外授權。

如果您的應用程式用戶端具有用戶端秘密，則必須根據操作提供 SecretHash 參數或 AuthParameters 中的 SECRET_HASH 值。如需更多詳細資訊，請參閱 運算私密雜湊值。

未經身分驗證的使用者操作
SignUp
ConfirmSignUp
ResendConfirmationCode
ForgotPassword
ConfirmForgotPassword
InitiateAuth

權杖授權的使用者操作會在使用者登入或開始登入程序後，登出、管理憑證、修改和檢視您的使用者。如果您不想在應用程式中分發秘密，並且想要以使用者自己的憑證授權請求時，請使用權杖授權 API 操作。如果您的使用者已完成登入，則必須使用存取權杖授權其權杖授權的 API 請求。如果您的使用者正在進行登入程序，您必須使用 Amazon Cognito 在回應先前請求時傳回的工作階段權杖來授權其權杖授權的 API 請求。

例如，在公有用戶端中，您可能會想要將更新使用者設定檔的寫入存取權限，限制為僅針對使用者自己的設定檔。若要進行此更新，您的用戶端可以在 UpdateUserAttributes API 請求中包含使用者的存取權杖。

若要在您使用 AWS SDK 開發的公有用戶端中傳送這些請求，您不需要設定任何憑證。在請求中包含 AccessToken 或 Session 參數。您也可以將請求直接傳送到 Amazon Cognito 使用者集區 API 的服務端點。要授權對服務端點的請求，請在請求的 POST 內文中包含存取或工作階段權杖。

若要簽署權杖授權操作的 API 請求，請在請求中以 Bearer <Base64-encoded access token> 格式包括存取權杖作為 Authorization 標頭。

權杖授權的使用者操作 AccessToken Session (工作階段)
RespondToAuthChallenge ✓
ChangePassword ✓
GetUser ✓
UpdateUserAttributes ✓
DeleteUserAttributes ✓
DeleteUser ✓
ConfirmDevice ✓
ForgetDevice ✓
GetDevice ✓
ListDevices ✓
UpdateDeviceStatus ✓
GetUserAttributeVerificationCode ✓
VerifyUserAttribute ✓
SetUserSettings ✓
SetUserMFAPreference ✓
GlobalSignOut ✓
AssociateSoftwareToken ✓ ✓
UpdateAuthEventFeedback ✓
VerifySoftwareToken ✓ ✓
RevokeToken¹

¹ RevokeToken 需要重新整理權杖作為參數。重新整理權杖用作授權權杖，並作為目標資源。