AWS powershell medium security documentation change
Summary
Added new section 'Login using console credentials' explaining browser-based authentication with temporary credentials, introduced Invoke-AWSLogin/Logout cmdlets, and restructured configuration steps
Security assessment
The change promotes using temporary credentials instead of long-term access keys, explicitly stating it 'enhances security by eliminating the need to store long-term credentials locally'. This addresses credential management security best practices. The documentation of credential caching locations and session management also relates to security controls.
Diff
diff --git a/powershell/v5/userguide/creds-idc.md b/powershell/v5/userguide/creds-idc.md index 1b4cac007..804dc42fa 100644 --- a//powershell/v5/userguide/creds-idc.md +++ b//powershell/v5/userguide/creds-idc.md @@ -5 +5 @@ -Enable and configure IAM Identity CenterConfigure the Tools for PowerShell to use IAM Identity Center.Start an AWS access portal sessionExampleAdditional information +Login using console credentialsEnable and configure IAM Identity CenterConfigure the Tools for PowerShell to use IAM Identity Center.Start an AWS access portal sessionExampleAdditional information @@ -23 +23 @@ Configuring this environment requires several steps, which are summarized as fol - 1. Enable and configure IAM Identity Center + 1. Login using console credentials @@ -25 +25 @@ Configuring this environment requires several steps, which are summarized as fol - 2. Configure the Tools for PowerShell to use IAM Identity Center. + 2. Enable and configure IAM Identity Center @@ -27 +27 @@ Configuring this environment requires several steps, which are summarized as fol - 3. Start an AWS access portal session + 3. Configure the Tools for PowerShell to use IAM Identity Center. @@ -28,0 +29 @@ Configuring this environment requires several steps, which are summarized as fol + 4. Start an AWS access portal session @@ -31,0 +33,135 @@ Configuring this environment requires several steps, which are summarized as fol + +## Login using console credentials + +You can use your existing AWS Management Console sign-in credentials for programmatic access to AWS services. After a browser-based authentication flow, AWS Tools for PowerShell generates temporary credentials that work across local development tools like the AWS SDKs, AWS Tools for PowerShell and AWS CLI. This feature simplifies the process of configuring and managing CLI credentials, especially if you prefer interactive authentication over managing long-term access keys. + +With this process, you can authenticate using root credentials created during initial account set up, an IAM user, or a federated identity from your identity provider, and Tools for PowerShell automatically manages the temporary credentials for you. This approach enhances security by eliminating the need to store long-term credentials locally. + +When you run the `Invoke-AWSLogin` cmdlet, you can select from your active console sessions, or sign in through the browser-based authentication flow and this will automatically generate temporary credentials. AWS Tools for PowerShell will automatically refresh these credentials for up to 12 hours. + +Once configured, your session can be used in AWS Tools for PowerShell and all other AWS SDKs and Tools. + +### Log in to AWS with the Invoke-AWSLogin Cmdlet + +Run the `Invoke-AWSLogin` cmdlet to authenticate using your existing AWS Management Console credentials. If you have not previously configured a profile, you will be prompted for additional information. + +To sign in or configure a profile follow the below steps. + + 1. Make sure you have imported the correct module you have installed from the installation guide. + +###### Note + +We have three different modules for PowerShell - `AWS.Tools`, `AWSPowerShell.NetCore` and `AWSPowerShell`. See [What are the AWS Tools for PowerShell?](./pstools-welcome.html) for more information. + + * In your PowerShell terminal, run the cmdlet. This will use the `default` profile. + + PS > Invoke-AWSLogin + + * To sign in to a named profile or create a new one, use the `-ProfileName` parameter. + + PS > Invoke-AWSLogin -ProfileName 'my-dev-profile' + + * If this is a new profile or no AWS Region has been specified or configured in any of your previous profiles/environment variables, the cmdlet prompts you to provide a region. + + Press Ctrl+C to cancel the following login prompts. + + Specify AWS Region + No AWS region has been configured. The AWS region is the geographic location of your AWS resources. + + If you've used AWS before and already have resources in your account, tell us which region they were created in. If you + haven't created resources in your account before, you can pick the region closest to you: + https://docs.aws.amazon.com/global-infrastructure/latest/regions/aws-regions.html + + AWS Region: + + 2. The AWS Tools for PowerShell attempts to open your default browser for the sign in process of your AWS account. + + Using region 'us-west-2' + Attempting to open the login page for 'us-west-2' in your default browser. + If the browser does not open, use the following URL to complete your login: + https://signin.us-west-2.amazonaws.com/authorize?<abbreviated> + + If you cannot connect to this URL, make sure that you have specified a valid region. + + * If the device using AWS Tools for PowerShell does not have a browser, you can use the `-Remote` parameter to provide a URL for you to open on a browser-enabled device. + + PS > Invoke-AWSLogin -Remote + + * If you used the `-Remote` parameter, instructions to manually start the sign in process are displayed based on the type of authorization you are using. The URL displayed is a unique URL starting with: https://signin.us-east-1.amazonaws.com/authorize. Once you complete the browser log in, you will need to copy and paste the resulting authorization code back in the terminal. + + Press Ctrl+C to cancel the following login prompts. + Using region 'us-west-2' determined by profile/environment defaults. To override, specify '-Region' parameter. + Please complete the login workflow via the following URL: + + https://us-west-2.signin.aws.amazon.com/v1/authorize?<abbrievated> + + Please enter the authorization code displayed in the browser: + + 3. In the browser, select your credentials to use from the displayed list and then return to your terminal. + + * If the profile you are configuring has a previously configured login session that does not match your new session, the AWS Tools for PowerShell prompts you to confirm that you are switching the session that corresponds to the existing profile. + + WARNING: Previously profile default was configured for arn:aws:iam::0123456789012:user/ReadOnly, + and is now being updated to arn:aws:iam::0123456789012:user/Admin. + + Do you wish to change the identity that default is associated with? (y/n) + + 4. A final message describes the completed profile configuration. + + Login completed successfully for profile 'my-dev-profile'. + +The authentication token is cached to disk under the .aws/login/cache directory with a hash filename based on the resolved profile. + + + + +#### Generated configuration file + +These steps result in creating the default or specified profile in the config file that looks like the following: + + + [default] + login_session = arn:aws:iam::0123456789012:user/username + region = us-east-1 + + [my-dev-profile] + login_session = arn:aws:iam::0123456789012:user/username + region = us-east-1 + +#### Run a command with your profile + +Once signed in, you can use your credentials to invoke Tools for PowerShell cmdlets with the associated profile. The following example calls the `Get-STSCallerIdentity` cmdlet using the default profile: + + + PS > Get-STSCallerIdentity + +To check for a specific session, use the `-ProfileName` parameter. + + + PS > Get-STSCallerIdentity -ProfileName 'my-dev-profile' + +The temporary credential token will expire in 15 minutes, but the AWS Tools for PowerShell and SDKs automatically refresh the token when needed during your requests. The overall session will be valid for up to 12 hours, after which you must run the `Invoke-AWSLogin` cmdlet again. + +#### Signing out of your session using the `Invoke-AWSLogout` cmdlet + +When you are done with your session, you can let your credentials expire, or run the `Invoke-AWSLogout` cmdlet to delete your cached credentials. If no profile is specified in the CLI or in the AWS_PROFILE environment variable, the command signs you out of your default profile. The following example signs you out of your default profile. + + + PS > Invoke-AWSLogout + +To sign out of a specific profile session, use the `-ProfileName` parameter. + + + PS > Invoke-AWSLogout -ProfileName 'my-dev-profile' + +To sign out of all the profile sessions you've logged in, use the `-All` parameter. + + + PS > Invoke-AWSLogout -All + +#### Cached Credentials + +The temporary cached credentials, as well as the metadata required to refresh them are stored by default in `%USERPROFILE%\.aws\login\cache` on Windows or `~/.aws/login/cache` on Linux and MacOS. + +You can override this location by setting the `AWS_LOGIN_CACHE_DIRECTORY` environment variable. +