The AssumeRole
action returns a set of temporary security credentials that you can
use to access resources that are defined in the role’s policy. The returned credentials consist
of an Access Key ID, a Secret Access Key, and a security token.
Important: Only IAM users can assume a role. If you use AWS account
credentials to call AssumeRole, access is denied.
The credentials are valid for the duration that you specified when calling
AssumeRole
, which can be from 15 minutes to 1 hour.
When you assume a role, you have the privileges that are defined in the role. You can further
restrict the privileges by passing a policy when calling AssumeRole
.
To assume a role, you must be an IAM user from a trusted entity and have permission to call
AssumeRole
. Trusted entites are defined when the IAM role is created. Permission
to call AssumeRole
is defined in your or your group’s IAM policy.
Access
Parameters
Parameter |
Type |
Required |
Description |
$role_arn
|
string
|
Required
|
The Amazon Resource Name (ARN) of the role that the caller is assuming. |
$role_session_name
|
string
|
Required
|
An identifier for the assumed role session. The session name is included as part of the AssumedRoleUser . [Constraints: The value must be between 2 and 32 characters, and must match the following regular expression pattern: [\w+=,.@-]* ] |
$opt
|
array
|
Optional
|
An associative array of parameters that can have the following keys:
Policy - string - Optional - A supplemental policy that can be associated with the temporary security credentials. The caller can restrict the permissions that are available on the role’s temporary security credentials to maintain the least amount of privileges. When a service call is made with the temporary security credentials, both the role’s permission policy and supplemental policy are checked. For more information about how permissions work in the context of temporary credentials, see Controlling Permissions in Temporary Credentials. [Constraints: The value must be between 1 and 2048 characters, and must match the following regular expression pattern: [\u0009\u000A\u000D\u0020-\u00FF]+ ]DurationSeconds - integer - Optional - The duration, in seconds, of the role session. The value can range from 900 seconds (15 minutes) to 3600 seconds (1 hour). By default, the value is set to 3600 seconds (1 hour).ExternalId - string - Optional - A unique identifier that is generated by a third party for each of their customers. For each role that the third party can assume, they should instruct their customers to create a role with the external ID that was generated by the third party. Each time the third party assumes the role, they must pass the customer’s correct external ID. The external ID is useful in order to help third parties bind a role to the customer who created it. For more information about the external ID, see About the External ID in Using Temporary Security Credentials. [Constraints: The value must be between 2 and 96 characters, and must match the following regular expression pattern: [\w+=,.@:-]* ]curlopts - array - Optional - A set of values to pass directly into curl_setopt() , where the key is a pre-defined CURLOPT_* constant.returnCurlHandle - boolean - Optional - A private toggle specifying that the cURL handle be returned rather than actually completing the request. This toggle is useful for manually managed batch requests. |
Returns
Source
Method defined in services/sts.class.php | Toggle source view (8 lines) | View on GitHub
public function assume_role($role_arn, $role_session_name, $opt = null)
{
if (!$opt) $opt = array();
$opt['RoleArn'] = $role_arn;
$opt['RoleSessionName'] = $role_session_name;
return $this->authenticate('AssumeRole', $opt);
}