docs(cognito_identity_credentials): Explain limitation of CognitoIden… (

#4455)

* docs(cognito_identity_credentials): Explain limitation of CognitoIdentityCredentials

This method uses the simplified authflow, which means users cannot explicitly set a session policy. This results in STS appending the Default Session Policy to the request, which can lead to limiting permissions even if they are explicitly attached to a role.

* Update cognito_identity_credentials.js

* Update lib/credentials/cognito_identity_credentials.js

* Update lib/credentials/cognito_identity_credentials.js

---------

Co-authored-by: George Fu <kuhe@users.noreply.github.com>

lib/credentials/cognito_identity_credentials.js

@@ -23,6 +23,15 @@ var STS = require('../../clients/sts');
  * identity providers. See {constructor} for an example on creating a credentials
  * object with proper property values.
  *
+ * DISCLAIMER: This convenience method leverages the Enhanced (simplified) Authflow. The underlying
+ * implementation calls Cognito's `getId()` and `GetCredentialsForIdentity()`.
+ * In this flow there is no way to explicitly set a session policy, resulting in
+ * STS attaching the default policy and limiting the permissions of the federated role.
+ * To be able to explicitly set a session policy, do not use this convenience method.
+ * Instead, you can use the Cognito client to call `getId()`, `GetOpenIdToken()` and then use
+ * that token with your desired session policy to call STS's `AssumeRoleWithWebIdentity()`
+ * For further reading refer to: https://docs.aws.amazon.com/cognito/latest/developerguide/authentication-flow.html
+ *
  * ## Refreshing Credentials from Identity Service
  *
  * In addition to AWS credentials expiring after a given amount of time, the