000033343 - Overview of using the Linux curl command to interact with the Web Services API in RSA Identity Governance & Lifecycle

Document created by RSA Customer Support Employee on Jun 17, 2016Last modified by RSA Customer Support on Mar 31, 2020
Version 4Show Document
  • View in full screen mode

Article Content

Article Number000033343
Applies ToRSA Product Set: RSA Identity Governance & Lifecycle 
RSA Version/Condition: 7.0.x, 7.1.x, 7.2.x
 
IssueThis article gives an overview of using the Linux curl command to interact with the RSA Identity Governance & Lifecycle Web Services API.
 
ResolutionBy default Web Services is not enabled in RSA Identity Governance & Lifecycle. 

To enable Web Services:
  1. Login to the RSA Identity Governance & Lifecycle user interface.
  2. Navigate to Admin > Web Services

User-added image


  1. On the Web Services page click Edit and change the Web Services Interface from Off to On.
  2. By default the server only allows connections from itself (127.0.0.1).  You can either add additional hosts or clear the loopback IP address to allow any host while you are testing.
  3. Click OK when done.

User-added image

 

  1. Now that Web Services is enabled here is a sample of logging in, obtaining an authentication token, and providing that token to execute an authenticated command.
    1. First open an SSH session to the RSA Identity Governance & Lifecycle server and authenticate as a user with the command below (note that the command should be entered on one line). Execute this command as the root user.



curl -k -H "Content-Type: application/xml" -X POST -d '<username>AveksaAdmin</username><password>actualpassword</password>'
"https://127.0.0.1:8443/aveksa/command.submit?cmd=loginUser"



  • Here is a breakdown of the above command:

curl is the Linux command
-k / --insecure, this option tells the curl command not to validate the certificate chain presented.  
If you wanted, you could export RSA Identity Governance & Lifecycle's self-signed certificate or your replacement certificate hierarchy as individual PEM files in a folder and leverage the curl command's --capath option to enable certificate validation.
-H, this option defines the header that is being passed to Web Services. In the above example we are identifying our traffic to Web Services as being of type application/xml.
-X, this option defines what request command is being passed. (GET/POST/PUT/DELETE).
-d, this option is the data that is being sent.
<username> </username> In between these tags is the User that is authenticating.
<password> </password> In between these tags is the password that is associated with the user.  Note that both username and password tags are case sensitive.


  • Here is a breakdown of the URL appended to the command:



https or http can be used,  if using http, the server must be configured to allow non-secure connections.
127.0.0.1, this is the server to which the connection is made.
:8443, this is the default port used for the JBoss/Wildfly application servers. This port should be the same port that the Administrative Web Interface is using.
/aveksa/command.submit?cmd=, this is the prefix for all commands that will be passed and is the target that parses the commands.
loginUser, this is the actual Web Services call/command that is being performed.


  • Note that the Admin > Web Services > Admin tab provides full information for each command and a description of what arguments that are required.
  • Note that for some Web Services commands, the <username> passed in the command is important.  If createChangeRequest is called for example, this will be the username of the user that generates the change request. 
  • If Security is enabled for the Web Service command, the user used for authentication must be allowed to make the Web Services request. 

  1. Here is the command again with output returned (again, the command should be entered on one line):



curl -k -H "Content-Type: application/xml" -X POST -d '<username>AveksaAdmin</username><password>actualpassword</password>'
"https://127.0.0.1:8443/aveksa/command.submit?cmd=loginUser"

token=ws3137f59972b7c7967f:-12d86acf:154bb48bc96:-7fd40.19157109468220368



  1. The token value returned above is then used to run an authenticated command getSecuritySettings.  This example passes the token as a authorization bearer header.  (Note the keyword token is not used).



curl -k -H "Content-Type: application/xml" -H
"Authorization: Bearer ws3137f59972b7c7967f:-12d86acf:154bb48bc96:-7fd40.19157109468220368" -X POST
"https://127.0.0.1:8443/aveksa/command.submit? cmd=getSecuritySettings"

allow-username-save=false token-lifespan-timeout=120 token-inactivity-timeout=10


  1. Alternatively (deprecated) the token can be passed as part of the query string as in this example.


curl -k -H "Content-Type: application/xml" -X POST
"https://127.0.0.1:8443/aveksa/command.submit?
cmd=getSecuritySettings&token=ws3137f59972b7c7967f:-12d86acf:154bb48bc96:-7fd40.19157109468220368"
allow-username-save=false token-lifespan-timeout=120 token-inactivity-timeout=10



  • The -d data option is omitted as username and password are not required because we are now leveraging the token that was returned.  We can continue to use the token until it expires. We can also use a keepAlive Web Services call to reset the inactivity timeout if needed.
  • The loginUser was replaced with getSecuritySettings.  An & is added after the command and the full token=<value> is appended to the URL with a closing quote at the end.
  • The result of the above query returns the user defined security settings for Web Services (whether saving the username is allowed, the token lifespan/absolute timeout, and the token idle/inactivity timeout.)

  1. Here is an additional example of a command that is documented within Web Services:



curl -k -H "Content-Type: application/xml" -X POST "https://127.0.0.1:8443/aveksa/command.submit?
cmd=findUsers&returnColumns=id,user_id&&token=ws3137f59972b7c7967f:-12d86acf:154bb48bc96:-7fd40.19157109468220368"
id=0 user_id=AveksaAdmin



 
NotesAnother use of the curl command with RSA Identity Governance & Lifecycle is to check if the required ports are available. Starting in RSA Identity Governance & Lifecycle 7.0 and above, the required ports for RSA Identity Governance & Lifecycle are:
 

PortUse
21FTP connections.  Can be used to transfer collection data
22SSH connections
1158Oracle ENterprise Manager Express
1555Oracle Listener for the AVDB data source
8443Secure connection (using Secure Sockets Layer (SSL) and secure cookies)
8444Secure communication between the RSA Identity Governance & Lifecycle application server and external components such as the remote agent and AFX.
8080Internal communication.  You might need to configure this port then RSA Identity Governance & Lifecycle is installed on WebLogiv or WebSphere.  For more information, see Configuring Non-SSL Port Assignments for WebLogic or Configuring Non-SSL Port Assignments for WebSphere.


Examples of how you may use the curl command to check port availability are:



Alternatively you may use the Fully Qualified Domain Name:




From the curl man page:


curl is a tool to transfer data from or to a server, using one of the supported protocols (DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET and TFTP). The command is designed to work without user interaction.



curl offers a busload of useful tricks like proxy support, user authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer resume, Metalink, and more. 

Attachments

    Outcomes