本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用應用程式用戶端的應用程式特定設定 使用者集區應用程式用戶端是使用者集區內的組態，它會與透過 Amazon Cognito 進行驗證的一個行動或 Web 應用程式互動。應用程式用戶端可以呼叫已驗證和未驗證的 API 操作，以及讀取或修改您的使用者屬性的一部分或全部。您的應用程式必須在註冊、登入及處理忘記密碼的操作過程中，對應用程式用戶端表明自己的身分。這些 API 請求必須包含具有應用程式用戶端 ID 的自我識別，以及具有選用用戶端密碼的授權。您必須保護任何應用程式用戶端 ID 或密碼的安全，如此只有經授權的用戶端應用程式可以呼叫這些未驗證的操作。此外，如果您將應用程式設定為使用 AWS 登入資料簽署已驗證的 API 請求，則必須保護登入資料免遭使用者檢查。 您可以為使用者集區建立多個應用程式。應用程式用戶端可能會連結至應用程式的程式碼平台，或是使用者集區中的另一個租用戶。例如，您可能為伺服器端應用程式建立一個應用程式，以及建立不同的 Android 應用程式。每個應用程式都有自己的應用程式用戶端 ID。 您可以在應用程式用戶端層級套用下列使用者集區功能的設定： 1. [分析](cognito-user-pools-pinpoint-integration.md) 1. [受管登入](cognito-user-pools-managed-login.md) IdPs、授予類型、回呼 URLs和自訂 1. [資源伺服器和自訂範圍](cognito-user-pools-define-resource-servers.md) 1. [威脅防護](cognito-user-pool-settings-threat-protection.md) 1. [屬性讀取和寫入許可](user-pool-settings-attributes.md#user-pool-settings-attribute-permissions-and-scopes) 1. [字符過期和撤銷](amazon-cognito-user-pools-using-tokens-with-identity-providers.md) 1. [身分驗證流程](authentication.md#amazon-cognito-user-pools-authentication-flow) ## 應用程式用戶端類型 在 Amazon Cognito 中建立應用程式用户端時，您可以根據標準 OAuth 用户端類型 **public client** (公有用戶端) 和 **confidential client** (機密用戶端) 預先填入選項。以 **client secret** (用户端密碼) 設定 **confidential client** (機密用户端)。如需有關用戶端類型的詳細資訊，請參閱 [IETF RFC 6749 \$12.1](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1)。 **Public client** (公有用户端) 公有用户端在瀏覽器或行動裝置上執行。因為它沒有受信任的伺服器端資源，因此沒有用户端密碼。 **Confidential client** (機密用户端) 機密用户端具有伺服器端資源，這些資源可透過 **client secret** (用户端密碼) 受到信任以用於未經身分驗證的 API 操作。應用程式可在後端伺服器上作為常駐程式或 Shell 指令碼執行。 **Client secret** (用戶端密碼) 用戶端秘密 (或用戶端密碼) 是固定的字串，您的應用程式必須在對應用程式用戶端的所有 API 請求中使用它。您的應用程式用户端必須具有用户端密碼才能執行 `client_credentials` 授予。如需詳細資訊，請參閱 [IETF RFC 6749 \$12.3.1](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1)。 每個應用程式用戶端一次最多可以有兩個秘密，啟用秘密輪換而不停機。建立應用程式用戶端時，您可以讓 Amazon Cognito 產生秘密值或提供您自己的自訂秘密值。您無法在建立應用程式後變更密碼。您可以使用 [AddUserPoolClientSecret](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AddUserPoolClientSecret.html) API 操作新增第二個秘密來輪換秘密。新增秘密時，您可以讓 Amazon Cognito 產生秘密值或提供您自己的自訂秘密值。若要刪除秘密，請使用 [DeleteUserPoolClientSecret](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DeleteUserPoolClientSecret.html) API 操作。您無法刪除與應用程式用戶端相關聯的唯一秘密。您也可以刪除應用程式，以封鎖從使用該應用程式用戶端 ID 的應用程式進行存取。 當您為應用程式類型選取**傳統 Web 應用程式**和**Machine-to-machine應用程式**選項時，Amazon Cognito 主控台會建立具有用戶端秘密的應用程式用戶端。選擇其中一個選項來產生用戶端秘密，或使用 [CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html) 以程式設計方式建立用戶端，並將 `GenerateSecret`設定為 `true`。 您可以在公有應用程式中使用機密用户端和用户端密碼。使用 Amazon CloudFront 代理在傳輸中新增 `SECRET_HASH`。如需詳細資訊，請參閱 AWS 部落格中的[使用 Amazon CloudFront 代理保護 Amazon Cognito 的公有用户端](https://aws.amazon.com/blogs/security/protect-public-clients-for-amazon-cognito-by-using-an-amazon-cloudfront-proxy/)。 ## JSON Web 權杖 Amazon Cognito 應用程式用戶端可以發出以下類型的 JSON Web 權杖 (JWT)。 **身分 (ID) 權杖** 您的使用者已透過您的使用者集區進行身分驗證的可驗證陳述式。OpenID Connect (OIDC) 將 [ID 權杖規範](https://openid.net/specs/openid-connect-core-1_0.html#IDToken)新增到 OAuth 2.0 定義的存取和重新整理權杖標準中。ID 權杖包含身分資訊，例如您的應用程式可用於建立使用者設定檔和佈建資源的使用者屬性。如需詳細資訊，請參閱[了解身分 (ID) 字符](amazon-cognito-user-pools-using-the-id-token.md)。 **存取權杖** 使用者存取許可的可驗證陳述式。存取權杖包含[範圍](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3)，這是 OIDC 和 OAuth 2.0 的功能。您的應用程式可以向後端資源呈現範圍，並證明您的使用者集區授權使用者或機器從 API 或其自己的使用者資料中存取資料。具有*自訂範圍*的存取權杖 (通常來自 M2M 用戶端憑證授予) 會授權對資源伺服器的存取。如需詳細資訊，請參閱[了解存取權杖](amazon-cognito-user-pools-using-the-access-token.md)。 **重新整理權杖** 當使用者的權杖過期時，您的應用程式可以向您的使用者集區提供初始驗證的加密陳述式。重新整理權杖請求會傳回新的未過期存取和 ID 權杖。如需詳細資訊，請參閱[重新整理權杖](amazon-cognito-user-pools-using-the-refresh-token.md)。 您可以從 [Amazon Cognito 主控台](https://console.aws.amazon.com/cognito/v2/idp/user-pools)中使用者集區的**應用程式用戶端**功能表，為每個應用程式用戶端設定這些權杖的過期時間。 ## 應用程式用戶端條款 下列條款是 Amazon Cognito 主控台中應用程式用戶端的可用屬性。 **允許回呼 URLs** 回呼 URL 表示使用者登入成功後，將重新導向至哪個位置。選擇至少一個回呼 URL。回呼 URL 必須： + 是絕對 URI。 + 已向用戶端預先註冊。 + 不包含片段元件。 請參閱 [OAuth 2.0 - 重新導向端點](https://tools.ietf.org/html/rfc6749#section-3.1.2)。 Amazon Cognito 必須使用 `HTTPS`，而不使用 `HTTP`，除非是 `http://localhost` 要進行測試。 同時可支援像是 `myapp://example` 等應用程式回呼 URL。 **允許的登出 URL** 登出 URL 表示您的使用者在登出之後，將重新導向至哪個位置。 **屬性讀取和寫入許可** 您的使用者集區可能有許多客戶端，每個客戶端都有自己的應用程式客戶端和 IdP。您可以將應用程式用戶端設定為僅對與應用程式相關的使用者屬性具有讀取和寫入存取許可。在機器對機器 (M2M) 授權等情況下，您可以授予任何使用者屬性的存取權。 **屬性讀取和寫入權限組態的考量事項** + 當您建立應用程式用戶端且不自訂屬性讀取和寫入許可時，Amazon Cognito 會將讀取和寫入許可授予所有使用者集區屬性。 + 您可以授與不可變[自訂屬性](user-pool-settings-attributes.md#user-pool-settings-custom-attributes.title)的寫入存取權。當您建立或註冊使用者時，您的應用程式用戶端可以將值寫入不可變屬性。在此之後，您無法將值寫入用戶的任何不可變自訂屬性。 + 應用程式用戶必須具有使用者集區中必要屬性的寫入存取權。Amazon Cognito 主控台會自動將必要屬性設定為可寫入。 + 您無法授與 `email_verified` 或 `phone_number_verified` 的寫入權限給應用程式用戶。使用者集區管理員可以修改這些值。使用者只能透過[屬性驗證](signing-up-users-in-your-app.md#allowing-users-to-sign-up-and-confirm-themselves.title)來變更這些屬性的值。 **身分驗證流程** 您的應用程式用戶端允許登入的方法。您的應用程式可以支援使用者名稱和密碼的身分驗證、電子郵件和簡訊 OTPs、通行金鑰驗證程式、使用 Lambda 觸發程序的自訂身分驗證，以及權杖重新整理。作為最佳安全實務，在自訂建置應用程式中使用 SRP 身分驗證進行使用者名稱和密碼身分驗證。 **自訂範圍** 自訂範圍是您在 **Resource Servers (資源伺服器)** 索引標籤中，為自己的資源伺服器定義的範圍。格式為 *resource-server-identifier*/*scope*。請參閱 [範圍、M2M 和資源伺服器](cognito-user-pools-define-resource-servers.md)。 **預設重新導向 URI** 使用第三方 IdPs 取代使用者身分驗證請求中的 `redirect_uri` 參數。使用 [CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html) 或 [UpdateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolClient.html) API 請求的 `DefaultRedirectURI` 參數來設定此應用程式用戶端設定。此 URL 也必須是應用程式用戶端`CallbackURLs`的 成員。下列情況下，Amazon Cognito 會將已驗證的工作階段重新導向至此 URL： 1. 您的應用程式用戶端已指派一個[身分提供者](#app-client-terms-identity-provider)，並已定義多個[回呼 URLs](#app-client-terms-callback-urls)。您的使用者集區在不包含`redirect_uri`參數時，會將身分驗證請求重新導向至[授權伺服器](authorization-endpoint.md)至預設重新導向 URI。 1. 您的應用程式用戶端已指派一個[身分提供者](#app-client-terms-identity-provider)，並已定義一個[回呼 URLs](#app-client-terms-callback-urls)。在這種情況下，您不需要定義預設回呼 URL。不包含`redirect_uri`參數重新導向至一個可用回呼 URL 的請求。 **身分提供者** 您可以選擇部分或所有使用者集區外部身分提供者 (IdP) 來驗證您的使用者。您的應用程式用戶端也可以只驗證使用者集區中的本機使用者。當您將 IdP 新增至應用程式用戶端時，您可以產生 IdP 的授權連結，並將其顯示在受管登入頁面上。您可以指派多個 IdP，但您必須至少啟用一個。如需使用外部 IdP 的詳細資訊，請參閱[使用第三方身分提供者登入使用者集區](cognito-user-pools-identity-federation.md)。 **OpenID Connect 範圍** 選擇下列一或多個 `OAuth`範圍，以指定可以為存取權杖請求的存取權限。 + `openid` 範圍宣告您要擷取 ID 權杖和使用者唯一 ID。它還請求全部或部分使用者屬性，具體取決於請求中的其他範圍。Amazon Cognito 不會傳回 ID 權杖，除非您請求 `openid` 範圍。該 `openid` 範圍授權結構化 ID 權杖宣告 (例如過期和金鑰 ID)，並確定您在 [userInfo 端點](userinfo-endpoint.md)的回應中收到的使用者屬性。 + 當 `openid` 是您請求的唯一範圍時，Amazon Cognito 會使用目前應用程式用戶端可讀取的所有使用者屬性填入 ID 權杖。僅具有此範圍的存取權杖的 `userInfo` 回應會傳回所有使用者屬性。 + 當您使用其他範圍 (例如 `phone`、`email` 或 `profile`) 請求 `openid` 時，ID 權杖和 `userInfo` 將傳回使用者的唯一 ID 以及其他範圍定義的屬性。 + `phone`範圍可授予對 `phone_number` 和 `phone_number_verified` 宣告的存取權。此範圍只能隨 `openid`範圍一起請求。 + `email`範圍可授予對 `email` 和 `email_verified` 宣告的存取權。此範圍只能隨 `openid`範圍一起請求。 + `aws.cognito.signin.user.admin` 範圍授予對需要存取權杖的 [Amazon Cognito 使用者集區 API 操作](authentication-flows-public-server-side.md#user-pools-API-operations)的存取權限，例如 [UpdateUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserAttributes.html) 和 [VerifyUserAttribute](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_VerifyUserAttribute.html)。 + `profile`範圍可供存取用戶端可讀取的所有使用者屬性。此範圍只能隨 `openid`範圍一起請求。 如需有關範圍的詳細資訊，請參閱[標準 OIDC 範圍](http://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims)清單。 **OAuth 授予類型** OAuth 授予是一種擷取使用者集區權杖的身分驗證方法。Amazon Cognito 支援下列三種類型的授予。若要將這些 OAuth 授予整合到應用程式中，您必須將網域新增至使用者集區。 **授予授權碼** 授權碼授予會產生一個程式碼，您的應用程式可以使用該程式碼與 [權杖端點](token-endpoint.md) 交換使用者集區權杖。在您交換授權碼時，您的應用程式會接收 ID、存取和重新整理權杖。此 OAuth 流程與隱含授予一樣，發生在使用者的瀏覽器中。授權碼授予是 Amazon Cognito 提供的最安全的授權，因為在您使用者的工作階段中是看不到權杖的。相反，您的應用程式會產生傳回權杖的請求，並可以將其快取在受保護的儲存中。如需詳細資訊，請參閱 [IETF RFC 6749 \$11.3.1](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1) 中的*授權碼* 作為公有用戶端應用程式的最佳安全實務，應僅啟用授予 OAuth 流程的授權程式碼，並實現代碼交換證明金鑰 (PKCE) 以限制權杖交換。透過 PKCE，只有在用戶端向權杖端點提供了與原始身分驗證請求中提供的相同秘密時，用戶端才能交換授權碼。如需 PKCE 詳細資訊，請參閱 [IETF RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636)。 **隱含授與** 隱含授予會將存取權和 ID 權杖 (但不重新整理權杖) 直接從 [授權端點](authorization-endpoint.md) 交付給您的使用者瀏覽器工作階段。隱含授予移除了對權杖端點單獨請求的需求，但與 PKCE 不相容，並且不會傳回重新整理權杖。此授予適用於無法完成授權程式碼授予的測試案例和應用程式體系架構。如需詳細資訊，請參閱 [IETF RFC 6749 \$11.3.2](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.2) 中的*隱含授予*。您可以在應用程式用戶端中啟用授權碼授予以及隱含授予，並視需要使用個別授予。 **用戶端憑證授予** 用戶端憑證授予是用於機器對機器 (M2M) 的通訊。授權程式碼和隱含授予會向經過身分驗證的人類使用者發出權杖。用戶端憑證會將以範圍為基礎的授權從非互動式系統授予 API。您的應用程式可以直接從權杖端點請求用戶端憑證並接收存取權杖。如需詳細資訊，請參閱 [IETF RFC 6749 \$11.3.4](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4) 中的*用戶端憑證*。您只能在具有用戶端秘密且不支援授權碼或隱含授予的應用程式用戶端中啟用用戶端憑證授予。 由於您沒有以使用者身分調用用戶端憑證流程，此授予只能新增*自訂*範圍來存取權杖。自訂範圍是您為自己的資源伺服器定義的範圍。預設範圍如 `openid` 和 `profile` 不適用於非人類使用者。 由於 ID 權杖是使用者屬性的驗證，因此它們與 M2M 通訊無關，並且用戶端憑證授予不會發給它們。請參閱 [範圍、M2M 和資源伺服器](cognito-user-pools-define-resource-servers.md)。 用戶端登入資料會授與 AWS 帳單的額外費用。如需詳細資訊，請參閱 [Amazon Cognito 定價](https://aws.amazon.com/cognito/pricing)。 ## 建立應用程式用戶端 ------ #### [ AWS 管理主控台 ] **建立應用程式用戶端 (主控台)** 1. 前往 [Amazon Cognito 主控台](https://console.aws.amazon.com/cognito/home)。如果出現提示，請輸入您的 AWS 登入資料。 1. 選擇 **User Pools** (使用者集區)。 1. 從清單中選擇現有的使用者集區，或建立使用者集區。這兩個選項都會提示您使用應用程式特定的設定來設定應用程式用戶端。 1. 選擇反映您應用程式架構的應用程式**類型**。 1. 使用易記識別符為您的**應用程式命名**。 1. 輸入**傳回 URL**。 1. 選擇 **Create app client (建立應用程式用戶端)**。您可以在建立應用程式用戶端後變更進階選項。 1. Amazon Cognito 會將您傳回應用程式用戶端詳細資訊。若要存取應用程式的範例程式碼，請從**快速設定指南**索引標籤中選取平台。 ------ #### [ AWS CLI ] ``` aws cognito-idp create-user-pool-client --user-pool-id MyUserPoolID --client-name myApp ``` **注意** 請使用 JSON 格式的回呼和登出 URL，以防止 CLI 將其視為遠端參數檔案： ``` --callback-urls "["https://example.com"]" --logout-urls "["https://example.com"]" ``` 如需詳細資訊，請參閱 AWS CLI 命令參考：[create-user-pool-client](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/create-user-pool-client.html) ------ #### [ Amazon Cognito user pools API ] 產生 [CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html) API 請求。您必須為不想設定為預設值的所有參數指定一個值。 ------ ## 更新使用者集區應用程式用戶端 (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](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/update-user-pool-client.html)。 AWS API：[UpdateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolClient.html) ## 取得使用者集區應用程式用戶端 (AWS CLI 和 AWS API) 的相關資訊 ``` aws cognito-idp describe-user-pool-client --user-pool-id MyUserPoolID --client-id MyClientID ``` 如需詳細資訊，請參閱 AWS CLI 命令參考： [describe-user-pool-client](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/describe-user-pool-client.html)。 AWS API：[DescribeUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeUserPoolClient.html) ## 列出使用者集區 (AWS CLI 和 AWS API) 中的所有應用程式用戶端資訊 ``` aws cognito-idp list-user-pool-clients --user-pool-id "MyUserPoolID" --max-results 3 ``` 如需詳細資訊，請參閱 AWS CLI 命令參考：[list-user-pool-clients](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/list-user-pool-clients.html)。 AWS API：[ListUserPoolClients](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ListUserPoolClients.html) ## 刪除使用者集區應用程式用戶端 (AWS CLI 和 AWS API) ``` aws cognito-idp delete-user-pool-client --user-pool-id "MyUserPoolID" --client-id "MyAppClientID" ``` 如需詳細資訊，請參閱 AWS CLI 命令參考：[delete-user-pool-client](https://docs.aws.amazon.com/cli/latest/reference/cognito-idp/delete-user-pool-client.html) AWS API：[DeleteUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DeleteUserPoolClient.html)