/******************************************************************************* * Copyright 2012-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. * Licensed under the Apache License, Version 2.0 (the "License"). You may not use * this file except in compliance with the License. A copy of the License is located at * * http://aws.amazon.com/apache2.0 * * or in the "license" file accompanying this file. * This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR * CONDITIONS OF ANY KIND, either express or implied. See the License for the * specific language governing permissions and limitations under the License. * ***************************************************************************** * * AWS Tools for Windows (TM) PowerShell (TM) * */ using System; using System.Collections.Generic; using System.Linq; using System.Management.Automation; using System.Text; using Amazon.PowerShell.Common; using Amazon.Runtime; using Amazon.SecurityToken; using Amazon.SecurityToken.Model; namespace Amazon.PowerShell.Cmdlets.STS { /// /// 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 and Comparing /// the Amazon Web Services STS API operations in the IAM User Guide. /// /// /// Permissions /// The temporary security credentials created by AssumeRole can be used /// to make API calls to any Amazon Web Services 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 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 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 to assume /// the role in the role trust policy. /// /// 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. /// /// A user who wants to access a role in a different account must also have permissions /// that are delegated from the account administrator. The administrator must attach a /// policy that allows the user to call AssumeRole for the ARN of the role /// in the other account. /// /// To allow a user to assume a role in the same account, you can do either of the following: /// /// 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 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 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 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 in the IAM User Guide. /// Using MFA with AssumeRole /// (Optional) You can include multi-factor authentication (MFA) information when you /// call AssumeRole. This is useful for cross-account scenarios to ensure /// that the user that assumes the role has been authenticated with an Amazon Web Services /// MFA device. In that scenario, the trust policy of the role being assumed includes /// a condition that tests for MFA authentication. If the caller does not include valid /// MFA information, the request to assume the role is denied. The condition in a trust /// policy that tests for MFA authentication might look like the following example. /// "Condition": {"Bool": {"aws:MultiFactorAuthPresent": true}} /// For more information, see Configuring /// MFA-Protected API Access 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. /// /// [Cmdlet("Use", "STSRole", SupportsShouldProcess = true, ConfirmImpact = ConfirmImpact.Medium)] [OutputType("Amazon.SecurityToken.Model.AssumeRoleResponse")] [AWSCmdlet("Calls the AWS Security Token Service (STS) AssumeRole API operation.", Operation = new[] {"AssumeRole"}, SelectReturnType = typeof(Amazon.SecurityToken.Model.AssumeRoleResponse))] [AWSCmdletOutput("Amazon.SecurityToken.Model.AssumeRoleResponse", "This cmdlet returns an Amazon.SecurityToken.Model.AssumeRoleResponse object containing multiple properties. The object can also be referenced from properties attached to the cmdlet entry in the $AWSHistory stack." )] public partial class UseSTSRoleCmdlet : AmazonSecurityTokenServiceClientCmdlet, IExecutor { protected override bool IsSensitiveResponse { get; set; } = true; #region Parameter DurationInSeconds /// /// /// The duration, in seconds, of the role session. The value specified can range from /// 900 seconds (15 minutes) up to the maximum session duration set for the role. The /// maximum session duration setting can have a value from 1 hour to 12 hours. If you /// specify a value higher than this setting or the administrator setting (whichever is /// lower), the operation fails. For example, if you specify a session duration of 12 /// hours, but your administrator set the maximum session duration to 6 hours, your operation /// fails. Role chaining limits your Amazon Web Services CLI or Amazon Web Services API role /// session to a maximum of one hour. When you use the AssumeRole API operation /// to assume a role, you can specify the duration of your role session with 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 in the IAM User Guide.By default, the value is set to 3600 seconds. The DurationSeconds parameter is separate from the duration of a console /// session that you might request using the returned credentials. The request to the /// federation endpoint for a console sign-in token takes a SessionDuration /// 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 /// in the IAM User Guide. /// /// [System.Management.Automation.Parameter(Position = 3, ValueFromPipelineByPropertyName = true)] [Alias("DurationSeconds")] public System.Int32? DurationInSeconds { get; set; } #endregion #region Parameter ExternalId /// /// /// A unique identifier that might be required when you assume a role in another account. /// If the administrator of the account to which the role belongs provided you with an /// external ID, then provide that value in the ExternalId parameter. This /// value can be any string, such as a passphrase or account number. A cross-account role /// is usually set up to trust everyone in an account. Therefore, the administrator of /// the trusting account might send an external ID to the administrator of the trusted /// account. That way, only someone with the ID can assume the role, rather than everyone /// in the account. For more information about the external ID, see How /// to Use an External ID When Granting Access to Your Amazon Web Services Resources to /// a Third Party 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: =,.@:/- /// /// [System.Management.Automation.Parameter(Position = 4, ValueFromPipelineByPropertyName = true)] public System.String ExternalId { get; set; } #endregion #region Parameter Policy /// /// /// An IAM policy in JSON format that you want to use as an inline session policy.This parameter is optional. 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 in the IAM User Guide.The plaintext that you use for both inline and managed session policies can't exceed /// 2,048 characters. The JSON 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.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. /// /// [System.Management.Automation.Parameter(Position = 2, ValueFromPipelineByPropertyName = true)] public System.String Policy { get; set; } #endregion #region Parameter PolicyArn /// /// /// The Amazon Resource Names (ARNs) of the IAM managed policies that you want to use /// as managed session policies. The policies must exist in the same account as the role.This parameter is optional. You can provide up to 10 managed policy ARNs. However, /// the plaintext that you use for both inline and managed session policies can't exceed /// 2,048 characters. For more information about ARNs, see Amazon /// Resource Names (ARNs) and Amazon Web Services Service Namespaces in the Amazon /// Web Services General Reference.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.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 in the IAM User Guide. /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] [Alias("PolicyArns")] public Amazon.SecurityToken.Model.PolicyDescriptorType[] PolicyArn { get; set; } #endregion #region Parameter ProvidedContext /// /// /// Reserved for future use. /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] [Alias("ProvidedContexts")] public Amazon.SecurityToken.Model.ProvidedContext[] ProvidedContext { get; set; } #endregion #region Parameter RoleArn /// /// /// The Amazon Resource Name (ARN) of the role to assume. /// /// #if !MODULAR [System.Management.Automation.Parameter(Position = 0, ValueFromPipelineByPropertyName = true, ValueFromPipeline = true)] #else [System.Management.Automation.Parameter(Position = 0, ValueFromPipelineByPropertyName = true, ValueFromPipeline = true, Mandatory = true)] [System.Management.Automation.AllowEmptyString] [System.Management.Automation.AllowNull] #endif [Amazon.PowerShell.Common.AWSRequiredParameter] public System.String RoleArn { get; set; } #endregion #region Parameter RoleSessionName /// /// /// An identifier for the assumed role session.Use the role session name to uniquely identify a session when the same role is assumed /// by different principals or for different reasons. In cross-account scenarios, the /// role session name is visible to, and can be logged by the account that owns the role. /// The role session name is also used in the ARN of the assumed role principal. This /// means that 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.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: =,.@- /// /// #if !MODULAR [System.Management.Automation.Parameter(Position = 1, ValueFromPipelineByPropertyName = true)] #else [System.Management.Automation.Parameter(Position = 1, ValueFromPipelineByPropertyName = true, Mandatory = true)] [System.Management.Automation.AllowEmptyString] [System.Management.Automation.AllowNull] #endif [Amazon.PowerShell.Common.AWSRequiredParameter] public System.String RoleSessionName { get; set; } #endregion #region Parameter SerialNumber /// /// /// The identification number of the MFA device that is associated with the user who is /// making the AssumeRole call. Specify this value if the trust policy of /// the role being assumed includes a condition that requires MFA authentication. The /// value is either the serial number for a hardware device (such as GAHT12345678) /// or an Amazon Resource Name (ARN) for a virtual device (such as arn:aws:iam::123456789012:mfa/user).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: =,.@- /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] public System.String SerialNumber { get; set; } #endregion #region Parameter SourceIdentity /// /// /// The source identity specified by the principal that is calling the AssumeRole /// operation.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 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 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. /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] public System.String SourceIdentity { get; set; } #endregion #region Parameter Tag /// /// /// A list of session tags that you want to pass. Each session tag consists of a key name /// and an associated value. For more information about session tags, see Tagging /// Amazon Web Services STS Sessions in the IAM User Guide.This parameter is optional. You can pass up to 50 session tags. The plaintext session /// tag keys can’t exceed 128 characters, and the values can’t exceed 256 characters. /// For these and additional limits, see IAM /// and STS Character Limits in the IAM User Guide.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.You can pass a session tag with the same key as a tag that is already attached to /// the role. When you do, session tags override a role tag with the same key. Tag key–value pairs are not case sensitive, but case is preserved. This means that /// you cannot have separate Department and department tag keys. /// Assume that the role has the Department=Marketing tag and /// you pass the department=engineering session tag. Department /// and department are not saved as separate tags, and the session tag passed /// in the request takes precedence over the role tag.Additionally, if you used temporary credentials to perform this operation, the new /// session inherits any transitive session tags from the calling session. If you pass /// a session tag with the same key as an inherited tag, the operation fails. To view /// the inherited tags for a session, see the CloudTrail logs. For more information, see /// Viewing /// Session Tags in CloudTrail in the IAM User Guide. /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] [Alias("Tags")] public Amazon.SecurityToken.Model.Tag[] Tag { get; set; } #endregion #region Parameter TokenCode /// /// /// The value provided by the MFA device, if the trust policy of the role being assumed /// requires MFA. (In other words, if the policy includes a condition that tests for MFA). /// If the role being assumed requires MFA and if the TokenCode value is /// missing or expired, the AssumeRole call returns an "access denied" error.The format for this parameter, as described by its regex pattern, is a sequence of /// six numeric digits. /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] public System.String TokenCode { get; set; } #endregion #region Parameter TransitiveTagKey /// /// /// A list of keys for session tags that you want to set as transitive. If you set a tag /// key as transitive, the corresponding key and value passes to subsequent sessions in /// a role chain. For more information, see Chaining /// Roles with Session Tags 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.If you choose not to specify a transitive tag key, then no tags are passed from this /// session to any subsequent sessions. /// /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] [Alias("TransitiveTagKeys")] public System.String[] TransitiveTagKey { get; set; } #endregion #region Parameter Select /// /// Use the -Select parameter to control the cmdlet output. The default value is '*'. /// Specifying -Select '*' will result in the cmdlet returning the whole service response (Amazon.SecurityToken.Model.AssumeRoleResponse). /// Specifying the name of a property of type Amazon.SecurityToken.Model.AssumeRoleResponse will result in that property being returned. /// Specifying -Select '^ParameterName' will result in the cmdlet returning the selected cmdlet parameter value. /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] public string Select { get; set; } = "*"; #endregion #region Parameter PassThru /// /// Changes the cmdlet behavior to return the value passed to the RoleArn parameter. /// The -PassThru parameter is deprecated, use -Select '^RoleArn' instead. This parameter will be removed in a future version. /// [System.Obsolete("The -PassThru parameter is deprecated, use -Select '^RoleArn' instead. This parameter will be removed in a future version.")] [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] public SwitchParameter PassThru { get; set; } #endregion #region Parameter Force /// /// This parameter overrides confirmation prompts to force /// the cmdlet to continue its operation. This parameter should always /// be used with caution. /// [System.Management.Automation.Parameter(ValueFromPipelineByPropertyName = true)] public SwitchParameter Force { get; set; } #endregion protected override void ProcessRecord() { this._AWSSignerType = "v4"; base.ProcessRecord(); var resourceIdentifiersText = FormatParameterValuesForConfirmationMsg(nameof(this.RoleArn), MyInvocation.BoundParameters); if (!ConfirmShouldProceed(this.Force.IsPresent, resourceIdentifiersText, "Use-STSRole (AssumeRole)")) { return; } var context = new CmdletContext(); // allow for manipulation of parameters prior to loading into context PreExecutionContextLoad(context); #pragma warning disable CS0618, CS0612 //A class member was marked with the Obsolete attribute if (ParameterWasBound(nameof(this.Select))) { context.Select = CreateSelectDelegate(Select) ?? throw new System.ArgumentException("Invalid value for -Select parameter.", nameof(this.Select)); if (this.PassThru.IsPresent) { throw new System.ArgumentException("-PassThru cannot be used when -Select is specified.", nameof(this.Select)); } } else if (this.PassThru.IsPresent) { context.Select = (response, cmdlet) => this.RoleArn; } #pragma warning restore CS0618, CS0612 //A class member was marked with the Obsolete attribute context.DurationInSeconds = this.DurationInSeconds; context.ExternalId = this.ExternalId; context.Policy = this.Policy; if (this.PolicyArn != null) { context.PolicyArn = new List(this.PolicyArn); } if (this.ProvidedContext != null) { context.ProvidedContext = new List(this.ProvidedContext); } context.RoleArn = this.RoleArn; #if MODULAR if (this.RoleArn == null && ParameterWasBound(nameof(this.RoleArn))) { WriteWarning("You are passing $null as a value for parameter RoleArn which is marked as required. In case you believe this parameter was incorrectly marked as required, report this by opening an issue at https://github.com/aws/aws-tools-for-powershell/issues."); } #endif context.RoleSessionName = this.RoleSessionName; #if MODULAR if (this.RoleSessionName == null && ParameterWasBound(nameof(this.RoleSessionName))) { WriteWarning("You are passing $null as a value for parameter RoleSessionName which is marked as required. In case you believe this parameter was incorrectly marked as required, report this by opening an issue at https://github.com/aws/aws-tools-for-powershell/issues."); } #endif context.SerialNumber = this.SerialNumber; context.SourceIdentity = this.SourceIdentity; if (this.Tag != null) { context.Tag = new List(this.Tag); } context.TokenCode = this.TokenCode; if (this.TransitiveTagKey != null) { context.TransitiveTagKey = new List(this.TransitiveTagKey); } // allow further manipulation of loaded context prior to processing PostExecutionContextLoad(context); var output = Execute(context) as CmdletOutput; ProcessOutput(output); } #region IExecutor Members public object Execute(ExecutorContext context) { var cmdletContext = context as CmdletContext; // create request var request = new Amazon.SecurityToken.Model.AssumeRoleRequest(); if (cmdletContext.DurationInSeconds != null) { request.DurationSeconds = cmdletContext.DurationInSeconds.Value; } if (cmdletContext.ExternalId != null) { request.ExternalId = cmdletContext.ExternalId; } if (cmdletContext.Policy != null) { request.Policy = cmdletContext.Policy; } if (cmdletContext.PolicyArn != null) { request.PolicyArns = cmdletContext.PolicyArn; } if (cmdletContext.ProvidedContext != null) { request.ProvidedContexts = cmdletContext.ProvidedContext; } if (cmdletContext.RoleArn != null) { request.RoleArn = cmdletContext.RoleArn; } if (cmdletContext.RoleSessionName != null) { request.RoleSessionName = cmdletContext.RoleSessionName; } if (cmdletContext.SerialNumber != null) { request.SerialNumber = cmdletContext.SerialNumber; } if (cmdletContext.SourceIdentity != null) { request.SourceIdentity = cmdletContext.SourceIdentity; } if (cmdletContext.Tag != null) { request.Tags = cmdletContext.Tag; } if (cmdletContext.TokenCode != null) { request.TokenCode = cmdletContext.TokenCode; } if (cmdletContext.TransitiveTagKey != null) { request.TransitiveTagKeys = cmdletContext.TransitiveTagKey; } CmdletOutput output; // issue call var client = Client ?? CreateClient(_CurrentCredentials, _RegionEndpoint); try { var response = CallAWSServiceOperation(client, request); object pipelineOutput = null; pipelineOutput = cmdletContext.Select(response, this); output = new CmdletOutput { PipelineOutput = pipelineOutput, ServiceResponse = response }; } catch (Exception e) { output = new CmdletOutput { ErrorResponse = e }; } return output; } public ExecutorContext CreateContext() { return new CmdletContext(); } #endregion #region AWS Service Operation Call private Amazon.SecurityToken.Model.AssumeRoleResponse CallAWSServiceOperation(IAmazonSecurityTokenService client, Amazon.SecurityToken.Model.AssumeRoleRequest request) { Utils.Common.WriteVerboseEndpointMessage(this, client.Config, "AWS Security Token Service (STS)", "AssumeRole"); try { #if DESKTOP return client.AssumeRole(request); #elif CORECLR return client.AssumeRoleAsync(request).GetAwaiter().GetResult(); #else #error "Unknown build edition" #endif } catch (AmazonServiceException exc) { var webException = exc.InnerException as System.Net.WebException; if (webException != null) { throw new Exception(Utils.Common.FormatNameResolutionFailureMessage(client.Config, webException.Message), webException); } throw; } } #endregion internal partial class CmdletContext : ExecutorContext { public System.Int32? DurationInSeconds { get; set; } public System.String ExternalId { get; set; } public System.String Policy { get; set; } public List PolicyArn { get; set; } public List ProvidedContext { get; set; } public System.String RoleArn { get; set; } public System.String RoleSessionName { get; set; } public System.String SerialNumber { get; set; } public System.String SourceIdentity { get; set; } public List Tag { get; set; } public System.String TokenCode { get; set; } public List TransitiveTagKey { get; set; } public System.Func Select { get; set; } = (response, cmdlet) => response; } } }