使用應用程式用戶端的應用程式特定設定 - Amazon Cognito

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

使用應用程式用戶端的應用程式特定設定

使用者集區應用程式用戶端是使用者集區內的組態,它會與透過 Amazon Cognito 進行驗證的一個行動或 Web 應用程式互動。應用程式用戶端可以呼叫已驗證和未驗證API的操作,並讀取或修改部分或全部的使用者屬性。您的應用程式必須在註冊、登入及處理忘記密碼的操作過程中,對應用程式用戶端表明自己的身分。這些API請求必須包含具有應用程式用戶端 ID 的自我識別,以及具有選用用戶端秘密的授權。您必須保護任何應用程式用戶端IDs或秘密,以便只有授權的用戶端應用程式可以呼叫這些未經驗證的操作。此外,如果您將應用程式設定為使用 AWS 憑證簽署已驗證的API請求,則必須保護您的憑證免受使用者檢查。

您可以為使用者集區建立多個應用程式。應用程式用戶端可能會連結至應用程式的程式碼平台,或是使用者集區中的另一個租用戶。例如,您可能為伺服器端應用程式建立一個應用程式,以及建立不同的 Android 應用程式。每個應用程式都有自己的應用程式用戶端 ID。

您可以在應用程式用戶端層級套用下列使用者集區功能的設定:

應用程式用戶端類型

當您在 Amazon Cognito 中建立應用程式用戶端時,您可以根據標準OAuth用戶端類型公有用戶端機密用戶端 預先填入選項。以 client secret (用户端密碼) 設定 confidential client (機密用户端)。如需用戶端類型的詳細資訊,請參閱 IETF RFC 6749 #2.1

Public client (公有用户端)

公有用户端在瀏覽器或行動裝置上執行。因為它沒有受信任的伺服器端資源,因此沒有用户端密碼。

Confidential client (機密用户端)

機密用戶端具有伺服器端資源,可透過未驗證API操作的用戶端秘密信任。應用程式可在後端伺服器上作為常駐程式或 Shell 指令碼執行。

Client secret (用戶端密碼)

用戶端秘密或用戶端密碼是固定字串,您的應用程式必須用於應用程式用戶端的所有API請求。您的應用程式用户端必須具有用户端密碼才能執行 client_credentials 授予。如需詳細資訊,請參閱 IETF RFC 6749 #2.3.1

您無法在建立應用程式後變更密碼。如果您要輪換密碼,可以建立具有新密碼的新應用程式。您也可以刪除應用程式,以封鎖從使用該應用程式用戶端 ID 的應用程式進行存取。

您可以在公有應用程式中使用機密用户端和用户端密碼。使用 Amazon CloudFront 代理新增傳輸SECRET_HASH中的 。如需詳細資訊,請參閱部落格上的使用 Amazon 代理來保護 Amazon Cognito 的公有用戶端 CloudFront 。 AWS

JSON Web 權杖

Amazon Cognito 應用程式用戶端可以發行下列類型的 JSON Web 權杖 (JWTs)。

身分 (ID) 權杖

您的使用者已透過您的使用者集區進行身分驗證的可驗證陳述式。OpenID Connect (OIDC) 已將 ID 權杖規格新增至 2.0 OAuth 定義的存取和重新整理權杖標準。ID 權杖包含身分資訊,例如您的應用程式可用於建立使用者設定檔和佈建資源的使用者屬性。如需更多資訊,請參閱了解身分 (ID) 字符

存取權杖

使用者存取許可的可驗證陳述式。存取權杖包含範圍 、 OIDC和 2.0 OAuth 的功能。您的應用程式可以呈現後端資源的範圍,並證明您的使用者集區已授權使用者或機器存取來自 的資料API,或自己的使用者資料。具有自訂範圍的存取權杖 (通常來自 M2M 用戶端憑證授予) 會授權對資源伺服器的存取。如需更多資訊,請參閱了解存取權杖

重新整理權杖

當使用者的權杖過期時,您的應用程式可以向您的使用者集區提供初始驗證的加密陳述式。重新整理權杖請求會傳回新的未過期存取和 ID 權杖。如需更多資訊,請參閱了解重新整理權杖

您可以從 Amazon Cognito 主控台中使用者集區的應用程式整合標籤,為每個應用程式用戶端設定這些權杖的到期日。

應用程式用戶端條款

下列條款是 Amazon Cognito 主控台中應用程式用戶端的可用屬性。

允許的回呼 URLs

回呼URL會指出使用者在成功登入後將重新導向的位置。選擇至少一個回呼 URL。回呼URL必須:

  • 成為絕對 URI。

  • 已向用戶端預先註冊。

  • 不包含片段元件。

請參閱 OAuth 2.0 - 重新導向端點

Amazon Cognito 必須使用 HTTPS,而不使用 HTTP,除非是 http://localhost 要進行測試。

myapp://example 也支援 URLs 等應用程式回呼。

允許登出 URLs

登出會URL指出登出後要重新引導使用者的位置。

屬性讀取和寫入許可

您的使用者集區可能有許多客戶,每個客戶都有自己的應用程式用戶端和 IdPs。您可以將應用程式用戶端設定為僅對與應用程式相關的使用者屬性具有讀取和寫入存取許可。在 machine-to-machine (M2M) 授權等情況下,您可以授予對任何使用者屬性的存取權。

屬性讀取和寫入權限組態的考量事項
  • 當您建立應用程式用戶端且不自訂屬性讀取和寫入許可時,Amazon Cognito 會授予所有使用者集區屬性的讀取和寫入許可。

  • 您可以授與不可變自訂屬性的寫入存取權。當您建立或註冊使用者時,您的應用程式用戶端可以將值寫入不可變屬性。在此之後,您無法將值寫入用戶的任何不可變自訂屬性。

  • 應用程式用戶必須具有使用者集區中必要屬性的寫入存取權。Amazon Cognito 主控台會自動將必要屬性設定為可寫入。

  • 您無法授與 email_verifiedphone_number_verified 的寫入權限給應用程式用戶。使用者集區管理員可以修改這些值。使用者只能透過屬性驗證來變更這些屬性的值。

身分驗證流程

您的應用程式用戶端允許登入的方法。您的應用程式可以支援使用者名稱和密碼的身分驗證、安全遠端密碼 (SRP)、使用 Lambda 觸發程序的自訂身分驗證,以及權杖重新整理。作為最佳安全實務,請使用SRP身分驗證作為主要登入方法。託管的 UI 會自動使用 在 中為使用者註冊SRP。

自訂範圍

自訂範圍是您在 Resource Servers (資源伺服器) 索引標籤中,為自己的資源伺服器定義的範圍。格式為 resource-server-identifier/scope。 請參閱 Scopes、M2M 和 APIs搭配資源伺服器

預設重新導向 URI

將身分驗證請求中的 redirect_uri 參數取代為第三方 IdPs。使用 CreateUserPoolClientUpdateUserPoolClientAPI請求的 DefaultRedirectURI 參數來設定此應用程式用戶端設定。這URL也必須是您應用程式用戶端 CallbackURLs 的成員。Amazon Cognito 會在下列URL情況下將已驗證的工作階段重新導向至此:

  1. 您的應用程式用戶端已指派一個身分提供者,並已定義多個回呼URLs。您的使用者集區會在未包含 redirect_uri 參數URI時,將驗證請求重新導向至授權伺服器

  2. 您的應用程式用戶端已指派一個身分提供者,並已定義一個回呼URLs。在此情況下,不需要定義預設回呼 URL。不包含redirect_uri參數重新導向至可用回呼 的請求URL。

身分提供者

您可以選擇部分或全部的使用者集區外部身分提供者 (IdPs) 來驗證您的使用者。您的應用程式用戶端也可以只驗證使用者集區中的本機使用者。當您將 IdP 新增至應用程式用戶端時,您可以產生指向 IdP 的授權連結,並將其顯示在託管的 UI 登入頁面上。您可以指派多個 IdPs,但必須至少指派一個 。如需使用外部 的詳細資訊 IdPs,請參閱 透過第三方新增使用者集區登入

OpenID Connect 範圍

選擇下列一或多個 OAuth範圍,以指定可以為存取權杖請求的存取權限。

  • openid 範圍宣告您要擷取 ID 權杖和使用者唯一 ID。它還請求全部或部分使用者屬性,具體取決於請求中的其他範圍。Amazon Cognito 不會傳回 ID 權杖,除非您請求 openid 範圍。該 openid 範圍授權結構化 ID 權杖宣告 (例如過期和金鑰 ID),並確定您在 userInfo 端點的回應中收到的使用者屬性。

    • openid 是您請求的唯一範圍時,Amazon Cognito 會使用目前應用程式用戶端可讀取的所有使用者屬性填入 ID 權杖。僅具有此範圍的存取權杖的 userInfo 回應會傳回所有使用者屬性。

    • 當您使用其他範圍 (例如 phoneemailprofile) 請求 openid 時,ID 權杖和 userInfo 將傳回使用者的唯一 ID 以及其他範圍定義的屬性。

  • phone範圍可授予對 phone_numberphone_number_verified 宣告的存取權。此範圍只能隨 openid範圍一起請求。

  • email範圍可授予對 emailemail_verified 宣告的存取權。此範圍只能隨 openid範圍一起請求。

  • aws.cognito.signin.user.admin範圍會授予需要存取權杖的 Amazon Cognito 使用者集區API操作的存取權,例如 UpdateUserAttributesVerifyUserAttribute

  • profile範圍可供存取用戶端可讀取的所有使用者屬性。此範圍只能隨 openid範圍一起請求。

如需範圍的詳細資訊,請參閱標準OIDC範圍清單

OAuth 授予類型

OAuth 授予是擷取使用者集區權杖的身分驗證方法。Amazon Cognito 支援下列三種類型的授予。若要將這些OAuth授予整合到您的應用程式中,您必須將網域新增至使用者集區。

授予授權碼

授權碼授予會產生一個程式碼,您的應用程式可以使用該程式碼與 權杖端點 交換使用者集區權杖。在您交換授權碼時,您的應用程式會接收 ID、存取和重新整理權杖。此OAuth流程,就像隱含授予一樣,都會發生在使用者的瀏覽器中。授權碼授予是 Amazon Cognito 提供的最安全的授權,因為在您使用者的工作階段中是看不到權杖的。相反,您的應用程式會產生傳回權杖的請求,並可以將其快取在受保護的儲存中。如需詳細資訊,請參閱 IETF6749 #1.3.1 RFC 中的授權碼

注意

作為公有用戶端應用程式中的最佳實務,請僅啟用授權碼授予OAuth流程,並實作 Code Exchange 的驗證金鑰 (PKCE) 來限制權杖交換。使用 時PKCE,只有在用戶端為權杖端點提供與原始身分驗證請求中呈現的相同秘密時,才能交換授權碼。如需 的詳細資訊PKCE,請參閱 IETF RFC 7636

隱含授與

隱含授予會將存取權和 ID 權杖 (但不重新整理權杖) 直接從 授權端點 交付給您的使用者瀏覽器工作階段。隱含授予會移除對權杖端點單獨請求的需求,但與 不相容PKCE,也不會傳回重新整理權杖。此授予適用於無法完成授權程式碼授予的測試案例和應用程式體系架構。如需詳細資訊,請參閱 IETF6749 #1.3.2 RFC 中的隱含授予。您可以在應用程式用戶端中啟用授權碼授予以及隱含授予,並視需要使用個別授予。

用戶端憑證授予

用戶端憑證授予適用於 machine-to-machine (M2M) 通訊。授權程式碼和隱含授予會向經過身分驗證的人類使用者發出權杖。用戶端憑證會將非互動式系統的範圍型授權授予 API。您的應用程式可以直接從權杖端點請求用戶端憑證並接收存取權杖。如需詳細資訊,請參閱 IETF6749 #1.3.4 RFC 中的用戶端憑證。您只能在具有用戶端秘密且不支援授權碼或隱含授予的應用程式用戶端中啟用用戶端憑證授予。

注意

由於您沒有以使用者身分調用用戶端憑證流程,此授予只能新增自訂範圍來存取權杖。自訂範圍是您為自己的資源伺服器定義的範圍。預設範圍如 openidprofile 不適用於非人類使用者。

由於 ID 權杖是使用者屬性的驗證,因此它們與 M2M 通訊無關,並且用戶端憑證授予不會發給它們。請參閱 Scopes、M2M 和 APIs搭配資源伺服器

用戶端憑證會授予 AWS 帳單的額外費用。如需詳細資訊,請參閱 Amazon Cognito 定價

建立應用程式用戶端

AWS Management Console
建立應用程式用戶端 (主控台)
  1. 前往 Amazon Cognito 主控台。如果出現提示,請輸入您的 AWS 憑證。

  2. 選擇 User Pools (使用者集區)。

  3. 從清單中選擇現有的使用者集區,或建立使用者集區。

  4. 選取 App integration (應用程式整合) 索引標籤。

  5. App clients (應用程式用戶端) 下,選取 Create an app client (建立應用程式用戶端)。

  6. 選取 App type (應用程式類型):Public client (公有用戶端)、Confidential client (機密用戶端),或 Other (其他)。

  7. 輸入 App client name (應用程式用戶端名稱)。

  8. 選擇 產生用戶端機密,讓 Amazon Cognito 為您產生用戶端密碼。用戶端密碼通常與機密用戶端相關聯。

  9. 選取您想要在應用程式用戶端中允許的 Authentication flows (身分驗證流程)。

  10. 設定 Authentication flow session duration (身分驗證流程工作階段持續時間)。這是您的使用者必須在工作階段字符到期之前完成每個身分驗證挑戰的時間量。

  11. (選用) 如果您想要設定權杖過期,請完成以下步驟:

    1. 指定應用程式用戶端的 Refresh token expiration (重新整理權杖過期)。預設值為 30 天。您可以將其變更為 1 小時到 10 年的任何值。

    2. 指定應用程式用戶端的 Access token expiration (存取權杖過期)。預設值為 1 小時。您可以將其變更為 5 分鐘到 24 小時的任何值。

    3. 指定應用程式用戶端的 ID token expiration (ID 權杖過期)。預設值為 1 小時。您可以將其變更為 5 分鐘到 24 小時的任何值。

      重要

      如果您使用託管 UI 並設定小於一小時的權杖生命週期,則使用者可根據目前固定在一小時的其工作階段 Cookie 持續時間,使用權杖。

  12. 選擇是否要為此應用程式用戶端 Enable token revocation (啟用權杖撤銷)。這將增加 Amazon Cognito 所簽發權杖的大小。

  13. 選擇是否要為此應用程式用戶端 防止使用者存在錯誤。Amazon Cognito 將回應不存在之使用者的登入請求,並顯示一則通用訊息,指出使用者名稱或密碼不正確。

  14. 如果要將託管 UI 與此應用程式用戶端搭配使用,請設定 託管 UI 設定

    1. 輸入一或多個允許的回呼 URLs。這些是URLs您希望 Amazon Cognito 在完成身分驗證後重新引導使用者的 Web 或應用程式。

    2. 輸入一或多個允許登出 URLs。這些URLs是您希望應用程式在 的請求中接受登出端點

    3. 選擇讓您可登入應用程式使用者的一或多個 身分提供者。您可以選擇現有 的任意組合 IdPs。您可以單獨使用您的使用者集區來驗證使用者,也可以使用您在使用者集區中設定的一或多個第三方 IdPs 來驗證使用者。

    4. 選擇您希望應用程式用戶端接受的 OAuth 2.0 授予類型

      • 選擇 授權碼授與 以將代碼傳遞給您的應用程式,該代碼可以使用 權杖端點 以兌換權杖。

      • 選取 隱含授與 以將 ID 和存取權杖直接傳遞給您的應用程式。隱含授予流程會直接向您的使用者公開權杖。

      • 選擇 用戶端登入資料,以根據其對用戶端秘密 (非使用者憑證) 之了解,將存取權杖傳遞給您的應用程式。用戶端憑證授予流程和授權代碼與隱含授予流程是互斥的。

    5. 選擇您要授權與您應用程式用戶端一起使用的 OpenID Connect 範圍。您可以透過使用者集區 產生僅包含 aws.cognito.signin.user.admin 範圍的存取權杖API。對於其他範圍,您必須向 權杖端點 要求存取權杖。

    6. 選擇您要使用應用程式用戶端授權的 自訂範圍。自訂範圍最常用於授權存取第三方 APIs。

  15. 為此應用程式用戶端設定 屬性讀取和寫入許可。您的應用程式用戶端可以擁有讀取和寫入使用者集區屬性結構描述子集之所有,或有限的許可。

  16. 選擇 Create app client (建立應用程式用戶端)

  17. 請記下 Client id (用戶端 ID)。這會識別註冊和登入請求中的應用程式用戶端。

AWS CLI
aws cognito-idp create-user-pool-client --user-pool-id MyUserPoolID --client-name myApp
注意

使用JSON格式進行回呼和登出URLs,以防止 將其CLI視為遠端參數檔案:

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

如需詳細資訊,請參閱 AWS CLI 命令參考: create-user-pool-client

Amazon Cognito user pools API

產生CreateUserPoolClientAPI請求。您必須為不想設定為預設值的所有參數指定一個值。

更新使用者集區應用程式用戶端 (AWS CLI 和 AWS API)

在 上 AWS CLI,輸入下列命令:

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, "AuthSessionValidity": 3, "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 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