diff --git a/README.md b/README.md new file mode 100644 index 0000000..45984a1 --- /dev/null +++ b/README.md @@ -0,0 +1,237 @@ +# callSoap + +## What is callSoap? + +callSoap allows you to send data to a SOAP service using an XML template file and an input CSV file. The program takes a configuration file which defines different aspects of the program including: + + + +## Command line parameters + +### --key +This is the 16 character length key 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 --key and --encrypt in order to get a correct result. +◊ +### --props +This is the location of the properties file to be consumed by the program. + +### --debug +This is a true / false flag which specifies if the debug information is displayed on the screen. The debug information is always written to the debug.log file. + +## Helper scripts + +### linux_runner.sh +The bash script listed below can be used to run the program. + +```bash +#!/bin/bash + +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_verify.sh +The bash script shown below can be used to verify the contents of the CSV input file. + +```bash +#!/bin/bash + +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 program. + +I use IDEA IntelliJ Community Ediiton when writing JAVA code. + + + +### Configuration file +A file similar to the one shown below is all you need to get started. + +```toml +SHIM_URL = https://test.mycompany.com:8443/IDMProv/role/service +PASSWORD = PT9TKHwFgJCxATJtAAMtMwtIF0UjFal6fo5riBN+ExY= +USERNAME = cn=keitha,ou=active,ou=users,o=belkast +XML_FILE = USER_TO_ROLE.xml +INPUT_FILE = msalah.csv +USE_SSL = true +JAVA_KS_LOCATION = ldap.keystore +JAVA_KS_PASSWORD = changeit +``` + +### XML template file + +```xml + + + + + + + grant + USER_TO_ROLE + USER_DN + DESC + + + + ROLE_DN + + + + + + +``` + +### Java keystore +If the SOAP service uses https you have one of two choices for keystore: + + + +## Encrypt a password +To encrypt a password, run the linux_runner.sh 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 linux_verify.sh bash script as shown below. + +```zsh +./linux_verify.sh +``` + +Assume we have the CSV input file, msalah.csv, below. + +```text +USER_DN,ROLE_DN,DESC +"cn=msalah,ou=admins,o=belkast","cn=TestRole,o=belkast","Test Load" +``` + +Running the linux_verify.sh bash script would result in the following output. + +```zsh +./linux_verify.sh + +Please enter the name of the CSV file to verify : msalah.csv + +CSV input file : msalah.csv +CSV token count : 3 +CSV token list : 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 +``` + +## Example usage + +To run the program, just run the linux_runner.sh bash script shown at the beginning of this README. + +### Getting Help +If you run the linux_runner.sh bash script with no command line parameters, you will receive a help screen. + +```zsh +keiarm@US09MAC769Q60KJ TEST % ./linux_runner.sh + +Usage:
[options] + Options: + --debug + Display debug information on the screen (true/false) + --encrypt + Value to encrypt using the Encryption Key + * --key + Encryption Key (must be 16 characters in length) + --props + Location of the properties file +``` + +### With Parameters + +The program checks the for the following potential issues before sending the SOAP document to the SOAP service: + + +```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 +``` + +Once the CSV file is processed, the data is sent to the SOAP service. The XML file below is the file that is sent for our example. Notice that the tokens have been replaced with the data from the CSV file. + +```xml + + + + + + + grant + USER_TO_ROLE + cn=msalah,ou=admins,o=belkast + Test Load + + + + cn=TestRole,o=belkast + + + + + +``` \ No newline at end of file