Whenever working with HTTP-Federation (H-Fed) applications, Key Chains always come into play. For every H-Fed application a user has a corresponding Key Chain with the credentials for that application. There are rare times when populating the Key Chains automatically is helpful/necessary, although this is not the only use case for the Key Chain CLI. Here are some other use cases that come to mind for the Key Chain CLI:
- Populating Users' Keychains for H-Fed Applications automatically
- Creating a "Snapshot" of Users' Keychains (This is not a backup, passwords are not exported)
- Migrate Users' Key Chains (If the user's Username has changed for some reason)
- Creating Usage Reports (Listing and counting configured H-Fed applications and Key Chains)
So let's try out the Key Chain CLI on a Windows Machine and a Linux Machine.
Key Chain CLI Prerequisites
There are a couple of prerequisites that are worth mentioning in order to successfully use the Key Chain CLI. Here is a small, and may not be comprehensive, list:
- The CLI needs to run against the IDR's management interface, not the portal interface
- This means the machine that is running the CLI needs to have access to the Management Interface of the IDR
- The CLI uses HTTPS to connect to the IDR
- The CLI requires Java version 1.7 or higher
Get the SDK Files
The Key Chain CLI is part of the SDK zip archive, you can download the SDK zip from RSA Via Access - Application Portal Integration API. After downloading the zip file, extract the contents to an easily accessible directory. I will refer to this as the SWS_SDK_HOME Directory.
Windows - Configure Environment Variables
In my testing I had Java 1.8:
C:\>java -version java version "1.8.0_66" Java(TM) SE Runtime Environment (build 1.8.0_66-b18) Java HotSpot(TM) Client VM (build 25.66-b18, mixed mode, sharing)
To ease the sourcing of the Environment variables I like to create a script. On my windows machine here is the script:
C:\>type c:\SWSSDK\key_cli.bat @echo off set SWS_SDK_HOME=C:\SWSSDK set PATH=%PATH%;%SWS_SDK_HOME%\bin set JAVA_HOME=C:\Program Files (x86)\Java\jre1.8.0_66 set SWS_KEYFILE=%SWS_SDK_HOME%\key.txt set SWS_SERVER=10.210.0.85 ::The SWS_SERVER is the management IP Address of the IDR
Now we can just run the following to set and confirm all the environment variables:
C:\>c:\SWSSDK\key_cli.bat C:\>set SWS SWS_KEYFILE=C:\SWSSDK\key.txt SWS_SDK_HOME=C:\SWSSDK SWS_SERVER=10.210.0.85
Lastly we can make sure the idr.cmd command is in your path (any commands are appended with .cmd by default so you don't have to type out the full command):
C:\>idr.cmd --version 10.0.0-SNAPSHOT
Linux - Configure Environment Variables
In my below example I will put the SWS_SDK_HOME directory under /tmp, but I would recommend installing it into a directory dedicated for software installs (ie, /usr/local or /opt). So let's create a dedicated folder for our testing:
me@admin:~>cd /tmp me@admin:/tmp>mkdir SWSSDK me@admin:/tmp>mv ~/SDSSDK.zip SWSSDK/. me@admin:/tmp>cd SWSSDK me@admin:/tmp/SWSSDK> unzip SWSSDK.zip
Now let's create a file to ease the setup of the environment variables let's call it /tmp/SWSSDK/keycli.sh. Here are the contents of the script:
#!/bin/bash export SWS_SDK_HOME=/tmp/SWSSDK export JAVA_HOME=/opt/jre export SWS_KEYFILE=/tmp/SWSSDK/key.txt export SWS_SERVER=10.210.0.85 #This should be the management IP Address for the IDR export PATH=/tmp/SWSSDK/bin:$PATH
After that's ready, you can source your script and your variables will be configured. Here is what you can run to source the setup script:
me@admin:/tmp/SWSSDK>. keycli.sh
Note: that there is a space between the "." and "keycli.sh"
After it's finished you can confirm that the environment variables are configured:
me@admin:~> env | grep -E "JAVA|SWS" SWS_SERVER=10.210.0.85 SWS_KEYFILE=/tmp/SWSSDK/.key SWS_SDK_HOME=/tmp/SWSSDK JAVA_HOME=/opt/jre
Create a Dedicated API user for the Key Chain CLI
Login into the RSA Via Access Console as a Customer Super Administrator and create another user with API functionality enabled (My Account > Administrators > Add an Administrator):
The Allowed Networks specifies the remote network that will be making the remote CLI calls (in my above example I allow the internal network 10.0.0.0/8). Don't forget to publish after creating the user (this will push the settings onto the IDR). Next we need to create the key.txt file and populate it with the Access ID and Access Key Values. We can run the following to create the key file:
# for Windows C:\> echo key=0da0fe339b202fb96b7f5317153f402c78a561bc/fabe1b20d2d47813d4131fe98c2a8b1ef064221f > c:\SWSSDK\key.txt # for Linux me@admin:~> echo "key=0da0fe339b202fb96b7f5317153f402c78a561bc/fabe1b20d2d47813d4131fe98c2a8b1ef064221f" > /tmp/SWSSDK/key.txt
The format of the file is the following:
key=<AccessID>/<AccessKey> #AccessID and AccessKey values can be found from RSA Via Access Console > My Account > Administrators > "Your_Designated_API_USER" -> Edit
Test KeyChain CLI Commands
As a quick test make sure the following commands work:
C:\>idr-describe-keychains Username Application Name Credentials -------------------------------------------------- karim Evernote username, password karim Sharepoint 2013 username, password karim Concur userid, password dave Evernote username, password dave Sharepoint 2013 username, password dave Concur userid, password dpeterson <none> <none> nancy Sharepoint 2013 username, password nancy Concur userid, password nancy Twitter username, password jason Evernote username, password jason Sharepoint 2013 username, password jason Concur userid, password
On Linux you can run the same:
me@admin:~> idr-describe-keychains Username Application Name Credentials ----------------------------------------------- Administrator <none> <none> devuser <none> <none> -----------------------------------------------
The above just shows the current Key Chains that are configured.
Import Key Chain Data Using a CSV File
If we need to batch import a bunch of H-Fed Credentials we can create a CSV file in the following format:
Username,Application Name,CredentialName1,CredentialValue1,CredentialName2,CredentialValue2 user1,app-1,username,user@application,password,my_password
To figure out the Application Name and Credential Names we can use the idr-describe-applications command. For example here is output from that command:
C:\>idr-describe-applications Application Name Portal URL Portal Text Enable Keychain Edit Credentials --------------------------------------------------------------------------------------------------------------- Concur https://aap1.pdn.com/portal.asp Concur true userid, password Evernote https://app2.pdn.com/Home.action Evernote true username, password Sharepoint 2013 http://app3.pdn.com/Home.aspx Sharepoint 2013 true username, password Twitter https://app4.pdn.com/ Twitter true username, password ----------------------------------------------------------------------------------------------------------------
So let's say I wanted to populate the Key Chain credentials for some users for the Sharepoint 2013 Application. I would then create a CSV file with the following contents:
me@admin:~> cat users.csv Username,Application Name,CredentialName1,CredentialValue1,CredentialName2,CredentialValue2 user1,Sharepoint 2013,username,user1@pdn.com,password,password1 user2,Sharepoint 2013,username,user2@pdn.com,password,password2 user3,Sharepoint 2013,username,user3@pdn.com,password,password3 user4,Sharepoint 2013,username,user4@pdn.com,password,password4 user5,Sharepoint 2013,username,user5@pdn.com,password,password5 user6,Sharepoint 2013,username,user6@pdn.com,password,password6 user7,Sharepoint 2013,username,user7@pdn.com,password,password7 user8,Sharepoint 2013,username,user8@pdn.com,password,password8
Then you can use the idr-update-keychains command to import that CSV file:
#Linux me@admin:~>idr-update-keychains -f users.csv A total of 8 keychains were updated. #Windows C:\>idr-update-keychains -f c:\SWSSDK\users.csv A total of 8 keychains were updated.
And you can confirm the Key Chain Data with the idr-describe-keychains command just like we did above.
Export User Key Chains as CSV
Another cool side note is that you can also export Key Chain Data as CSV but the password will not be available (they will be left blank):
C:\>idr-describe-keychains -f csv Username,Application Name,CredentialName1,CredentialValue1,CredentialName2,CredentialValue2 user1,Sharepoint 2013,username,user1@pdn.com,password,******** user2,Sharepoint 2013,username,user2@pdn.com,password,******** user3,Sharepoint 2013,username,user3@pdn.com,password,******** user4,Sharepoint 2013,username,user4@pdn.com,password,******** user5,Sharepoint 2013,username,user5@pdn.com,password,******** user6,Sharepoint 2013,username,user6@pdn.com,password,******** user7,Sharepoint 2013,username,user7@pdn.com,password,******** user8,Sharepoint 2013,username,user8@pdn.com,password,********
A full list of all the keychain CLI commands will be available soon and I will definitely link to it as soon as it's available.
