AWS cognito: Document step-up auth parameters (acr_values, max_age) on /login endpoint
Summary
Adds a new 'Step-up authentication request' section to the managed login /login endpoint page, documenting the acr_values and max_age URL parameters, their equivalence to TARGET_ACR_VALUES/MAX_AGE API parameters, feature-plan requirements, and the silent-ignore behavior on insufficient plans. Also updates the example client_id value.
Security assessment
The added text documents how to require a specific authentication level (ACR) and recent authentication (max_age) for sensitive operations, which is security best-practice guidance for step-up authentication rather than a fix for a specific vulnerability.
Evidence
+Combine `acr_values` with `max_age` to require a specific authentication level with recent authentication for a sensitive operation.
Diff
diff --git a/cognito/latest/developerguide/login-endpoint.md b/cognito/latest/developerguide/login-endpoint.md index d7c96fe..ade1505 100644 --- a//cognito/latest/developerguide/login-endpoint.md +++ b//cognito/latest/developerguide/login-endpoint.md @@ -7 +7 @@ -GET /loginUser-initiated sign-in request +GET /loginUser-initiated sign-in requestStep-up authentication request @@ -28 +28 @@ This example displays the login screen. - client_id=ad398u21ijw3s9w3939& + client_id=1example23456789& @@ -46,0 +47,20 @@ After your user loads the `/login` endpoint, they can enter a user name and pass +## Step-up authentication request + +The `/login` endpoint accepts the following URL parameters for step-up authentication. These parameters have the same behavior as on the [authorize endpoint](./authorization-endpoint.html#authorization-endpoint-step-up). For more information about ACR levels and AMR values, see [Authentication levels with ACR and AMR claims](./cognito-user-pools-step-up-authentication.html). + +`acr_values` + + +A space-separated, URL-encoded list of target ACR authentication level URIs, from highest to lowest. Amazon Cognito evaluates the list from left to right, enforces the first valid level that the user can satisfy, and ignores values that it doesn't recognize. This parameter behaves the same as the `TARGET_ACR_VALUES` API parameter. Requires the Essentials or Plus feature plan. + +`max_age` + + +A non-negative integer that specifies the maximum number of seconds since the user last authenticated. If the current time minus `auth_time` is greater than `max_age`, the user must authenticate again from scratch instead of only stepping up. This behavior is identical to the `MAX_AGE` API parameter. + +For an example request that uses these parameters, see the [authorize endpoint](./authorization-endpoint.html#authorization-endpoint-step-up). + +Combine `acr_values` with `max_age` to require a specific authentication level with recent authentication for a sensitive operation. + +The behavior on an insufficient feature plan differs from the API. The managed login `/login` endpoint silently ignores `acr_values` and proceeds with normal authentication, without an error. The API returns a `FeatureUnavailableInTierException`. For more information, see [Feature plan requirements](./cognito-user-pools-step-up-authentication.html#cognito-user-pools-step-up-authentication-tiers). +