重新導向和授權端點 - Amazon Cognito
GET /oauth2/authorize具有正面回應的請求範例負向回應的範例

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

重新導向和授權端點

/oauth2/authorize 端點是支援兩個重新導向目的地的重新導向端點。如果您在 中包含 identity_provider或 idp_identifier 參數URL，則會將使用者無訊息重新導向至該身分提供者 （IdP ） 的登入頁面。否則，它會重新導向至登入端點具有與您在請求中包含之相同URL參數的 。

授權端點重新導向至託管 UI 或 IdP 登入頁面。此端點上的使用者工作階段目的地是使用者必須直接在瀏覽器中與之互動的網頁。

若要使用授權端點，請在 /oauth2/authorize 叫用使用者的瀏覽器，並搭配為使用者集區提供有關下列使用者集區詳細資訊的參數。

  • 您要登入的應用程式用戶端。

  • URL 您想要最終的回呼。

  • 您想要在使用者的存取權杖中請求的 OAuth 2.0 範圍。

  • 或者，您要用來登入的第三方 IdP。

您也可以提供 state 和 nonce 參數，讓 Amazon Cognito 用來驗證傳入宣告。

GET /oauth2/authorize

/oauth2/authorize 端點僅支援 HTTPS GET。您的應用程式通常會在使用者的瀏覽器中啟動此請求。您只能透過 向/oauth2/authorize端點提出請求HTTPS。

您可以在授權端點 的 OpenID Connect （OIDC） 標準中進一步了解授權端點的定義。

請求參數

response_type

（必要） 回應類型。必須是 code 或 token。

response_type 為 code 的成功請求會傳回授權碼授與。授權碼授予是 Amazon Cognito 附加至重新導向 的code參數URL。您的應用程式可以針對存取、ID 及重新整理權杖和 權杖端點 交換代碼。作為安全最佳實務，並為您的使用者接收重新整理權杖，請在您的應用程式中使用授權碼授與。

具有 token 之 response_type 的成功請求會傳回隱含授與。隱含授予是 Amazon Cognito 附加至重新導向 的 ID 和存取權杖URL。隱含授與不太安全，因為它會向使用者公開權杖和潛在的識別資訊。您可以在應用程式用戶端的組態中停用對隱含授與的支援。

client_id

（必要） 應用程式用戶端 ID。

client_id 的值必須是您提出請求之使用者集區中應用程式用戶端的 ID。您的應用程式用戶端必須支援 Amazon Cognito 本機使用者或至少一個第三方 IdP 登入。

redirect_uri

（必要） 驗證伺服器URL在 Amazon Cognito 授權使用者之後重新導向瀏覽器的 。

重新導向統一資源識別碼 （URI） 必須具有下列屬性：

  • 它必須是絕對 URI。

  • 您必須已URI向用戶端預先註冊 。

  • 不得包含片段元件。

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

Amazon Cognito 要求您的重新導向URI使用 HTTPS，但 除外http://localhost，您可以將其設定為回呼URL以供測試之用。

Amazon Cognito 也支援應用程式回呼，URLs例如 myapp://example。

state

（選用，建議） 當您的應用程式將狀態參數新增至請求時，Amazon Cognito 會在/oauth2/authorize端點重新引導您的使用者時將其值傳回至您的應用程式。

將此值新增至您的請求，以防止CSRF攻擊。

您無法將 state 參數的值設定為 URL編碼字串JSON。若要在state參數中傳遞與此格式相符的字串，請將字串編碼為 base64，然後在應用程式中解碼。

identity_provider

（選用） 新增此參數以略過託管 UI，並將您的使用者重新導向至提供者登入頁面。identity_provider 參數的值是身分提供者 (IdP) 在使用者集區中顯示的名稱。

  • 對於社交提供者，您可以使用 identity_provider 值 Facebook、Google、 LoginWithAmazon和 SignInWithApple。

  • 對於 Amazon Cognito 使用者集區，請使用 值 COGNITO。

  • 對於 SAML 2.0 和 OpenID Connect （OIDC） 身分提供者 （IdPs），使用您在使用者集區中指派給 IdP 的名稱。

idp_identifier

（選用） 新增此參數以重新導向至具有 identity_provider 名稱替代名稱的提供者。您可以從 Amazon Cognito 主控台的OIDC IdPs 登入體驗索引標籤輸入 SAML 2.0 的識別符。

scope

（選用） 可以是與用戶端相關聯的任何系統保留範圍或自訂範圍的組合。範圍必須以空格隔開。系統預留範圍為 openid、email、phone、profile 和 aws.cognito.signin.user.admin。所使用的任何範圍都必須與用戶端建立關聯，否則在執行時間會將其忽略。

如果用戶端沒有請求任何範圍，則身分驗證伺服器會使用與用戶端相關聯的所有範圍。

只有在請求 openid 範圍時，才會傳回 ID 權杖。只有在請求 aws.cognito.signin.user.admin 範圍時，才能對 Amazon Cognito 使用者集區使用存取權杖。只有在也同時請求 phone 範圍時，才能請求 email、profile 和 openid 範圍。這些範圍需要有進入 ID 權杖中的宣告。

code_challenge_method

（選用） 您用來產生挑戰的雜湊通訊協定。PKCE RFC 定義了兩種方法：S256 和純；不過，Amazon Cognito 身分驗證伺服器僅支援 S256。

code_challenge

（選用） 您從 產生的金鑰程式碼交換 （PKCE） 挑戰的證明code_verifier。如需詳細資訊，請參閱在授權碼授予PKCE中使用。

僅當您指定 code_challenge_method 參數時才需要。

nonce

（選用） 可新增至請求的隨機值。您提供的 nonce 值包含在 Amazon Cognito 發出的 ID 權杖中。為了防止重播攻擊，您的應用程式可以檢查 ID 權杖中的 nonce 宣告並將其與您產生的權杖進行比較。如需 nonce 宣告的詳細資訊，請參閱 OpenID Connect standard (OpenID Connect 標準) 中的 ID token validation (ID 權杖驗證)。

login_hint

您要傳遞給授權伺服器的使用者名稱提示。您可以從使用者收集使用者名稱、電子郵件地址或電話號碼，並允許目的地提供者預先填入使用者的登入名稱。當您將login_hint參數和無 idp_identifier或 identity_provider 參數提交至oauth2/authorize端點時，託管 UI 會以提示值填入使用者名稱欄位。您也可以將此參數傳遞至 ，登入端點並自動填入使用者名稱值。

當您的授權請求調用重新導向至 OIDC IdPs 或 Google 時，Amazon Cognito 會將 login_hint 參數新增至該第三方授權方。您無法將登入提示轉送至 SAML、Apple、使用 Amazon 登入或 Facebook （Meta） IdPs。

具有正面回應的請求範例

下列範例說明 /oauth2/authorize端點HTTP請求的格式。

授予授權碼

這是授權碼授予的範例請求。

範例 – GET請求

下列請求會啟動工作階段，以擷取您的使用者在redirect_uri目的地傳送到您應用程式的授權碼。此工作階段會請求使用者屬性的範圍，以及對 Amazon Cognito 自助API操作的存取。

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=openid+profile+aws.cognito.signin.user.admin
範例 – 回應

Amazon Cognito 身分驗證伺服器會附上授權碼和狀態，重新引導回應用程式。授權碼的有效期限為五分鐘。

HTTP/1.1 302 Found
Location: https://www.example.com?code=a1b2c3d4-5678-90ab-cdef-EXAMPLE11111&state=abcdefg

授權碼授予搭配 PKCE

這是使用 授予授權碼的範例請求PKCE。

範例 – GET請求

下列請求會將code_challenge參數新增至先前的請求。若要完成權杖的程式碼交換，您必須在對/oauth2/token端點的請求中包含 code_verifier 參數。

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=code&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=aws.cognito.signin.user.admin&
code_challenge_method=S256&
code_challenge=a1b2c3d4...
範例 – 回應

身分驗證伺服器會使用授權碼和狀態重新引導回您的應用程式。程式碼和狀態必須在查詢字串參數中傳回，而不是在片段中：

HTTP/1.1 302 Found
Location: https://www.example.com?code=a1b2c3d4-5678-90ab-cdef-EXAMPLE11111&state=abcdefg

授予權杖，不含 openid 範圍

這是產生隱含授予並JWTs直接返回使用者工作階段的範例請求。

範例 – GET請求

下列請求適用於來自授權伺服器的隱含授予。Amazon Cognito 的存取權杖會授權自助API操作。

GET https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize?
response_type=token&
client_id=1example23456789&
redirect_uri=https://www.example.com&
state=abcdefg&
scope=aws.cognito.signin.user.admin
範例 – 回應

Amazon Cognito 授權伺服器會附上存取權杖，重新引導回應用程式。由於未請求 openid 範圍，Amazon Cognito 不會傳回 ID 權杖。此外，Amazon Cognito 不會在此流程中傳回重新整理權杖。Amazon Cognito 會在片段中傳回存取權杖和狀態，而不是在查詢字串中：

HTTP/1.1 302 Found
Location: https://YOUR_APP/redirect_uri#access_token=ACCESS_TOKEN&token_type=bearer&expires_in=3600&state=STATE

授予權杖，含 openid 範圍

這是產生隱含授予並JWTs直接返回使用者工作階段的範例請求。

範例 – GET請求

下列請求適用於來自授權伺服器的隱含授予。Amazon Cognito 的存取權杖會授權存取使用者屬性和自助API操作。

GET
https://mydomain.auth.us-east-1.amazoncognito.com/oauth2/authorize? 
response_type=token& 
client_id=1example23456789& 
redirect_uri=https://www.example.com& 
state=abcdefg&
scope=aws.cognito.signin.user.admin+openid+profile
範例 – 回應

授權伺服器會使用存取權杖和 ID 權杖重新引導回您的應用程式 （因為包含openid範圍）：

HTTP/1.1 302 Found
Location: https://www.example.com#id_token=eyJra67890EXAMPLE&access_token=eyJra12345EXAMPLE&token_type=bearer&expires_in=3600&state=abcdefg

負向回應的範例

Amazon Cognito 可能會拒絕您的請求。負面請求隨附HTTP錯誤碼和描述，您可以用來修正請求參數。以下是負面回應的範例。

  • 如果 client_id和 redirect_uri 有效，但請求參數格式不正確，則身分驗證伺服器會將錯誤重新導向至用戶端，redirect_uri並在URL參數中附加錯誤訊息。以下是格式不正確的範例。

    • 請求不包含 response_type 參數。

    • 授權請求提供 code_challenge 參數，但不是 code_challenge_method 參數。

    • code_challenge_method 參數的值不是 S256。

    以下是對格式不正確之範例請求的回應。

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request

  • 如果用戶端在 token中請求 code或 response_type，但沒有這些請求的許可，Amazon Cognito 授權伺服器會傳回unauthorized_client用戶端的 redirect_uri，如下所示：

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=unauthorized_client

  • 如果用戶端請求的範圍不明、範圍格式不正確或無效，Amazon Cognito 授權伺服器會將 invalid_scope 傳回用戶端的 redirect_uri，如下所示：

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_scope

  • 如果伺服器中有任何非預期的錯誤，身分驗證伺服器server_error會傳回用戶端的 redirect_uri。由於 HTTP 500 錯誤不會傳送至用戶端，因此錯誤不會顯示在使用者的瀏覽器中。授權伺服器傳回下列錯誤。

    HTTP 1.1 302 Found Location: https://client_redirect_uri?error=server_error

  • 當 Amazon Cognito 透過聯合驗證第三方 時 IdPs，Amazon Cognito 可能會遇到連線問題，例如：

    • 如果在向 IdP 請求權杖時，發生連線逾時，身分驗證伺服器則會如下所示，將錯誤重新導向至用戶端的 redirect_uri：

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Timeout+occurred+in+calling+IdP+token+endpoint

    • 如果在呼叫jwks_uri端點進行 ID 字符驗證時發生連線逾時，身分驗證伺服器會以錯誤重新導向至用戶端redirect_uri，如下所示：

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=error_description=Timeout+in+calling+jwks+uri

  • 透過聯合第三方進行身分驗證時 IdPs，供應商可能會傳回錯誤回應。這可能是由於組態錯誤或其他原因所造成，例如：

    • 如果從其他供應商收到錯誤回應，身分驗證伺服器則會如下所示，將錯誤重新導向至用戶端的 redirect_uri：

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=[IdP name]+Error+-+[status code]+error getting token

    • 如果從 Google 收到錯誤回應，身分驗證伺服器則會如下所示，將錯誤重新導向至用戶端的 redirect_uri：

      HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Google+Error+-+[status code]+[Google-provided error code]

  • 當 Amazon Cognito 連線到外部 IdP 時遇到通訊例外狀況時，身分驗證伺服器會使用下列redirect_uri任一訊息，以錯誤的方式重新導向至用戶端的 ：

    • HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Connection+reset
    • HTTP 1.1 302 Found Location: https://client_redirect_uri?error=invalid_request&error_description=Read+timed+out