feat(client-sts): Documentation updates for AWS Security Token Service.

clients/client-sts/README.md

@@ -9,8 +9,7 @@ AWS SDK for JavaScript STS Client for Node.js, Browser and React Native.
 <fullname>Security Token Service</fullname>
 
 <p>Security Token Service (STS) enables you to request temporary, limited-privilege
-credentials for Identity and Access Management (IAM) users or for users that you
-authenticate (federated users). This guide provides descriptions of the STS API. For
+credentials for users. This guide provides descriptions of the STS API. For
 more information about using this service, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html">Temporary Security Credentials</a>.</p>
 
 ## Installing

clients/client-sts/src/STS.ts

@@ -184,8 +184,7 @@ export interface STS {
  * @public
  * <fullname>Security Token Service</fullname>
  *          <p>Security Token Service (STS) enables you to request temporary, limited-privilege
- *       credentials for Identity and Access Management (IAM) users or for users that you
- *       authenticate (federated users). This guide provides descriptions of the STS API. For
+ *       credentials for users. This guide provides descriptions of the STS API. For
  *       more information about using this service, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html">Temporary Security Credentials</a>.</p>
  */
 export class STS extends STSClient implements STS {}

clients/client-sts/src/STSClient.ts

@@ -258,8 +258,7 @@ export interface STSClientResolvedConfig extends STSClientResolvedConfigType {}
  * @public
  * <fullname>Security Token Service</fullname>
  *          <p>Security Token Service (STS) enables you to request temporary, limited-privilege
- *       credentials for Identity and Access Management (IAM) users or for users that you
- *       authenticate (federated users). This guide provides descriptions of the STS API. For
+ *       credentials for users. This guide provides descriptions of the STS API. For
  *       more information about using this service, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html">Temporary Security Credentials</a>.</p>
  */
 export class STSClient extends __Client<

clients/client-sts/src/commands/AssumeRoleCommand.ts

@@ -59,16 +59,16 @@ export interface AssumeRoleCommandOutput extends AssumeRoleResponse, __MetadataB
  *          by the identity-based policy of the role that is being assumed. For more information, see
  *             <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session">Session
  *             Policies</a> in the <i>IAM User Guide</i>.</p>
- *          <p>When you create a role, you create two policies: A role trust policy that specifies
- *             <i>who</i> can assume the role and a permissions policy that specifies
+ *          <p>When you create a role, you create two policies: a role trust policy that specifies
+ *             <i>who</i> can assume the role, and a permissions policy that specifies
  *             <i>what</i> can be done with the role. You specify the trusted principal
- *          who is allowed to assume the role in the role trust policy.</p>
+ *          that is allowed to assume the role in the role trust policy.</p>
  *          <p>To assume a role from a different account, your Amazon Web Services account must be trusted by the
  *          role. The trust relationship is defined in the role's trust policy when the role is
  *          created. That trust policy states which accounts are allowed to delegate that access to
  *          users in the account. </p>
  *          <p>A user who wants to access a role in a different account must also have permissions that
- *          are delegated from the user account administrator. The administrator must attach a policy
+ *          are delegated from the account administrator. The administrator must attach a policy
  *          that allows the user to call <code>AssumeRole</code> for the ARN of the role in the other
  *          account.</p>
  *          <p>To allow a user to assume a role in the same account, you can do either of the

clients/client-sts/src/commands/AssumeRoleWithWebIdentityCommand.ts

@@ -41,9 +41,8 @@ export interface AssumeRoleWithWebIdentityCommandOutput extends AssumeRoleWithWe
  *                <a href="http://aws.amazon.com/sdkforios/">Amazon Web Services SDK for iOS Developer Guide</a> and the <a href="http://aws.amazon.com/sdkforandroid/">Amazon Web Services SDK for Android Developer Guide</a> to uniquely
  *             identify a user. You can also supply the user with a consistent identity throughout the
  *             lifetime of an application.</p>
- *             <p>To learn more about Amazon Cognito, see <a href="https://docs.aws.amazon.com/mobile/sdkforandroid/developerguide/cognito-auth.html#d0e840">Amazon Cognito Overview</a> in
- *                <i>Amazon Web Services SDK for Android Developer Guide</i> and <a href="https://docs.aws.amazon.com/mobile/sdkforios/developerguide/cognito-auth.html#d0e664">Amazon Cognito Overview</a> in the
- *                <i>Amazon Web Services SDK for iOS Developer Guide</i>.</p>
+ *             <p>To learn more about Amazon Cognito, see <a href="https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html">Amazon Cognito identity pools</a> in
+ *             <i>Amazon Cognito Developer Guide</i>.</p>
  *          </note>
  *          <p>Calling <code>AssumeRoleWithWebIdentity</code> does not require the use of Amazon Web Services
  *          security credentials. Therefore, you can distribute an application (for example, on mobile

clients/client-sts/src/commands/GetCallerIdentityCommand.ts

@@ -33,14 +33,12 @@ export interface GetCallerIdentityCommandOutput extends GetCallerIdentityRespons
 
 /**
  * @public
- * <p>Returns details about the IAM user or role whose credentials are used to call the
- *          operation.</p>
+ * <p>Returns details about the IAM user or role whose credentials are used to call the operation.</p>
  *          <note>
- *             <p>No permissions are required to perform this operation. If an administrator adds a
- *             policy to your IAM user or role that explicitly denies access to the
+ *             <p>No permissions are required to perform this operation. If an administrator
+ *            attaches a policy to your identity that explicitly denies access to the
  *                <code>sts:GetCallerIdentity</code> action, you can still perform this operation.
- *             Permissions are not required because the same information is returned when an IAM user
- *             or role is denied access. To view an example response, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_general.html#troubleshoot_general_access-denied-delete-mfa">I Am Not Authorized to Perform: iam:DeleteVirtualMFADevice</a> in the
+ *             Permissions are not required because the same information is returned when access is denied. To view an example response, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_general.html#troubleshoot_general_access-denied-delete-mfa">I Am Not Authorized to Perform: iam:DeleteVirtualMFADevice</a> in the
  *                <i>IAM User Guide</i>.</p>
  *          </note>
  * @example

clients/client-sts/src/commands/GetFederationTokenCommand.ts

@@ -34,35 +34,32 @@ export interface GetFederationTokenCommandOutput extends GetFederationTokenRespo
 /**
  * @public
  * <p>Returns a set of temporary security credentials (consisting of an access key ID, a
- *          secret access key, and a security token) for a federated user. A typical use is in a proxy
+ *          secret access key, and a security token) for a user. A typical use is in a proxy
  *          application that gets temporary security credentials on behalf of distributed applications
- *          inside a corporate network. You must call the <code>GetFederationToken</code> operation
+ *          inside a corporate network.</p>
+ *          <p>You must call the <code>GetFederationToken</code> operation
  *          using the long-term security credentials of an IAM user. As a result, this call is
- *          appropriate in contexts where those credentials can be safely stored, usually in a
+ *          appropriate in contexts where those credentials can be safeguarded, usually in a
  *          server-based application. For a comparison of <code>GetFederationToken</code> with the
  *          other API operations that produce temporary credentials, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html">Requesting Temporary Security
  *             Credentials</a> and <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#stsapi_comparison">Comparing the
  *             Amazon Web Services STS API operations</a> in the <i>IAM User Guide</i>.</p>
+ *          <p>Although it is possible to call <code>GetFederationToken</code> using the security credentials of an
+ *          Amazon Web Services account root user rather than an IAM user that you create for the purpose of a proxy application, we do not recommend it. For more information, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials">Safeguard your root user credentials and don't use them for everyday tasks</a> in the
+ *          <i>IAM User Guide</i>. </p>
  *          <note>
  *             <p>You can create a mobile-based or browser-based app that can authenticate users using
  *             a web identity provider like Login with Amazon, Facebook, Google, or an OpenID
  *             Connect-compatible identity provider. In this case, we recommend that you use <a href="http://aws.amazon.com/cognito/">Amazon Cognito</a> or
  *                <code>AssumeRoleWithWebIdentity</code>. For more information, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#api_assumerolewithwebidentity">Federation Through a Web-based Identity Provider</a> in the
  *                <i>IAM User Guide</i>.</p>
  *          </note>
- *          <p>You can also call <code>GetFederationToken</code> using the security credentials of an
- *          Amazon Web Services account root user, but we do not recommend it. Instead, we recommend that you create
- *          an IAM user for the purpose of the proxy application. Then attach a policy to the IAM
- *          user that limits federated users to only the actions and resources that they need to
- *          access. For more information, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html">IAM Best Practices</a> in the
- *             <i>IAM User Guide</i>. </p>
  *          <p>
  *             <b>Session duration</b>
  *          </p>
  *          <p>The temporary credentials are valid for the specified duration, from 900 seconds (15
  *          minutes) up to a maximum of 129,600 seconds (36 hours). The default session duration is
- *          43,200 seconds (12 hours). Temporary credentials obtained by using the Amazon Web Services account root
- *          user credentials have a maximum duration of 3,600 seconds (1 hour).</p>
+ *          43,200 seconds (12 hours). Temporary credentials obtained by using the root user credentials have a maximum duration of 3,600 seconds (1 hour).</p>
  *          <p>
  *             <b>Permissions</b>
  *          </p>

clients/client-sts/src/commands/GetSessionTokenCommand.ts

@@ -36,12 +36,11 @@ export interface GetSessionTokenCommandOutput extends GetSessionTokenResponse, _
  * <p>Returns a set of temporary credentials for an Amazon Web Services account or IAM user. The
  *          credentials consist of an access key ID, a secret access key, and a security token.
  *          Typically, you use <code>GetSessionToken</code> if you want to use MFA to protect
- *          programmatic calls to specific Amazon Web Services API operations like Amazon EC2 <code>StopInstances</code>.
- *          MFA-enabled IAM users would need to call <code>GetSessionToken</code> and submit an MFA
+ *          programmatic calls to specific Amazon Web Services API operations like Amazon EC2 <code>StopInstances</code>.</p>
+ *          <p>MFA-enabled IAM users must call <code>GetSessionToken</code> and submit an MFA
  *          code that is associated with their MFA device. Using the temporary security credentials
- *          that are returned from the call, IAM users can then make programmatic calls to API
- *          operations that require MFA authentication. If you do not supply a correct MFA code, then
- *          the API returns an access denied error. For a comparison of <code>GetSessionToken</code>
+ *          that the call returns, IAM users can then make programmatic calls to API
+ *          operations that require MFA authentication. An incorrect MFA code causes the API to return an access denied error. For a comparison of <code>GetSessionToken</code>
  *          with the other API operations that produce temporary credentials, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html">Requesting
  *             Temporary Security Credentials</a> and <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#stsapi_comparison">Comparing the
  *             Amazon Web Services STS API operations</a> in the <i>IAM User Guide</i>.</p>
@@ -56,7 +55,7 @@ export interface GetSessionTokenCommandOutput extends GetSessionTokenResponse, _
  *             <b>Session Duration</b>
  *          </p>
  *          <p>The <code>GetSessionToken</code> operation must be called by using the long-term Amazon Web Services
- *          security credentials of the Amazon Web Services account root user or an IAM user. Credentials that are
+ *          security credentials of an IAM user. Credentials that are
  *          created by IAM users are valid for the duration that you specify. This duration can range
  *          from 900 seconds (15 minutes) up to a maximum of 129,600 seconds (36 hours), with a default
  *          of 43,200 seconds (12 hours). Credentials based on account credentials can range from 900
@@ -76,20 +75,19 @@ export interface GetSessionTokenCommandOutput extends GetSessionTokenResponse, _
  *                   <code>AssumeRole</code> or <code>GetCallerIdentity</code>.</p>
  *             </li>
  *          </ul>
+ *          <p>The credentials that <code>GetSessionToken</code> returns are based on
+ *          permissions associated with the IAM user whose credentials were used to call the operation. The
+ *          temporary credentials have the same permissions as the IAM user.</p>
  *          <note>
- *             <p>We recommend that you do not call <code>GetSessionToken</code> with Amazon Web Services account
- *             root user credentials. Instead, follow our <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#create-iam-users">best practices</a> by
- *             creating one or more IAM users, giving them the necessary permissions, and using IAM
- *             users for everyday interaction with Amazon Web Services. </p>
+ *             <p>Although it is possible to call <code>GetSessionToken</code> using the security credentials of an
+ *             Amazon Web Services account root user rather than an IAM user, we do not recommend it. If
+ *             <code>GetSessionToken</code> is called using root user credentials, the
+ *             temporary credentials have root user permissions. For more information, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials">Safeguard your root user credentials and don't use them for everyday tasks</a> in the
+ *             <i>IAM User Guide</i>
+ *             </p>
  *          </note>
- *          <p>The credentials that are returned by <code>GetSessionToken</code> are based on
- *          permissions associated with the user whose credentials were used to call the operation. If
- *             <code>GetSessionToken</code> is called using Amazon Web Services account root user credentials, the
- *          temporary credentials have root user permissions. Similarly, if
- *             <code>GetSessionToken</code> is called using the credentials of an IAM user, the
- *          temporary credentials have the same permissions as the IAM user. </p>
  *          <p>For more information about using <code>GetSessionToken</code> to create temporary
- *          credentials, go to <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#api_getsessiontoken">Temporary
+ *          credentials, see <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#api_getsessiontoken">Temporary
  *             Credentials for Users in Untrusted Environments</a> in the
  *             <i>IAM User Guide</i>. </p>
  * @example