Karim Elatov

Using the RSA SecurID Access Key Chain Command Line Interface (CLI)

Blog Post created by Karim Elatov Employee on Dec 21, 2015

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)

java-version-windows.png

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):

api-admin-user.png

 

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.

Outcomes