310 lines
10 KiB
Markdown
310 lines
10 KiB
Markdown
# soapClient
|
|
|
|
## What is soapClient?
|
|
|
|
soapClient.jar allows you to send data to a SOAP service using an XML template file and an input CSV file. The program reads a configuration file which defines different aspects of the program including:
|
|
|
|
<ul>
|
|
<li>SOAP Service URL</li>
|
|
<li>SOAP Service Username</li>
|
|
<li>SOAP Service Password</li>
|
|
<li>Does SOAP Service require authentication</li>
|
|
<li>Whether to use SSL</li>
|
|
<li>Java Keystore</li>
|
|
<li>Java Keystore Password</li>
|
|
<li>XML Template file</li>
|
|
<li>CSV Input File</li>
|
|
<li>Are empty CSV values allowed</li>
|
|
<li>Username format for authentication</li>
|
|
</ul>
|
|
|
|
## Command line parameters
|
|
|
|
### --key
|
|
This is the key (must be 16 characters) which is used to encrypt the password that is stored in the configuration file.
|
|
|
|
### --encrypt
|
|
This is the value to encrypt using the encryption key. You need to pass both <i>--key</i> and <i>--encrypt</i> in order to get a correct result.
|
|
|
|
### --props
|
|
This is the location of the properties file to be consumed by the program.
|
|
|
|
### --debug
|
|
This parameter takes no value and, if present, displays debug information on the screen. The debug information is <b>always</b> written to the debug.log file.
|
|
|
|
## Helper scripts
|
|
|
|
### linux_verify.sh
|
|
The bash script shown below can be used to verify the contents of the CSV input file.
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
|
|
JAVA=/usr/local/bin/java
|
|
$JAVA -cp lib/commons-codec-1.17.1.jar:lib/commons-csv-1.12.0.jar:lib/commons-io-2.18.0.jar:lib/jcommander-1.82.jar:lib/soapClient.jar com.belkast.soap.userVerify
|
|
```
|
|
|
|
### linux_runner.sh
|
|
The bash script shown below can be used to run the program.
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
|
|
JAVA=/usr/local/bin/java
|
|
$JAVA -cp lib/commons-codec-1.17.1.jar:lib/commons-csv-1.12.0.jar:lib/commons-io-2.18.0.jar:lib/jcommander-1.82.jar:lib/soapClient.jar com.belkast.soap.webService "$@"
|
|
```
|
|
|
|
## Program components
|
|
|
|
Do not forget to include the following four JAR files as dependencies when building the soapClient.jar.
|
|
|
|
<ul>
|
|
<li><a href="https://repo1.maven.org/maven2/org/apache/commons/commons-csv/1.12.0/commons-csv-1.12.0.jar">commons-csv-1.12.0.jar</a></li>
|
|
<li><a href="https://repo1.maven.org/maven2/com/beust/jcommander/1.82/jcommander-1.82.jar">jcommander-1.82.jar</a></li>
|
|
<li><a href="https://repo1.maven.org/maven2/commons-codec/commons-codec/1.17.1/commons-codec-1.17.1.jar">commons-codec-1.17.1.jar</a></li>
|
|
<li><a href="https://repo1.maven.org/maven2/commons-io/commons-io/2.18.0/commons-io-2.18.0.jar">commons-io-2.18.0.jar</a></li>
|
|
</ul>
|
|
|
|
### Configuration file
|
|
|
|
This is the main file containing the settings used by the program, and one with settings similar to those shown below is all you need to get started.
|
|
|
|
```toml
|
|
SHIM_URL = https://test.mycompany.com:8443/IDMProv/role/service
|
|
USERNAME = cn=keitha,ou=active,ou=users,o=belkast
|
|
PASSWORD = PT9TKHwFgJCxATJtAAMtMwtIF0UjFal6fo5riBN+ExY=
|
|
AUTH_REQUIRED = true
|
|
SSL = true
|
|
JAVA_KS_LOCATION = ldap.keystore
|
|
JAVA_KS_PASSWORD = changeit
|
|
XML_FILE = USER_TO_ROLE.xml
|
|
CSV_FILE = msalah.csv
|
|
CSV_ALLOW_EMPTY_COLUMN_VALUES = true
|
|
USERNAME_FORMAT = (cn=.+?),ou=Active,ou=Users,o=Belkast
|
|
```
|
|
|
|
### Default values
|
|
|
|
The settings listed below are not required to be included in the configuration file. If not present, they will be assigned the default values shown below.
|
|
|
|
<ul>
|
|
<li>AUTH_REQUIRED : true</li>
|
|
<li>SSL : true</li>
|
|
<li>CSV_ALLOW_EMPTY_COLUMN_VALUES : false</li>
|
|
<li>USERNAME_FORMAT : ^.+$</li>
|
|
</ul>
|
|
|
|
### Username and Password
|
|
|
|
If the configuration file specifies that authentication to the SOAP Service is required, and either the USERNAME or PASSWORD is not specified, you will be asked to enter the missing values.
|
|
|
|
```zsh
|
|
Please enter a username [ (cn=.+?),ou=Active,ou=Users,o=Belkast ] :
|
|
Please enter your password :
|
|
```
|
|
|
|
### XML template file
|
|
|
|
This is the XML file that is sent to the SOAP service once all search and replace tokens have been processed.
|
|
|
|
```xml
|
|
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://www.novell.com/role/service">
|
|
<soapenv:Header/>
|
|
<soapenv:Body>
|
|
<ser:requestRolesAssignmentRequest>
|
|
<!--Optional:-->
|
|
<ser:assignRequest>
|
|
<ser:actionType>grant</ser:actionType>
|
|
<ser:assignmentType>USER_TO_ROLE</ser:assignmentType>
|
|
<ser:identity>USER_DN</ser:identity>
|
|
<ser:reason>DESC</ser:reason>
|
|
<ser:roles>
|
|
<!--Zero or more repetitions:-->
|
|
<ser:dnstring>
|
|
<ser:dn>ROLE_DN</ser:dn>
|
|
</ser:dnstring>
|
|
</ser:roles>
|
|
</ser:assignRequest>
|
|
</ser:requestRolesAssignmentRequest>
|
|
</soapenv:Body>
|
|
</soapenv:Envelope>
|
|
```
|
|
|
|
### Java keystore
|
|
|
|
If the SOAP service uses <b>https</b> you have one of two options when choosing which keystore to use:
|
|
<ul>
|
|
<li>Use a local keystore, which must be specified in the configuration file and must contain all necessary certificates</li>
|
|
<li>Use the systemwide JRE or JDK keystore. Once again, this must contain all necessary certificates</li>
|
|
</ul>
|
|
|
|
|
|
## Encrypt a password
|
|
|
|
To encrypt a password, run the <i>linux_runner.sh</i> bash script as shown below.
|
|
|
|
```zsh
|
|
./linux_runner.sh --key 420CondoCondo420 --encrypt Password123
|
|
|
|
Clear Text Password : Password123
|
|
Encryption Key : 420CondoCondo420
|
|
Encrypted / Encoded : PT9TKHwFgJCxATJtAAMtMwtIF0UjFal6fo5riBN+ExY=
|
|
Decoded / Decrypted : Password123
|
|
```
|
|
|
|
## Verification of the CSV input file
|
|
|
|
To verify the CSV input file, run the <i>linux_verify.sh</i> bash script as shown below.
|
|
|
|
```zsh
|
|
./linux_verify.sh
|
|
```
|
|
|
|
Assume we want to process the CSV input file, <i>msalah.csv</i>, shown below.
|
|
|
|
```text
|
|
USER_DN,ROLE_DN,DESC
|
|
"cn=msalah,ou=admins,o=belkast","cn=TestRole,o=belkast","Test Load"
|
|
```
|
|
|
|
Running the <i>linux_verify.sh</i> bash script would result in the following output.
|
|
|
|
```zsh
|
|
./linux_verify.sh
|
|
|
|
Please enter the name of the CSV file to verify : msalah.csv
|
|
Block on empty column values (Y/n) : Y
|
|
|
|
CSV input file : msalah.csv
|
|
CSV block on empty : true
|
|
CSV header tokens : USER_DN,ROLE_DN,DESC
|
|
|
|
## 2 [passed]
|
|
|
|
CSV lines read : 1
|
|
CSV lines passed : 1
|
|
CSV lines failed : 0
|
|
|
|
record 1 key : USER_DN
|
|
record 1 val : cn=msalah,ou=admins,o=belkast
|
|
record 1 key : ROLE_DN
|
|
record 1 val : cn=TestRole,o=belkast
|
|
record 1 key : DESC
|
|
record 1 val : Test Load
|
|
|
|
CSV file records : 1
|
|
CSV file is valid : true
|
|
```
|
|
|
|
If we had a second line with a missing DESC value, the program would return an error as shown below.
|
|
|
|
```zsh
|
|
...
|
|
USER_DN,ROLE_DN,DESC
|
|
"cn=msalah,ou=admins,o=belkast","cn=TestRole,o=belkast","Test Load 1"
|
|
"cn=msalah,ou=admins,o=belkast","cn=TestRole,o=belkast",""
|
|
|
|
## line 2 [passed]
|
|
!! line 3 [failed] : the DESC token value is empty
|
|
!! line 3 [failed] : "cn=msalah,ou=admins,o=belkast","cn=TestRole,o=belkast",""
|
|
!! line 3 [failed] : {DESC=, ROLE_DN=cn=TestRole,o=belkast, USER_DN=cn=msalah,ou=admins,o=belkast}
|
|
|
|
CSV lines read : 2
|
|
CSV lines passed : 1
|
|
CSV lines failed : 1
|
|
|
|
CSV file records : 0
|
|
CSV file is valid : false
|
|
```
|
|
|
|
## Example usage
|
|
|
|
To run the program, just run the <i>linux_runner.sh</i> bash script shown at the beginning of this README.
|
|
|
|
### Getting Help
|
|
|
|
If you run the <i>linux_runner.sh</i> bash script with no command line parameters, you will receive a help screen as shown below.
|
|
|
|
```zsh
|
|
./linux_runner.sh
|
|
|
|
Usage: <main class> [options]
|
|
Options:
|
|
--debug
|
|
Display debug information on the screen (no value required)
|
|
Default: false
|
|
--encrypt
|
|
Value to encrypt using the encryption key
|
|
--key
|
|
Encryption key (must be 16 characters)
|
|
--props
|
|
Location of the properties file
|
|
```
|
|
|
|
### With command line parameters
|
|
|
|
Please note that if the <i>--key</i> command line parameter and the <i>--encrypt</i> command line parameter are specified, the program will encrypt the passed value and exit.
|
|
|
|
The program checks for the following potential issues before sending the SOAP XML to the SOAP service:
|
|
|
|
<ul>
|
|
<li>The <i>--key</i> command line parameter is specified:</li>
|
|
<ul>
|
|
<li>If specified, it must have a length of 16 characters</li>
|
|
<li>If NOT specified, you will be asked to enter it</li>
|
|
</ul>
|
|
<li>The <i>--props</i> command line parameter is specified:</li>
|
|
<ul>
|
|
<li>If specified, there is a check to make sure that the file exists</li>
|
|
</ul>
|
|
<li>If configured, check that the encrypted password can be decrypted</li>
|
|
<li>The CSV input file must exist</li>
|
|
<li>The XML template file must exist</li>
|
|
</ul>
|
|
|
|
A simple example is shown below.
|
|
```zsh
|
|
./linux_runner.sh --debug true --key 420CondoCondo420 --props props_USER_TO_ROLE.conf
|
|
|
|
props_USER_TO_ROLE.conf => SOAP URL : https://test.mycompany.com:8443/IDMProv/role/service
|
|
props_USER_TO_ROLE.conf => Username : cn=keitha,ou=active,ou=users,o=belkast
|
|
props_USER_TO_ROLE.conf => Use SSL : true
|
|
props_USER_TO_ROLE.conf => JAVA Keystore : ldap.keystore
|
|
props_USER_TO_ROLE.conf => JAVA Keystore password : changeit
|
|
props_USER_TO_ROLE.conf => Input File : msalah.csv
|
|
props_USER_TO_ROLE.conf => XML File : USER_TO_ROLE.xml
|
|
msalah.csv : CSV file is valid : true
|
|
msalah.csv : records to process : 1
|
|
Processing record 1
|
|
Record 1 : [cn=msalah,ou=admins,o=belkast, cn=TestRole,o=belkast, Test Load]
|
|
Record 1 : USER_DN => cn=msalah,ou=admins,o=belkast
|
|
Record 1 : ROLE_DN => cn=TestRole,o=belkast
|
|
Record 1 : DESC => Test Load
|
|
```
|
|
|
|
For each of the lines in the input CSV file, the corresponding XML data is sent to the SOAP service. The XML data shown below is the data that is sent for our particular example. Notice that the tokens have been replaced with the data from the corresponding line in the CSV input file.
|
|
|
|
```xml
|
|
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://www.novell.com/role/service">
|
|
<soapenv:Header/>
|
|
<soapenv:Body>
|
|
<ser:requestRolesAssignmentRequest>
|
|
<!--Optional:-->
|
|
<ser:assignRequest>
|
|
<ser:actionType>grant</ser:actionType>
|
|
<ser:assignmentType>USER_TO_ROLE</ser:assignmentType>
|
|
<ser:identity>cn=msalah,ou=admins,o=belkast</ser:identity>
|
|
<ser:reason>Test Load</ser:reason>
|
|
<ser:roles>
|
|
<!--Zero or more repetitions:-->
|
|
<ser:dnstring>
|
|
<ser:dn>cn=TestRole,o=belkast</ser:dn>
|
|
</ser:dnstring>
|
|
</ser:roles>
|
|
</ser:assignRequest>
|
|
</ser:requestRolesAssignmentRequest>
|
|
</soapenv:Body></soapenv:Envelope>
|
|
```
|
|
|
|
If you require any additional assistance, or you have any enhancement requests, please get in touch by visiting the <a href="https://www.belkast.com">Belkast Consulting</a> website.
|