Overview of using the Linux curl command to interact with the Web Services API in RSA Identity Governance & Lifecycle
Originally Published: 2016-06-15
Article Number
Applies To
RSA Version/Condition: 7.0.x, 7.1.x, 7.2.x
Issue
Resolution
To enable Web Services:
- Login to the RSA Identity Governance & Lifecycle user interface.
- Navigate to Admin > Web Services
- On the Web Services page click Edit and change the Web Services Interface from Off to On.
- 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.
- Click OK when done.
- 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.
- 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.
-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.
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.
- 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
- 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
- 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.)
- 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
Notes
| Port | Use |
| 21 | FTP connections. Can be used to transfer collection data |
| 22 | SSH connections |
| 1158 | Oracle ENterprise Manager Express |
| 1555 | Oracle Listener for the AVDB data source |
| 8443 | Secure connection (using Secure Sockets Layer (SSL) and secure cookies) |
| 8444 | Secure communication between the RSA Identity Governance & Lifecycle application server and external components such as the remote agent and AFX. |
| 8080 | Internal 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. |
curl -v http://localhost:8080 curl -v https://localhost:8443 curl -v https://localhost:8444
Alternatively you may use the Fully Qualified Domain Name:
curl -v http://myhost.mydomain.com:8080 curl -v https://myhost.mydomain.com:8443 curl -v https://myhost.mydomain.com:8444
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.
