AWS cognito documentation change
Summary
Expanded explanation of authorization models (IAM-authorized, public, token-authorized) and added details about client/server-side operation differences. Added WebAuthn operations to token-authorized table.
Security assessment
Changes clarify security-related authorization models and add documentation for WebAuthn security features. No evidence of addressing a specific vulnerability.
Diff
diff --git a/cognito/latest/developerguide/authentication-flows-public-server-side.md b/cognito/latest/developerguide/authentication-flows-public-server-side.md index 1da1adb49..869cfbd38 100644 --- a//cognito/latest/developerguide/authentication-flows-public-server-side.md +++ b//cognito/latest/developerguide/authentication-flows-public-server-side.md @@ -9 +9,5 @@ Server-side authentication optionsClient-side authentication optionsUsing the AP -When you start out with user pools authentication, you must decide on your application authorization model. Amazon Cognito authentication typically requires that you implement two API operations in order. The API operations that you use for authentication depend on the characteristics of your application. Public clients, where the application is distributed to users, use public authentication, where requests for sign-in don't require authorization. Server-side clients, where the application logic is hosted on a remote system, can protect authentication operations with IAM authorization for sign-in requests. The following API operation pairs and their corresponding SDK methods map to each of the available authorization models. +When you're starting development of your application with user pools authentication, you must decide on the API authorization model that fits your application type. An authorization model is a system for providing authorization to make requests with the authentication components in the Amazon Cognito user pools API and SDK integrations. Amazon Cognito has three authorization models: IAM-authorized, public, and token-authorized. + +With IAM-authorized requests, the authorization comes from a signature by a set of AWS IAM credentials in the `Authorization` header of a request. For server-side applications, this practice protects authentication operations with IAM authorization. With public (unauthenticated) authentication requests, no authorization is required. This is suitable for client-side applications distributed to users. With token-authorized operations, typically implemented in combination with public operations, the authorization comes from a session token or an access token included in the `Authorization` header of the request. Amazon Cognito authentication typically requires that you implement two or more API operations in order, and the API operations you use depend on the characteristics of your application. Public clients, where the application is distributed to users, use public operations, where requests for sign-in don't require authorization. Token-authorized operations continue the session of users in public applications. Server-side clients, where the application logic is hosted on a remote system, protect authentication operations with IAM authorization for sign-in requests. The API operation pairs that follow, and their corresponding SDK methods, map to the available authorization models. + +Each public authentication operation has some form of server-side equivalent, for example [UpdateUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserAttributes.html) and [AdminUpdateUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html). While client-side operations are user-initiated and require confirmation, server-side operations assume the change was committed by a user pool administrator and changes take immediate effect. In this example, Amazon Cognito sends a message with a confirmation code to the user, and the user's access token authorizes a [VerifyUserAttribute](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_VerifyUserAttribute.html) request that submits the code. The server-side application can immediately set the value of any attribute, although [special considerations apply](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html#CognitoUserPools-AdminUpdateUserAttributes-request-UserAttributes) for changing the value of email addresses and phone numbers when they're used for sign-in. @@ -16 +20,5 @@ Client-side (public) authentication - 1. [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) +The following is a typical sequence of requests in a client-side application + + 1. The public [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) operation submits primary credentials like a username and password. + + 2. The token-authorized [RespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html) operation submits a _session_ token from the `InitiateAuth` response and the answer to a challenge, for example MFA. Session token authorization indicates requests that are part of not-yet-complete authentication cycles. @@ -18 +26 @@ Client-side (public) authentication - 2. [RespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html) + 3. The token-authorized [ConfirmDevice](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmDevice.html) operation submits an _access_ token and performs the write operation of adding a remembered device to the user's profile. Access token authorization indicates requests that are for user self-service operations after they have completed authentication. @@ -23 +31 @@ Client-side (public) authentication -`InitiateAuth` and `RespondToAuthChallenge` are unauthenticated APIs for use with client-side public app clients. For more information, see Client-side authentication options and Understanding API, OIDC, and managed login pages authentication. +For more information, see Client-side authentication options and Understanding API, OIDC, and managed login pages authentication. @@ -28 +36 @@ Server-side authentication - 1. [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) +The following is a typical sequence of requests from a server-side operation. Each request has an [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) authorization header signed with IAM machine credentials that were issued to the application server. @@ -30 +38 @@ Server-side authentication - 2. [AdminRespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminRespondToAuthChallenge.html) + 1. The [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) operation submits primary credentials like a username and password. @@ -31,0 +40 @@ Server-side authentication + 2. [AdminRespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminRespondToAuthChallenge.html) operation submits the answer to a challenge, for example MFA. @@ -32,0 +42 @@ Server-side authentication + 3. The [AdminUpdateDeviceStatus](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateDeviceStatus.html) operation sets the device key from the `AdminInitiateAuth` [response](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html#API_AdminInitiateAuth_ResponseSyntax) as remembered. @@ -35 +45,3 @@ Server-side authentication -`AdminInitiateAuth` and `AdminRespondToAuthChallenge` require IAM credentials and are suited for server-side confidential app clients. For more information, see Server-side authentication options and Understanding API, OIDC, and managed login pages authentication. + + +For more information, see Server-side authentication options and Understanding API, OIDC, and managed login pages authentication. @@ -52 +64 @@ A user authenticates by answering successive challenges until authentication eit -Web applications and other _server-side_ applications implement authentication in a session on a remote server, usually in a browser that initiates a session to that server. Server-side applications typically have the following characteristics. +Web applications and other _server-side_ applications implement authentication on a remote server that a client loads in a remote-display application like a browser or SSH session. Server-side applications typically have the following characteristics. @@ -86 +98 @@ Because backend admin implementations use the admin authentication flow, the flo -Mobile apps and other _client-side_ application types installed on users' devices typically have the following characteristics. +Mobile apps and other _client-side_ application types are installed on users' devices and perform the logic of authentication and user interface locally. They typically have the following characteristics. @@ -208 +220 @@ The Amazon Cognito user pools API, both a resource-management interface and a us -You can only assign permissions in IAM policies for IAM-authenticated management operations and IAM-authenticated user operations. +You can only assign permissions in IAM policies for IAM-authorized management operations and IAM-authorized user operations. @@ -210 +222 @@ You can only assign permissions in IAM policies for IAM-authenticated management -IAM-authenticated management operations modify and view your user pool and app client configuration, like you would do in the AWS Management Console. +IAM-authorized management operations modify and view your user pool and app client configuration, like you would do in the AWS Management Console. @@ -216 +228 @@ To authorize these requests in the AWS Command Line Interface (AWS CLI) or an AW -IAM-authenticated management operations +IAM-authorized management operations @@ -268 +280 @@ IAM-authenticated management operations -IAM-authenticated user operations sign up, sign in, manage credentials for, modify, and view your users. +IAM-authorized user operations sign up, sign in, manage credentials for, modify, and view your users. @@ -276 +288 @@ If your app client has a client secret, you must provide both your IAM credentia -IAM-authenticated user operations +IAM-authorized user operations @@ -334,0 +347,4 @@ Token-authorized user operations | AccessToken | Session +`StartWebAuthnRegistration` | ✓ | +`CompleteWebAuthnRegistration` | ✓ | +`DeleteWebAuthnCredential` | ✓ | +`ListWebAuthnCredentials` | ✓ | @@ -348 +363,0 @@ Token-authorized user operations | AccessToken | Session -`AssociateSoftwareToken` | ✓ | ✓ @@ -349,0 +365 @@ Token-authorized user operations | AccessToken | Session +`AssociateSoftwareToken` | ✓ | ✓