/******************************************************************************* * Copyright 2012-2018 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 { /// <summary> /// Returns a set of temporary security credentials for users who have been authenticated /// via a SAML authentication response. This operation provides a mechanism for tying /// an enterprise identity store or directory to role-based AWS access without user-specific /// credentials or configuration. For a comparison of <code>AssumeRoleWithSAML</code> /// with the other APIs that produce temporary credentials, see <a href="http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html">Requesting /// Temporary Security Credentials</a> and <a href="http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#stsapi_comparison">Comparing /// the AWS STS APIs</a> in the <i>IAM User Guide</i>. /// /// /// <para> /// The temporary security credentials returned by this operation 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 AWS services. /// </para><para> /// The temporary security credentials are valid for the duration that you specified when /// calling <code>AssumeRole</code>, or until the time specified in the SAML authentication /// response's <code>SessionNotOnOrAfter</code> value, whichever is shorter. The duration /// can be from 900 seconds (15 minutes) to a maximum of 3600 seconds (1 hour). The default /// is 1 hour. /// </para><para> /// The temporary security credentials created by <code>AssumeRoleWithSAML</code> can /// be used to make API calls to any AWS service with the following exception: you cannot /// call the STS service's <code>GetFederationToken</code> or <code>GetSessionToken</code> /// APIs. /// </para><para> /// Optionally, you can pass an IAM access policy to this operation. If you choose not /// to pass a policy, the temporary security credentials that are returned by the operation /// have the permissions that are defined in the access policy of the role that is being /// assumed. If you pass a policy to this operation, the temporary security credentials /// that are returned by the operation have the permissions that are allowed by the intersection /// of both the access policy of the role that is being assumed, <i><b>and</b></i> the /// policy that you pass. This means that both policies must grant the permission for /// the action to be allowed. This gives you a way to further restrict the permissions /// for the resulting temporary security credentials. You cannot use the passed policy /// to grant permissions that are in excess of those allowed by the access policy of the /// role that is being assumed. For more information, see <a href="http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_assumerole.html">Permissions /// for AssumeRole, AssumeRoleWithSAML, and AssumeRoleWithWebIdentity</a> in the <i>IAM /// User Guide</i>. /// </para><para> /// Before your application can call <code>AssumeRoleWithSAML</code>, you must configure /// your SAML identity provider (IdP) to issue the claims required by AWS. Additionally, /// you must use AWS Identity and Access Management (IAM) to create a SAML provider entity /// in your AWS account that represents your identity provider, and create an IAM role /// that specifies this SAML provider in its trust policy. /// </para><para> /// Calling <code>AssumeRoleWithSAML</code> does not require the use of AWS security credentials. /// The identity of the caller is validated by using keys in the metadata document that /// is uploaded for the SAML provider entity for your identity provider. /// </para><important><para> /// Calling <code>AssumeRoleWithSAML</code> can result in an entry in your AWS CloudTrail /// logs. The entry includes the value in the <code>NameID</code> element of the SAML /// assertion. We recommend that you use a NameIDType that is not associated with any /// personally identifiable information (PII). For example, you could instead use the /// Persistent Identifier (<code>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</code>). /// </para></important><para> /// For more information, see the following resources: /// </para><ul><li><para><a href="http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_saml.html">About /// SAML 2.0-based Federation</a> in the <i>IAM User Guide</i>. /// </para></li><li><para><a href="http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml.html">Creating /// SAML Identity Providers</a> in the <i>IAM User Guide</i>. /// </para></li><li><para><a href="http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_relying-party.html">Configuring /// a Relying Party and Claims</a> in the <i>IAM User Guide</i>. /// </para></li><li><para><a href="http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html">Creating /// a Role for SAML 2.0 Federation</a> in the <i>IAM User Guide</i>. /// </para></li></ul> /// </summary> [Cmdlet("Use", "STSRoleWithSAML", SupportsShouldProcess = true, ConfirmImpact = ConfirmImpact.Medium)] [OutputType("Amazon.SecurityToken.Model.AssumeRoleWithSAMLResponse")] [AWSCmdlet("Calls the AWS Security Token Service AssumeRoleWithSAML API operation.", Operation = new[] { "AssumeRoleWithSAML" }, SelectReturnType = typeof(Amazon.SecurityToken.Model.AssumeRoleWithSAMLResponse))] [AWSCmdletOutput("Amazon.SecurityToken.Model.AssumeRoleWithSAMLResponse", "This cmdlet returns an Amazon.SecurityToken.Model.AssumeRoleWithSAMLResponse object containing multiple properties. The object can also be referenced from properties attached to the cmdlet entry in the $AWSHistory stack.")] [AWSClientCmdlet("AWS Security Token Service", "STS", null, "SecurityToken")] public partial class UseSTSRoleWithSAMLCmdlet : BaseCmdlet, IExecutor { protected IAmazonSecurityTokenService Client { get; private set; } #region Parameter DurationInSeconds /// <summary> /// <para> /// <para>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. /// An expiration can also be specified in the SAML authentication response's <code>SessionNotOnOrAfter</code> /// value. The actual expiration time is whichever value is shorter. </para><note><para>This 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 <code>SessionDuration</code> parameter that specifies the maximum length /// of the console session, separately from the <code>DurationSeconds</code> parameter /// on this API. For more information, see <a href="http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_enable-console-saml.html">Enabling /// SAML 2.0 Federated Users to Access the AWS Management Console</a> in the <i>IAM User /// Guide</i>.</para></note> /// </para> /// </summary> [System.Management.Automation.Parameter(Position = 4, ValueFromPipelineByPropertyName = true)] [Alias("DurationSeconds")] public System.Int32 DurationInSeconds { get; set; } #endregion #region Parameter Policy /// <summary> /// <para> /// <para>An IAM policy in JSON format.</para><para>The policy parameter is optional. If you pass a policy, the temporary security credentials /// that are returned by the operation have the permissions that are allowed by both the /// access policy of the role that is being assumed, <i><b>and</b></i> the policy that /// you pass. This gives you a way to further restrict the permissions for the resulting /// temporary security credentials. You cannot use the passed policy to grant permissions /// that are in excess of those allowed by the access policy of the role that is being /// assumed. For more information, <a href="http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_assumerole.html">Permissions /// for AssumeRole, AssumeRoleWithSAML, and AssumeRoleWithWebIdentity</a> in the <i>IAM /// User Guide</i>. </para><para>The format for this parameter, as described by its regex pattern, is a string of characters /// up to 2048 characters in length. The characters can be any ASCII character from the /// space character to the end of the valid character list (\u0020-\u00FF). It can also /// include the tab (\u0009), linefeed (\u000A), and carriage return (\u000D) characters.</para><note><para>The policy plain text must be 2048 bytes or shorter. However, an internal conversion /// compresses it into a packed binary format with a separate limit. The PackedPolicySize /// response element indicates by percentage how close to the upper size limit the policy /// is, with 100% equaling the maximum allowed size.</para></note> /// </para> /// </summary> [System.Management.Automation.Parameter(Position = 3, ValueFromPipelineByPropertyName = true)] public System.String Policy { get; set; } #endregion #region Parameter PrincipalArn /// <summary> /// <para> /// <para>The Amazon Resource Name (ARN) of the SAML provider in IAM that describes the IdP.</para> /// </para> /// </summary> [System.Management.Automation.Parameter(Position = 1, ValueFromPipelineByPropertyName = true)] public System.String PrincipalArn { get; set; } #endregion #region Parameter RoleArn /// <summary> /// <para> /// <para>The Amazon Resource Name (ARN) of the role that the caller is assuming.</para> /// </para> /// </summary> [System.Management.Automation.Parameter(Position = 0, ValueFromPipeline = true, ValueFromPipelineByPropertyName = true)] public System.String RoleArn { get; set; } #endregion #region Parameter SAMLAssertion /// <summary> /// <para> /// <para>The base-64 encoded SAML authentication response provided by the IdP.</para><para>For more information, see <a href="http://docs.aws.amazon.com/IAM/latest/UserGuide/create-role-saml-IdP-tasks.html">Configuring /// a Relying Party and Adding Claims</a> in the <i>Using IAM</i> guide. </para> /// </para> /// </summary> [System.Management.Automation.Parameter(Position = 2, ValueFromPipelineByPropertyName = true)] public System.String SAMLAssertion { get; set; } #endregion #region Parameter Force /// <summary> /// This parameter overrides confirmation prompts to force /// the cmdlet to continue its operation. This parameter should always /// be used with caution. /// </summary> [System.Management.Automation.Parameter] public SwitchParameter Force { get; set; } #endregion #region Parameter Region /// <summary> /// The region to use. STS has a single endpoint irrespective of region, though STS in GovCloud and China (Beijing) has its own endpoint. /// </summary> [Parameter(ValueFromPipelineByPropertyName = true)] public System.String Region { get; set; } #endregion #region Parameter Select /// <summary> /// 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.AssumeRoleWithSAMLResponse). /// Specifying the name of a property of type Amazon.SecurityToken.Model.AssumeRoleWithSAMLResponse will result in that property being returned. /// Specifying -Select '^ParameterName' will result in the cmdlet returning the selected cmdlet parameter value. /// </summary> [System.Management.Automation.Parameter] public string Select { get; set; } = "*"; #endregion protected IAmazonSecurityTokenService CreateClient() { var config = new AmazonSecurityTokenServiceConfig(); Amazon.PowerShell.Utils.Common.PopulateConfig(this, config); if (!string.IsNullOrEmpty(this.Region)) { config.RegionEndpoint = RegionEndpoint.GetBySystemName(this.Region); } AmazonSecurityTokenServiceClient client = new AmazonSecurityTokenServiceClient(new AnonymousAWSCredentials(), config); client.BeforeRequestEvent += RequestEventHandler; client.AfterResponseEvent += ResponseEventHandler; return client; } protected override void ProcessRecord() { base.ProcessRecord(); var resourceIdentifiersText = FormatParameterValuesForConfirmationMsg("RoleArn", MyInvocation.BoundParameters); if (!ConfirmShouldProceed(this.Force.IsPresent, resourceIdentifiersText, "Use-STSRoleWithSAML (AssumeRoleWithSAML)")) { return; } Client = CreateClient(); var context = new CmdletContext { Region = this.Region }; // allow for manipulation of parameters prior to loading into context PreExecutionContextLoad(context); if (ParameterWasBound(nameof(this.Select))) { context.Select = CreateSelectDelegate<Amazon.SecurityToken.Model.AssumeRoleWithSAMLResponse, UseSTSRoleWithSAMLCmdlet>(Select) ?? throw new System.ArgumentException("Invalid value for -Select parameter.", nameof(this.Select)); } if (ParameterWasBound("DurationInSeconds")) context.DurationInSeconds = this.DurationInSeconds; context.Policy = this.Policy; context.PrincipalArn = this.PrincipalArn; context.RoleArn = this.RoleArn; context.SAMLAssertion = this.SAMLAssertion; // 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.AssumeRoleWithSAMLRequest(); if (cmdletContext.DurationInSeconds != null) { request.DurationSeconds = cmdletContext.DurationInSeconds.Value; } if (cmdletContext.Policy != null) { request.Policy = cmdletContext.Policy; } if (cmdletContext.PrincipalArn != null) { request.PrincipalArn = cmdletContext.PrincipalArn; } if (cmdletContext.RoleArn != null) { request.RoleArn = cmdletContext.RoleArn; } if (cmdletContext.SAMLAssertion != null) { request.SAMLAssertion = cmdletContext.SAMLAssertion; } CmdletOutput output; // issue call var client = Client ?? CreateClient(); try { var response = CallAWSServiceOperation(client, request); object 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.AssumeRoleWithSAMLResponse CallAWSServiceOperation(IAmazonSecurityTokenService client, Amazon.SecurityToken.Model.AssumeRoleWithSAMLRequest request) { Utils.Common.WriteVerboseEndpointMessage(this, client.Config, "AWS Security Token Service", "AssumeRoleWithSAML"); try { #if DESKTOP return client.AssumeRoleWithSAML(request); #elif CORECLR return client.AssumeRoleWithSAMLAsync(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 class CmdletContext : ExecutorContext { public System.Int32? DurationInSeconds { get; set; } public System.String Policy { get; set; } public System.String PrincipalArn { get; set; } public System.String RoleArn { get; set; } public System.String SAMLAssertion { get; set; } public String Region { get; set; } public System.Func<Amazon.SecurityToken.Model.AssumeRoleWithSAMLResponse, UseSTSRoleWithSAMLCmdlet, object> Select { get; set; } = (response, cmdlet) => response; } } }