Hi everyone. I recently went through this journey and thought I would share the installation instructions that I created for my AWS team members to follow to install. These instructions are specific to my org obviously. I removed any specific org info that i felt necessary. BTW I am creating a custom config.properties per person and just sending to them. I figured it was easier that way for all involved. My team isn’t that big and turnover is very low plus I get to create an individual access/secret key per person. I realize this is probably overkill security wise.
This install was way more involved than I had hoped for. It took my a solid week to get everything “production ready” for my folks and documented. I do have a background in Java and PowerShell and Windows administration so I was able to piece together the gaps. One example is that i don’t recall anything saying you have to “unzip” the .jar. Non Java folks will not know to do that.
Other thoughts:
-
F: is our AD home directory paths.
-
The formatting looks terrible because I copied and pasted from OneNote.
-
I had a bunch of HTTP links but it says new users can’t have more than 5 so I removed them all.
Anyways, onto instructions…
Installation
Notes
- Must user PowerShell and not Windows Command Line
- Overall steps (in order):
- Run install script, which will create .okta folder and configure $profile with okta aws commands.
- Run jar to unzip files inside .okta folder.
- Copy custom config.properties file from Austin to overwrite the default config.properties file in .okta folder.
- Two main pieces for this to work:
- All the source java files inside the .okta folder located in your $HOME directory, which on my workstation was C:\users[username] and my laptop it was F:.
- The $profile being updated at $PROFILE, which for me was F:\WindowsPowerShell\Microsoft.PowerShell_profile.ps1
- [If you want to install this one more than one machine, there are two issues to address]
- (1) At [org name] our $PROFILE is located on our F:. That means for every computer we log on to, we run the same $PROFILE script. The problem is there is a script that runs every time in $PROFILE when you open PowerShell and it is using the variable called $HOME to look for the java source files. The $HOME location must be the same on each of your computers or this will not work. For some reason the $HOME location was different between my workstations and laptop. To check it run the following commands:
- $HOME. Should show c:\users[username]
- $PROFILE. Should show [org path]\WindowsPowerShell\Microsoft.PowerShell_profile.ps1]
- If $HOME is different from above, you must change it. Setting the $HOME is only persistent for the PS session you have open unfortunately. To change it, add the following code to the $profile so that it overrides $HOME every time:
- Remove-Variable -Force HOME
- Set-Variable HOME "C:\Users[username];"
- (2) After you have already installed everything once, when you go to install on the next computer the Install script will not download the .jar file in the .okta folder. It will still create the other 3 files but just not the .jar. Follow the directions as normal for installation but after the step to run the install script, go to [org path] and copy ‘okta-aws-cli.jar’ into your C:\users[username].okta folder. Then proceed as normal with the next step of running the jar command.
- (1) At [org name] our $PROFILE is located on our F:. That means for every computer we log on to, we run the same $PROFILE script. The problem is there is a script that runs every time in $PROFILE when you open PowerShell and it is using the variable called $HOME to look for the java source files. The $HOME location must be the same on each of your computers or this will not work. For some reason the $HOME location was different between my workstations and laptop. To check it run the following commands:
- Install script
- It won’t run if you don’t already have a PowerShell profile created. See side article on how to create one.
- It won’t run if you already have .okta folder created in $HOME. If you encounter problems, blow away the .okta folder and the profile and start again.
- Will not run over VPN. Can’t connect to gethub.
- Config Parameters that do not work
- OKTA_STS_DURATION=28800 does not work.
- OKTA_ENV_MODE = this is unreliable
- OKTA_BROWSER_AUTH = this is unreliable
Why is this needed?
AWS is federated with Okta. What that means is you can log in with your [org name] account into AWS. You don’t actually have a ‘AWS user account’. Those are called IAM users. We only use a few IAM user accounts in AWS and those are for service accounts. So what happens when you try to authenticate to AWS is Okta is saying “give me a role”. Your [org name] account is assuming a predefined role that we have setup in AWS. Those roles are assigned by AD group (Admin, Developer, etc) in each AWS account (Prod, nProd, etc). The Native AWS CLI is expecting the person to have an IAM user account, which I just described us not having. So in order to use the CLI, Okta themselves wrote a wrapper Java Class to make it all work. When you use that, you assume one of the roles you have assigned. There is some back end work I had to do for that. Hopefully this makes a little more sense.
-
Install Java. Download and install Java JDK
-
Make sure to install the JDK and not the JRE. You will need this to run Jar command later.
-
Configure Java. Add bin for Java to PATH env variable (e.g. System Properties->Advanced tab->Environment Variables->Edit the Path variable->Add "C:\Program Files\Java\jdk1.8.0_201\bin")
-
Reboot for Java to take effect.
-
Configure PowerShell.
-
Open PowerShell and run the following commands (without quotations):
-
‘Get-Executionpolicy’
-
Results should be to either ‘RemoteSigned’ or ‘Unrestricted’.
-
‘Test-Path $profile’
-
Result should be True. If not, run the command (without quotations): ‘New-Item -path $profile -type file –force’ to create one. The script below won’t run without having a $profile.
-
‘$HOME’
-
Should show c:\users[username]. If not, its ok unless you plan to install this on more than one computer. Stop and contact Austin for more info if this is the case.
-
‘$PROFILE’
-
Should show [screenshot removed]
-
Open IE and add [internal server name] to Trusted Sites. Make sure require HTTPS box is unchecked.
-
This tells PowerShell to trust scripts running off your F: (aka $profile) . If you don’t do this then after the steps below are complete you will get a security warning every time you launch PowerShell.
-
Install AWS CLI commands. Download AWS CLI and install.
-
I used MSI installer but you can use Python and PIP if you want.
-
Verify working. Open a PowerShell and run the following command:
-
aws --version
-
Make sure it is version higher than 1.8.
-
Install Okta AWS PowerShell commands. Open PowerShell and run the following command:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy unrestricted -Force; Invoke-Expression ((New-Object Net.WebClient).DownloadString(‘https://raw.githubusercontent.com/oktadeveloper/okta-aws-cli-assume-role/master/bin/Install-OktaAwsCli.ps1’)); .$profile
-
Do not install on a [org name] laptop and off premise even with VPN, the script cannot connect to raw.githubusercontent and will fail.
-
This script will do two things:
-
Creates a .okta folder in your $HOME (C:\Users[username]). The contains of the folder should look like this:
[screen shot removed]
-
Update your PowerShell $profile (on your F:) so that each time PowerShell is launched all of the Okta-AWS executables that will be needed will be loaded. That is why you must use PowerShell to connect to AWS CLI and not Windows Command Prompt.
-
Install Okta AWS Java commands. In PowerShell, cd to .okta folder in $HOME (C:\Users[username] and run the command (without quotations) ‘jar xf okta-aws-cli.jar’
-
When complete, your C:\Users[username].okta should look like this:
[screenshot removed]
- Reach out to Austin and let him know that you would like CLI access to AWS. He will create you a custom.properties file to use.
- Take the config.properties file sent by Austin and put in .okta folder in $HOME (C:\Users[username]). Replace the current one.
- Complete. You are now ready to log in to AWS CLI!
Usage
Before we get started, this guide applies to users in Okta. Meaning, end users. This is how users in Okta would access the AWS CLI. If you want a service account or job to run scheduled tasks then we would probably not use this. We would have to explore case-by-case but probably we would create a local IAM user in AWS.
Let’s explain how this whole thing will work. In order to integrate with Okta, we must use their wrapper executables. This means that the command syntax will change slightly. For example, normal AWS CLI commands start with ‘aws’ then have the rest of the command you want to run.
Example: aws configure list (fyi this shows what region you’re connected to, what your access key is, and what your secret key is)
Now with Okta, ‘aws’ is replaced with ‘okta-aws’ and there is an additional parameter that must be added called a profile.
The same command above is now: okta-aws np configure list
So every command will be okta-aws [profile name] and then the normal AWS CLI command.
So what is the profile name? First, this is NOT the same thing as a PowerShell profile. This is a name that you pick to name your session. It doesn’t matter what you pick but it will use this name every time you type a command during the one hour window the session is active so I would keep it short. What is actually happening is there is a config file that is updated for each profile name you pick storing the role, the time you connected, and time your token expires (its 1 hour later). Think of this as your “session”.
The profile name really comes in to play when you are switching roles and/or AWS accounts during the one hour window the session is active. If you are only logging in to one AWS account (say, Prod) and will only use one role inside that account, such as Developer, for the one hour then profiles don’t really affect you.
However if you plan to CLI into different AWS accounts or you want to switch your roles in that account (say, run one task as Administrator then drop down to just Developer) during the one hour window the session is active, then pick profile names that are descriptive. Profile name will remember the account you logged into and the role you selected even if you change the config.properties file during the one hour window the session is active.
The workflow for logging into AWS CLI is:
-
Determine what AWS Account you want to CLI into (Sandbox, Prod, etc).
-
Open config.properties file in C:\Users[username].okta and uncomment out the Okta_AWS_App_URL for the env you want. Only one URL can be active at a time.
-
Launch PowerShell.
-
You must use PowerShell and not the Windows CMD prompt. The reason is there is a profile script you installed earlier that will make this work where as CMD will not find the executables to run this.
-
In PowerShell run the command (without quotations) ‘okta-aws [profile name you pick] sts get-caller-identity’
-
Example: okta-aws sec sts get-caller-identity
-
Your username should already be loaded in the config.properties file that you are given. Type your [org name] password. You will not have to authenticate again while you are within your 1 hour session window.
[screen shot removed]
- If you are off-premises of [org name] then you must MFA. This screenshot is an example of that that screen would look like from Okta documentation.
[screenshot removed]
-
After authenticating, you must now choose your role.
-
In the first screenshot below, I only have one role assigned in Okta so it auto assigns it to me. If you have more than one role, you will have to type the number of the role you want to pick.
[screenshot removed]
- If picking the role was successful, it automatically displays your account information for that session.
- You can now start issuing AWS commands. To test that everything is setup OK, run the following commands (without quotations):
- ‘okta-aws [profile name you pick] configure list’
- shows what your region, access key, and secret key is
- ‘okta-aws [profile name you pick] configure get region’
- shows the region you are logged in to.
- ‘okta-aws [profile name you pick] s3 ls’
- list all S3 buckets in this account (have to have permissions to do this so may not work)
- ‘okta-aws [profile name you pick] ec2 describe-instances’
- will list all ec2 in this account (have to have permissions to do this so may not work)
- Finished. You can now use AWS CLI as you like.
Optional: AWS Tools for PowerShell
In addition to the AWS CLI, there is also cmdlets for AWS in PowerShell. You don’t have to use this if you do not want.
If you have Windows 10, it is very easy to install. From an Administrator (must be Admin) PowerShell window just type (without quotations) ‘install-module -Name AWSPowerShell’
If you need help or don’t have Windows 10 here is the AWS page on installing PowerShell Tools.
To run AWS PowerShell tools you must do two things: 1. Specify a Profile you want to use for authentication and 2. Specify the Region you want to run the command in. One key difference from above is AWS PowerShell Tools does NOT import the Region from the Profile explained above so you have to actually tell PowerShell what Region you want to use.
Profiles
If you have followed the steps above then you are good to go. AWS PowerShell Tools makes use of the same Profile concept explained above when it comes to authentication and it works exactly the same as explained above. You have two options for specifying the Profile name to PowerShell, (1) use the Set-AWSCredential cmdlet to set this for your entire PowerShell session or you can use ‘-ProfileName’ switch behind each cmdlet to specify.
(without quotations)
(1) ‘Set-AWSCredential -ProfileName MyProfileName’
(2) ‘Get-EC2Instance -ProfileName MyProfileName’
Region
You can either set the Region for your whole PowerShell session or specify the Region after each cmdlet using the ‘-Region’ switch. You must set the Region! Most cmdlets will complain that you did not set the Region when you try to run them.
(without quotations)
(1) ‘Set-DefaultAWSRegion -Region us-east-1’
(2) ‘Get-EC2Instance -Region us-east-1’
Now you are ready to test.
Test
After you have set Profile and Region, you just run the AWS PowerShell commands. You DO NOT have to prefix each cmdlet with 'okta-aws [ProfileName] like you did above with AWS CLI. Just run the cmdlet as you would without Okta.
Some good test cmdlets (without quotations)
- ‘Get-AWSCredential -ListProfileDetail’
- This will list all your Profiles
- ‘Get-AWSRegion’
- Just lists all the regions in AWS
- ‘Get-Command -Module AWSPowerShell’
- Displays every AWS Powershell cmdlet
- ‘(Get-Ec2Instance).Instances | Select InstanceType, @{Name=“Servername”;Expression={$_.tags | where key -eq “Name” | Select Value -Expand Value}}’
- Displays all EC2 instances in the AWS Account you are connected to in your Profile. Displays it in a table format. You must have permissions for EC2 so may not work for you.