diff --git a/CHANGELOG.md b/CHANGELOG.md index af91d0f..5d22bd3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ - use strict comparison `null !==` instead of `!` - Fix CS +- AWS enhancement: Documentation updates. ## 1.22.1 diff --git a/src/Sts/Exception/RegionDisabledException.php b/src/Sts/Exception/RegionDisabledException.php index e64f7e9..116b002 100644 --- a/src/Sts/Exception/RegionDisabledException.php +++ b/src/Sts/Exception/RegionDisabledException.php @@ -7,7 +7,7 @@ /** * STS is not activated in the requested region for the account that is being asked to generate credentials. The account * administrator must use the IAM console to activate STS in that region. For more information, see Activating and - * Deactivating Amazon Web Services STS in an Amazon Web Services Region [^1] in the *IAM User Guide*. + * Deactivating STS in an Amazon Web Services Region [^1] in the *IAM User Guide*. * * [^1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html */ diff --git a/src/Sts/Input/AssumeRoleRequest.php b/src/Sts/Input/AssumeRoleRequest.php index 9576972..e8f50e1 100644 --- a/src/Sts/Input/AssumeRoleRequest.php +++ b/src/Sts/Input/AssumeRoleRequest.php @@ -30,9 +30,16 @@ final class AssumeRoleRequest extends Input * subsequent cross-account API requests that use the temporary security credentials will expose the role session name * to the external account in their CloudTrail logs. * + * For security purposes, administrators can view this field in CloudTrail logs [^1] to help identify who performed an + * action in Amazon Web Services. Your administrator might require that you specify your user name as the session name + * when you assume the role. For more information, see `sts:RoleSessionName` [^2]. + * * The regex used to validate this parameter is a string of characters consisting of upper- and lower-case alphanumeric * characters with no spaces. You can also include underscores or any of the following characters: =,.@- * + * [^1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/cloudtrail-integration.html#cloudtrail-integration_signin-tempcreds + * [^2]: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_rolesessionname + * * @required * * @var string|null @@ -83,7 +90,10 @@ final class AssumeRoleRequest extends Input * > plaintext meets the other requirements. The `PackedPolicySize` response element indicates by percentage how close * > the policies and tags for your request are to the upper size limit. * + * For more information about role session permissions, see Session policies [^2]. + * * [^1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session + * [^2]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session * * @var string|null */ @@ -101,7 +111,7 @@ final class AssumeRoleRequest extends Input * the `DurationSeconds` parameter. You can specify a parameter value of up to 43200 seconds (12 hours), depending on * the maximum session duration setting for your role. However, if you assume a role using role chaining and provide a * `DurationSeconds` parameter value greater than one hour, the operation fails. To learn how to view the maximum value - * for your role, see View the Maximum Session Duration Setting for a Role [^1] in the *IAM User Guide*. + * for your role, see Update the maximum session duration for a role [^1]. * * By default, the value is set to `3600` seconds. * @@ -110,7 +120,7 @@ final class AssumeRoleRequest extends Input * > parameter that specifies the maximum length of the console session. For more information, see Creating a URL that * > Enables Federated Users to Access the Amazon Web Services Management Console [^2] in the *IAM User Guide*. * - * [^1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html#id_roles_use_view-role-max-session + * [^1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_update-role-settings.html#id_roles_update-session-duration * [^2]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_enable-console-custom-url.html * * @var int|null @@ -156,8 +166,7 @@ final class AssumeRoleRequest extends Input * corresponding key and value passes to subsequent sessions in a role chain. For more information, see Chaining Roles * with Session Tags [^1] in the *IAM User Guide*. * - * This parameter is optional. When you set session tags as transitive, the session policy and session tags packed - * binary limit is not affected. + * This parameter is optional. The transitive status of a session tag does not impact its packed binary size. * * If you choose not to specify a transitive tag key, then no tags are passed from this session to any subsequent * sessions. @@ -211,19 +220,22 @@ final class AssumeRoleRequest extends Input private $tokenCode; /** - * The source identity specified by the principal that is calling the `AssumeRole` operation. + * The source identity specified by the principal that is calling the `AssumeRole` operation. The source identity value + * persists across chained role [^1] sessions. * * You can require users to specify a source identity when they assume a role. You do this by using the - * `sts:SourceIdentity` condition key in a role trust policy. You can use source identity information in CloudTrail logs - * to determine who took actions with a role. You can use the `aws:SourceIdentity` condition key to further control + * `sts:SourceIdentity` [^2] condition key in a role trust policy. You can use source identity information in CloudTrail + * logs to determine who took actions with a role. You can use the `aws:SourceIdentity` condition key to further control * access to Amazon Web Services resources based on the value of source identity. For more information about using - * source identity, see Monitor and control actions taken with assumed roles [^1] in the *IAM User Guide*. + * source identity, see Monitor and control actions taken with assumed roles [^3] in the *IAM User Guide*. * * The regex used to validate this parameter is a string of characters consisting of upper- and lower-case alphanumeric * characters with no spaces. You can also include underscores or any of the following characters: =,.@-. You cannot use * a value that begins with the text `aws:`. This prefix is reserved for Amazon Web Services internal use. * - * [^1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_monitor.html + * [^1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html#iam-term-role-chaining + * [^2]: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceidentity + * [^3]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_monitor.html * * @var string|null */ diff --git a/src/Sts/Input/AssumeRoleWithWebIdentityRequest.php b/src/Sts/Input/AssumeRoleWithWebIdentityRequest.php index 5047aea..f694685 100644 --- a/src/Sts/Input/AssumeRoleWithWebIdentityRequest.php +++ b/src/Sts/Input/AssumeRoleWithWebIdentityRequest.php @@ -13,6 +13,16 @@ final class AssumeRoleWithWebIdentityRequest extends Input /** * The Amazon Resource Name (ARN) of the role that the caller is assuming. * + * > Additional considerations apply to Amazon Cognito identity pools that assume cross-account IAM roles [^1]. The + * > trust policies of these roles must accept the `cognito-identity.amazonaws.com` service principal and must contain + * > the `cognito-identity.amazonaws.com:aud` condition key to restrict role assumption to users from your intended + * > identity pools. A policy that trusts Amazon Cognito identity pools without this condition creates a risk that a + * > user from an unintended identity pool can assume the role. For more information, see Trust policies for IAM roles + * > in Basic (Classic) authentication [^2] in the *Amazon Cognito Developer Guide*. + * + * [^1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html + * [^2]: https://docs.aws.amazon.com/cognito/latest/developerguide/iam-roles.html#trust-policies + * * @required * * @var string|null @@ -25,9 +35,16 @@ final class AssumeRoleWithWebIdentityRequest extends Input * associated with that user. This session name is included as part of the ARN and assumed role ID in the * `AssumedRoleUser` response element. * + * For security purposes, administrators can view this field in CloudTrail logs [^1] to help identify who performed an + * action in Amazon Web Services. Your administrator might require that you specify your user name as the session name + * when you assume the role. For more information, see `sts:RoleSessionName` [^2]. + * * The regex used to validate this parameter is a string of characters consisting of upper- and lower-case alphanumeric * characters with no spaces. You can also include underscores or any of the following characters: =,.@- * + * [^1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/cloudtrail-integration.html#cloudtrail-integration_signin-tempcreds + * [^2]: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_rolesessionname + * * @required * * @var string|null @@ -37,7 +54,8 @@ final class AssumeRoleWithWebIdentityRequest extends Input /** * The OAuth 2.0 access token or OpenID Connect ID token that is provided by the identity provider. Your application * must get this token by authenticating the user who is using your application with a web identity provider before the - * application makes an `AssumeRoleWithWebIdentity` call. Only tokens with RSA algorithms (RS256) are supported. + * application makes an `AssumeRoleWithWebIdentity` call. Timestamps in the token must be formatted as either an integer + * or a long integer. Only tokens with RSA algorithms (RS256) are supported. * * @required * @@ -97,12 +115,15 @@ final class AssumeRoleWithWebIdentityRequest extends Input * policy characters can be any ASCII character from the space character to the end of the valid character list (\u0020 * through \u00FF). It can also include the tab (\u0009), linefeed (\u000A), and carriage return (\u000D) characters. * + * For more information about role session permissions, see Session policies [^2]. + * * > An Amazon Web Services conversion compresses the passed inline session policy, managed policy ARNs, and session * > tags into a packed binary format that has a separate limit. Your request can fail for this limit even if your * > plaintext meets the other requirements. The `PackedPolicySize` response element indicates by percentage how close * > the policies and tags for your request are to the upper size limit. * * [^1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session + * [^2]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session * * @var string|null */ diff --git a/src/Sts/Result/AssumeRoleWithWebIdentityResponse.php b/src/Sts/Result/AssumeRoleWithWebIdentityResponse.php index 5e6c1f8..5c82fd9 100644 --- a/src/Sts/Result/AssumeRoleWithWebIdentityResponse.php +++ b/src/Sts/Result/AssumeRoleWithWebIdentityResponse.php @@ -85,7 +85,7 @@ class AssumeRoleWithWebIdentityResponse extends Result * The regex used to validate this parameter is a string of characters consisting of upper- and lower-case alphanumeric * characters with no spaces. You can also include underscores or any of the following characters: =,.@- * - * [^1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts#iam-term-role-chaining + * [^1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html#id_roles_terms-and-concepts * [^2]: https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html * [^3]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_monitor.html * diff --git a/src/Sts/StsClient.php b/src/Sts/StsClient.php index 717a4e7..e6f0a2a 100644 --- a/src/Sts/StsClient.php +++ b/src/Sts/StsClient.php @@ -29,8 +29,8 @@ class StsClient extends AbstractApi * Returns a set of temporary security credentials that you can use to access Amazon Web Services resources. These * temporary credentials consist of an access key ID, a secret access key, and a security token. Typically, you use * `AssumeRole` within your account or for cross-account access. For a comparison of `AssumeRole` with other API - * operations that produce temporary credentials, see Requesting Temporary Security Credentials [^1] and Comparing the - * Amazon Web Services STS API operations [^2] in the *IAM User Guide*. + * operations that produce temporary credentials, see Requesting Temporary Security Credentials [^1] and Compare STS + * credentials [^2] in the *IAM User Guide*. * * **Permissions** * @@ -38,14 +38,14 @@ class StsClient extends AbstractApi * service with the following exception: You cannot call the Amazon Web Services STS `GetFederationToken` or * `GetSessionToken` API operations. * - * (Optional) You can pass inline or managed session policies [^3] to this operation. You can pass a single JSON policy + * (Optional) You can pass inline or managed session policies to this operation. You can pass a single JSON policy * document to use as an inline session policy. You can also specify up to 10 managed policy Amazon Resource Names * (ARNs) to use as managed session policies. The plaintext that you use for both inline and managed session policies * can't exceed 2,048 characters. Passing policies to this operation returns new temporary credentials. The resulting * session's permissions are the intersection of the role's identity-based policy and the session policies. You can use * the role's temporary credentials in subsequent Amazon Web Services API calls to access resources in the account that * owns the role. You cannot use session policies to grant more permissions than those allowed by the identity-based - * policy of the role that is being assumed. For more information, see Session Policies [^4] in the *IAM User Guide*. + * policy of the role that is being assumed. For more information, see Session Policies [^3] in the *IAM User Guide*. * * When you create a role, you create two policies: a role trust policy that specifies *who* can assume the role, and a * permissions policy that specifies *what* can be done with the role. You specify the trusted principal that is allowed @@ -67,19 +67,19 @@ class StsClient extends AbstractApi * * You can do either because the role’s trust policy acts as an IAM resource-based policy. When a resource-based * policy grants access to a principal in the same account, no additional identity-based policy is required. For more - * information about trust policies and resource-based policies, see IAM Policies [^5] in the *IAM User Guide*. + * information about trust policies and resource-based policies, see IAM Policies [^4] in the *IAM User Guide*. * * **Tags** * * (Optional) You can pass tag key-value pairs to your session. These tags are called session tags. For more information - * about session tags, see Passing Session Tags in STS [^6] in the *IAM User Guide*. + * about session tags, see Passing Session Tags in STS [^5] in the *IAM User Guide*. * * An administrator must grant you the permissions necessary to pass session tags. The administrator can also create * granular permissions to allow you to pass only specific session tags. For more information, see Tutorial: Using Tags - * for Attribute-Based Access Control [^7] in the *IAM User Guide*. + * for Attribute-Based Access Control [^6] in the *IAM User Guide*. * * You can set the session tags as transitive. Transitive tags persist during role chaining. For more information, see - * Chaining Roles with Session Tags [^8] in the *IAM User Guide*. + * Chaining Roles with Session Tags [^7] in the *IAM User Guide*. * * **Using MFA with AssumeRole** * @@ -91,21 +91,20 @@ class StsClient extends AbstractApi * * `"Condition": {"Bool": {"aws:MultiFactorAuthPresent": true}}` * - * For more information, see Configuring MFA-Protected API Access [^9] in the *IAM User Guide* guide. + * For more information, see Configuring MFA-Protected API Access [^8] in the *IAM User Guide* guide. * * To use MFA with `AssumeRole`, you pass values for the `SerialNumber` and `TokenCode` parameters. The `SerialNumber` * value identifies the user's hardware or virtual MFA device. The `TokenCode` is the time-based one-time password * (TOTP) that the MFA device produces. * * [^1]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html - * [^2]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#stsapi_comparison + * [^2]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_sts-comparison.html * [^3]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session - * [^4]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session - * [^5]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html - * [^6]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html - * [^7]: https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_attribute-based-access-control.html - * [^8]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html#id_session-tags_role-chaining - * [^9]: https://docs.aws.amazon.com/IAM/latest/UserGuide/MFAProtectedAPI.html + * [^4]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html + * [^5]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html + * [^6]: https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_attribute-based-access-control.html + * [^7]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html#id_session-tags_role-chaining + * [^8]: https://docs.aws.amazon.com/IAM/latest/UserGuide/MFAProtectedAPI.html * * @see https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html * @see https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sts-2011-06-15.html#assumerole @@ -162,7 +161,7 @@ public function assumeRole($input): AssumeRoleResponse * server-based proxy services that use long-term Amazon Web Services credentials. Instead, the identity of the caller * is validated by using a token from the web identity provider. For a comparison of `AssumeRoleWithWebIdentity` with * the other API operations that produce temporary credentials, see Requesting Temporary Security Credentials [^5] and - * Comparing the Amazon Web Services STS API operations [^6] in the *IAM User Guide*. + * Compare STS credentials [^6] in the *IAM User Guide*. * * The temporary security credentials returned by this API consist of an access key ID, a secret access key, and a * security token. Applications can use these temporary security credentials to sign calls to Amazon Web Services @@ -173,8 +172,8 @@ public function assumeRole($input): AssumeRoleResponse * By default, the temporary security credentials created by `AssumeRoleWithWebIdentity` last for one hour. However, you * can use the optional `DurationSeconds` parameter to specify the duration of your session. You can provide a value * from 900 seconds (15 minutes) up to the maximum session duration setting for the role. This setting can have a value - * from 1 hour to 12 hours. To learn how to view the maximum value for your role, see View the Maximum Session Duration - * Setting for a Role [^7] in the *IAM User Guide*. The maximum session duration limit applies when you use the + * from 1 hour to 12 hours. To learn how to view the maximum value for your role, see Update the maximum session + * duration for a role [^7] in the *IAM User Guide*. The maximum session duration limit applies when you use the * `AssumeRole*` API operations or the `assume-role*` CLI commands. However the limit does not apply when you use those * operations to create a console URL. For more information, see Using IAM Roles [^8] in the *IAM User Guide*. * @@ -230,27 +229,22 @@ public function assumeRole($input): AssumeRoleResponse * ! (PII) in this field. For example, you could instead use a GUID or a pairwise identifier, as suggested in the OIDC * ! specification [^16]. * - * For more information about how to use web identity federation and the `AssumeRoleWithWebIdentity` API, see the - * following resources: + * For more information about how to use OIDC federation and the `AssumeRoleWithWebIdentity` API, see the following + * resources: * * - Using Web Identity Federation API Operations for Mobile Apps [^17] and Federation Through a Web-based Identity * Provider [^18]. - * - Web Identity Federation Playground [^19]. Walk through the process of authenticating through Login with Amazon, - * Facebook, or Google, getting temporary security credentials, and then using those credentials to make a request to - * Amazon Web Services. - * - Amazon Web Services SDK for iOS Developer Guide [^20] and Amazon Web Services SDK for Android Developer Guide - * [^21]. These toolkits contain sample apps that show how to invoke the identity providers. The toolkits then show + * - Amazon Web Services SDK for iOS Developer Guide [^19] and Amazon Web Services SDK for Android Developer Guide + * [^20]. These toolkits contain sample apps that show how to invoke the identity providers. The toolkits then show * how to use the information from these providers to get and use temporary security credentials. - * - Web Identity Federation with Mobile Applications [^22]. This article discusses web identity federation and shows an - * example of how to use web identity federation to get access to content in Amazon S3. * * [^1]: https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html * [^2]: http://aws.amazon.com/sdkforios/ * [^3]: http://aws.amazon.com/sdkforandroid/ * [^4]: https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html * [^5]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html - * [^6]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#stsapi_comparison - * [^7]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html#id_roles_use_view-role-max-session + * [^6]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_sts-comparison.html + * [^7]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_update-role-settings.html#id_roles_update-session-duration * [^8]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html * [^9]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session * [^10]: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session @@ -262,10 +256,8 @@ public function assumeRole($input): AssumeRoleResponse * [^16]: http://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes * [^17]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc_manual.html * [^18]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#api_assumerolewithwebidentity - * [^19]: https://aws.amazon.com/blogs/aws/the-aws-web-identity-federation-playground/ - * [^20]: http://aws.amazon.com/sdkforios/ - * [^21]: http://aws.amazon.com/sdkforandroid/ - * [^22]: http://aws.amazon.com/articles/web-identity-federation-with-mobile-applications + * [^19]: http://aws.amazon.com/sdkforios/ + * [^20]: http://aws.amazon.com/sdkforandroid/ * * @see https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html * @see https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-sts-2011-06-15.html#assumerolewithwebidentity