chore: Update enhanced auth flow public docs (#544)

--------- Co-authored-by: Quinn Hanam <hanquinn@amazon.com>
aws-observability · Apr 16, 2024 · 34ce323 · 34ce323
1 parent d8b2b05
commit 34ce323
Show file tree

Hide file tree

Showing 8 changed files with 26 additions and 28 deletions.
diff --git a/docs/cdn_angular.md b/docs/cdn_angular.md
@@ -9,7 +9,7 @@ To install the web client in an Angular application, add the snippet inside the
 <html lang="en">
 <head>
   <script>
-    (function(n,i,v,r,s,c,u,x,z){x=window.AwsRumClient={q:[],n:n,i:i,v:v,r:r,c:c,u:u};window[n]=function(c,p){x.q.push({c:c,p:p});};z=document.createElement('script');z.async=true;z.src=s;document.head.insertBefore(z,document.getElementsByTagName('script')[0]);})('cwr','00000000-0000-0000-0000-000000000000','1.0.0','us-west-2','https://client.rum.us-east-1.amazonaws.com/1.0.2/cwr.js',{sessionSampleRate:1,guestRoleArn:'arn:aws:iam::000000000000:role/RUM-Monitor-us-west-2-000000000000-0000000000000-Unauth',identityPoolId:'us-west-2:00000000-0000-0000-0000-000000000000',endpoint:'https://dataplane.rum.us-west-2.amazonaws.com',telemetries:['errors','http','performance'],allowCookies:true});
+    (function(n,i,v,r,s,c,u,x,z){x=window.AwsRumClient={q:[],n:n,i:i,v:v,r:r,c:c,u:u};window[n]=function(c,p){x.q.push({c:c,p:p});};z=document.createElement('script');z.async=true;z.src=s;document.head.insertBefore(z,document.getElementsByTagName('script')[0]);})('cwr','00000000-0000-0000-0000-000000000000','1.0.0','us-west-2','https://client.rum.us-east-1.amazonaws.com/1.0.2/cwr.js',{sessionSampleRate:1,identityPoolId:'us-west-2:00000000-0000-0000-0000-000000000000',endpoint:'https://dataplane.rum.us-west-2.amazonaws.com',telemetries:['errors','http','performance'],allowCookies:true});
   </script>
   ...
 </head>

diff --git a/docs/cdn_commands.md b/docs/cdn_commands.md
@@ -62,7 +62,7 @@ if(awsCreds) awsRum.setAwsCredentials(credentialProvider);
 | recordError | Error \|&nbsp;ErrorEvent \|&nbsp;String | `try {...} catch(e) { cwr('recordError', e); }`<br/><br/>`try {...} catch(e) { awsRum.recordError(e); }` | Record a caught error.
 | recordEvent | [Event](#event) | `cwr('recordEvent', {type: 'your_event_type', data: {field1: 1, field2: 2}})` <br/><br/> `awsRum.recordEvent('your_event_type', {field1: 1, field2: 2})` | Record a custom event.<br/><br/>⚠️ The app monitor must have custom events enabled.<br/><br/> Event types must conform to the following regex: `^[a-zA-Z0-9_.-]{1,256}$`. <br/><br/>Each custom event, including metadata, must be less than 6 KB. Events over 6KB are dropped by CloudWatch RUM.
 | registerDomEvents | Array | `cwr('registerDomEvents', [{ event: 'click', cssLocator: '[label="label1"]' }]);`<br/><br/>`awsRum.registerDomEvents([{ event: 'click', cssLocator: '[label="label1"]' }]);` | Register target DOM events to record. The target DOM events will be added to existing target DOM events. The parameter type is equivalent to the `events` property type of the [interaction telemetry configuration](https://github.com/aws-observability/aws-rum-web/blob/main/docs/cdn_installation.md#interaction).
-| setAwsCredentials | [Credentials](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html) \|&nbsp;[CredentialProvider](https://www.npmjs.com/package/@aws-sdk/credential-providers) | `cwr('setAwsCredentials', cred);`<br/><br/>`awsRum.setAwsCredentials(cred);` | Forward AWS credentials to the web client. The web client requires AWS credentials with permission to call the `PutRumEvents` API. If you have not set `identityPoolId` and `guestRoleArn` in the web client configuration, you must forward AWS credentials to the web client using this command.
+| setAwsCredentials | [Credentials](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html) \|&nbsp;[CredentialProvider](https://www.npmjs.com/package/@aws-sdk/credential-providers) | `cwr('setAwsCredentials', cred);`<br/><br/>`awsRum.setAwsCredentials(cred);` | Forward AWS credentials to the web client. The web client requires AWS credentials with permission to call the `PutRumEvents` API. If you have not set `identityPoolId` in the web client configuration, you must forward AWS credentials to the web client using this command.
 
 ## PageView
 | Field Name | Type | Default | Example | Description |

diff --git a/docs/cdn_installation.md b/docs/cdn_installation.md
@@ -17,7 +17,7 @@ The snippet will look similar to the following:
 
 ```html
 <script>
-(function(n,i,v,r,s,c,u,x,z){x=window.AwsRumClient={q:[],n:n,i:i,v:v,r:r,c:c,u:u};window[n]=function(c,p){x.q.push({c:c,p:p});};z=document.createElement('script');z.async=true;z.src=s;document.head.insertBefore(z,document.getElementsByTagName('script')[0]);})('cwr','00000000-0000-0000-0000-000000000000','1.0.0','us-west-2','https://client.rum.us-east-1.amazonaws.com/1.0.2/cwr.js',{sessionSampleRate:1,guestRoleArn:'arn:aws:iam::000000000000:role/RUM-Monitor-us-west-2-000000000000-00xx-Unauth',identityPoolId:'us-west-2:00000000-0000-0000-0000-000000000000',endpoint:'https://dataplane.rum.us-west-2.amazonaws.com',telemetries:['errors','http','performance'],allowCookies:true});
+(function(n,i,v,r,s,c,u,x,z){x=window.AwsRumClient={q:[],n:n,i:i,v:v,r:r,c:c,u:u};window[n]=function(c,p){x.q.push({c:c,p:p});};z=document.createElement('script');z.async=true;z.src=s;document.head.insertBefore(z,document.getElementsByTagName('script')[0]);})('cwr','00000000-0000-0000-0000-000000000000','1.0.0','us-west-2','https://client.rum.us-east-1.amazonaws.com/1.0.2/cwr.js',{sessionSampleRate:1,identityPoolId:'us-west-2:00000000-0000-0000-0000-000000000000',endpoint:'https://dataplane.rum.us-west-2.amazonaws.com',telemetries:['errors','http','performance'],allowCookies:true});
 </script>
 ```
 
@@ -73,7 +73,7 @@ The code snippet accepts six arguments. The snippet below shows these arguments
 
 ## Configuring the CloudWatch RUM web client
 
-The application-specific web client configuration is a JavaScript object whose fields are all optional. While these fields are optional, depending on your application the web client may not function properly if certain fields are omitted. For example, `identityPoolId` and `guestRoleArn` are both required unless your application performs its own AWS authentication and passes the credentials to the web client using the command `cwr('setAwsCredentials', {...});`.
+The application-specific web client configuration is a JavaScript object whose fields are all optional. While these fields are optional, depending on your application the web client may not function properly if certain fields are omitted. For example, `identityPoolId` is required unless your application performs its own AWS authentication and passes the credentials to the web client using the command `cwr('setAwsCredentials', {...});`.
 
 The snippet below shows several configuration options with the body of the snippet's function omitted for readability:
 ```html
@@ -86,7 +86,6 @@ The snippet below shows several configuration options with the body of the snipp
         'https://client.rum.us-east-1.amazonaws.com/1.0.2/cwr.js',
         {
             sessionSampleRate:1,
-            guestRoleArn:'arn:aws:iam::000000000000:role/RUM-Monitor-us-west-2-000000000000-00xx-Unauth',
             identityPoolId:'us-west-2:00000000-0000-0000-0000-000000000000',
             endpoint:'https://dataplane.rum.us-west-2.amazonaws.com',
             telemetries:['errors','http','performance'],

diff --git a/docs/cdn_react.md b/docs/cdn_react.md
@@ -9,7 +9,7 @@ To install the web client in a React application, add the snippet inside the \<h
 <html lang="en">
 <head>
   <script>
-    (function(n,i,v,r,s,c,u,x,z){x=window.AwsRumClient={q:[],n:n,i:i,v:v,r:r,c:c,u:u};window[n]=function(c,p){x.q.push({c:c,p:p});};z=document.createElement('script');z.async=true;z.src=s;document.head.insertBefore(z,document.getElementsByTagName('script')[0]);})('cwr','00000000-0000-0000-0000-000000000000','1.0.0','us-west-2','https://client.rum.us-east-1.amazonaws.com/1.0.2/cwr.js',{sessionSampleRate:1,guestRoleArn:'arn:aws:iam::000000000000:role/RUM-Monitor-us-west-2-000000000000-0000000000000-Unauth',identityPoolId:'us-west-2:00000000-0000-0000-0000-000000000000',endpoint:'https://dataplane.rum.us-west-2.amazonaws.com',telemetries:['errors','http','performance'],allowCookies:true});
+    (function(n,i,v,r,s,c,u,x,z){x=window.AwsRumClient={q:[],n:n,i:i,v:v,r:r,c:c,u:u};window[n]=function(c,p){x.q.push({c:c,p:p});};z=document.createElement('script');z.async=true;z.src=s;document.head.insertBefore(z,document.getElementsByTagName('script')[0]);})('cwr','00000000-0000-0000-0000-000000000000','1.0.0','us-west-2','https://client.rum.us-east-1.amazonaws.com/1.0.2/cwr.js',{sessionSampleRate:1,identityPoolId:'us-west-2:00000000-0000-0000-0000-000000000000',endpoint:'https://dataplane.rum.us-west-2.amazonaws.com',telemetries:['errors','http','performance'],allowCookies:true});
   </script>
   ...
 </head>

diff --git a/docs/cdn_troubleshooting.md b/docs/cdn_troubleshooting.md
@@ -12,10 +12,10 @@ configuration.
 
 The web client requires AWS credentials to sign RUM payloads. When the RUM web
 client does not have AWS credentials, it will not attempt to send events to
-CloudWatch RUM. Your application must either (1) provide the web client with an
-anonymous Cognito identity using `identityPoolId` and `guestRoleArn`, or (2)
-provide the web client with AWS credentials using the `cwr('setAwsCredentials',
-credentials);` command.
+CloudWatch RUM. Your application must either (A) provide the web client with an
+anonymous Cognito identity using `identityPoolId`, (B) provide the web client
+with AWS credentials using the `cwr('setAwsCredentials', credentials);` command
+or (C) use a proxy and disable SigV4 signing by setting `signing` to `false`.
 
 ### Event limit is reached for the session
 
@@ -142,7 +142,7 @@ following trust relationship:
 
 ### Cognito's basic authflow is not enabled
 
-When the CloudWatch RUM web client is provided with both `identityPoolId` and `guestRoleArn`, the web client will use Cognito's [basic (classic) authflow](https://docs.aws.amazon.com/cognito/latest/developerguide/authentication-flow.html). If the Cognito `GetCredentialsForIdentity` operation fails, this may be because the basic (classic) authflow is not enabled for the identity pool. In this case, the response may look similar to the following:
+When the CloudWatch RUM web client is provided with both `identityPoolId` and `guestRoleArn`, the web client will use Cognito's [basic (classic) authflow](https://docs.aws.amazon.com/cognito/latest/developerguide/authentication-flow.html). If the Cognito `GetCredentialsForIdentity` operation fails, this may be because the basic (classic) authflow is not enabled in the Cognito identity pool. In this case, the response may look similar to the following:
 
 ```
 <Error>
@@ -152,15 +152,20 @@ When the CloudWatch RUM web client is provided with both `identityPoolId` and `g
 </Error>
 ```
 
-Using the Amazon Cognito console or CLI (i.e, the `aws cognito-identity
-describe-identity-pool` command), verify that the identity pool
-configuration does **not** contain `AllowClassicFlow: false`. If it does, then
-update the configuration so that it contains `AllowClassicFlow: true`.
+This can be fixed by removing `guestRoleArn` from the [web client
+configuration](configuration.md). After removing `guestRoleArn`, the web client will use Cognito's [enhanced
+(simplified) auth
+flow](https://docs.aws.amazon.com/cognito/latest/developerguide/authentication-flow.html).
+
+Alternatively, to continue using the basic auth flow, use the Amazon Cognito
+console or CLI (i.e, the `aws cognito-identity describe-identity-pool` command)
+to verify that the identity pool configuration does **not** contain
+`AllowClassicFlow: false`.  If it does, then update the configuration so that it
+contains `AllowClassicFlow: true`.
 
 See also:
 1. `AllowClassicFlow` in the [update-identity-pool CLI reference](https://docs.aws.amazon.com/cli/latest/reference/cognito-identity/update-identity-pool.html).
 1. [Identity pool (federated identities) authentication flow](https://docs.aws.amazon.com/cognito/latest/developerguide/authentication-flow.html).
-
 ---
 ## Content security policy blocks the web client
 
@@ -184,7 +189,7 @@ web client will contain the following directives and values:
 A hash of the snippet can be generated from the command line using openssl:
 
 ```bash
-SNIPPET='(function(n,i,v,r,s,c,u,x,z){x=window.AwsRumClient={q:[],n:n,i:i,v:v,r:r,c:c,u:u};window[n]=function(c,p){x.q.push({c:c,p:p});};z=document.createElement('script');z.async=true;z.src=s;document.head.insertBefore(z,document.getElementsByTagName('script')[0]);})('cwr','00000000-0000-0000-0000-000000000000','1.0.0','us-west-2','https://client.rum.us-east-1.amazonaws.com/1.0.2/cwr.js',{sessionSampleRate:1,guestRoleArn:'arn:aws:iam::000000000000:role/RUM-Monitor-us-west-2-000000000000-00xx-Unauth',identityPoolId:'us-west-2:00000000-0000-0000-0000-000000000000',endpoint:'https://dataplane.rum.us-west-2.amazonaws.com',telemetries:['errors','http','performance'],allowCookies:true});'
+SNIPPET='(function(n,i,v,r,s,c,u,x,z){x=window.AwsRumClient={q:[],n:n,i:i,v:v,r:r,c:c,u:u};window[n]=function(c,p){x.q.push({c:c,p:p});};z=document.createElement('script');z.async=true;z.src=s;document.head.insertBefore(z,document.getElementsByTagName('script')[0]);})('cwr','00000000-0000-0000-0000-000000000000','1.0.0','us-west-2','https://client.rum.us-east-1.amazonaws.com/1.0.2/cwr.js',{sessionSampleRate:1,identityPoolId:'us-west-2:00000000-0000-0000-0000-000000000000',endpoint:'https://dataplane.rum.us-west-2.amazonaws.com',telemetries:['errors','http','performance'],allowCookies:true});'
 echo $SNIPPET | openssl sha256 -binary | openssl base64
 ```
 

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -9,7 +9,6 @@ For example, the config object may look similar to the following:
 {
     allowCookies: true,
     endpoint: "https://dataplane.rum.us-west-2.amazonaws.com",
-    guestRoleArn: "arn:aws:iam::000000000000:role/RUM-Monitor-us-west-2-000000000000-00xx-Unauth",
     identityPoolId: "us-west-2:00000000-0000-0000-0000-000000000000",
     sessionSampleRate: 1,
     telemetries: ['errors', 'performance', 'http']
@@ -28,8 +27,8 @@ For example, the config object may look similar to the following:
 | enableXRay | Boolean | `false` | When this field is `true` **and** the `http` telemetry is used, the web client will record X-Ray traces for HTTP requests.<br/><br/>See the [HTTP telemetry configuration](#http) for more information, including how to connect client-side and server-side traces. |
 | endpoint | String | `'https://dataplane.rum.[region].amazonaws.com'`<br/><br/>`'https://[restapi_id].execute-api.[region].amazonaws.com/[stage_name]/'` | The URL of the CloudWatch RUM API where data will be sent.<br/><br/>You may include a path prefix like `/stage_name/` in the endpoint URL if there is a proxy between your web application and CloudWatch RUM. |
 | eventPluginsToLoad | [Plugin](examples.md#record-custom-events-using-a-plugin)[] | `[]` | The set of custom plugins to load. See [usage examples](examples.md#record-custom-events-using-a-plugin). |
-| guestRoleArn | String | `undefined` | The ARN of the AWS IAM role that will be assumed during anonymous authorization.<br/><br/>When this field is set (along with `identityPoolId`), the web client will attempt to retrieve temporary AWS credentials through Cognito using `AssumeRoleWithWebIdentity`. If this field is not set, you must forward credentials to the web client using the `setAwsCredentials` command. |
-| identityPoolId | String | `undefined` | The Amazon Cognito Identity Pool ID that will be used during anonymous authorization.<br/><br/>When this field is set (along with `guestRoleArn`), the web client will attempt to retrieve temporary AWS credentials through Cognito using `AssumeRoleWithWebIdentity`. If this field is not set, you must forward credentials to the web client using the `setAwsCredentials` command. |
+| guestRoleArn | String | `undefined` | The ARN of the AWS IAM role that will be assumed during anonymous authorization.<br/><br/>When `guestRoleArn` and `identityPoolId` are both set, the web client will use Cognito's [basic (classic) authflow](https://docs.aws.amazon.com/cognito/latest/developerguide/authentication-flow.html).<br/><br/>When only `identityPoolId` is set, the web client will use Cognito's [enhanced (simplified) authflow](https://docs.aws.amazon.com/cognito/latest/developerguide/authentication-flow.html) (recommended). |
+| identityPoolId | String | `undefined` | The Amazon Cognito Identity Pool ID that will be used during anonymous authorization.<br/><br/>When `identityPoolId` is set, the web client will use Cognito to retrieve temporary AWS credentials. These credentials authorize the bearer to send data to the CloudWatch RUM app monitor.<br/><br/>When`identityPoolId` is not set, you must either (A) forward credentials to the web client using the `setAwsCredentials` command, or (B) use a proxy and set `signing` to `false`. |
 | pageIdFormat | String | `'PATH'` | The portion of the `window.location` that will be used as the page ID. Options include `PATH`, `HASH` and `PATH_AND_HASH`.<br/><br/>For example, consider the URL `https://amazonaws.com/home?param=true#content`<br/><br/>`PATH`: `/home`<br/>`HASH`: `#content`<br/>`PATH_AND_HASH`: `/home#content` |
 | pagesToInclude | RegExp[] | `[/.*/]` | A list of regular expressions which specify the `window.location` values for which the web client will record data, unless explicitly excluded by `pagesToExclude`. Pages are matched using the `RegExp.test()` function.<br/><br/>For example, when `pagesToInclude: [ /\/home/ ]`, then data from `https://amazonaws.com/home` will be included,  and `https://amazonaws.com/` will not be included. |
 | pagesToExclude | RegExp[] | `[]` | A list of regular expressions which specify the `window.location` values for which the web client will not record data. Pages are matched using the `RegExp.test()` function.<br/><br/>For example, when `pagesToExclude: [ /\/home/ ]`, then data from `https://amazonaws.com/home` will be excluded,  and `https://amazonaws.com/` will not be excluded. |
@@ -163,7 +162,6 @@ const getInteractionId = (event: Event): string => {
 }
 
 const config: AwsRumConfig = {
-    guestRoleArn: "arn:aws:iam::000000000000:role/RUM-Monitor-us-west-2-000000000000-00xx-Unauth",
     identityPoolId: "us-west-2:00000000-0000-0000-0000-000000000000",
     sessionSampleRate: 1,
     telemetries: [

diff --git a/docs/examples.md b/docs/examples.md
@@ -86,7 +86,6 @@ try {
   const myScrollEventPlugin: MyScrollEventPlugin = new MyScrollEventPlugin();
 
   const config: AwsRumConfig = {
-    guestRoleArn: "arn:aws:iam::000000000000:role/RUM-Monitor-us-west-2-000000000000-00xx-Unauth",
     identityPoolId: "us-west-2:00000000-0000-0000-0000-000000000000",
     sessionSampleRate: 1,
     telemetries: ['errors', 'performance'],