CHARON
All the security services are SOAP services. So they need a special runtime environment which probably is not present if you use HTTP GET/POST services only.
The main requirement to successfully deploy and run the security services is a web service engine for the SOAP stack. There are some implementations available and theoretically you could use any implementation you prefer and that supports XMLBeans, but at least the PEP and Proxy part of the security service implementation depends on some stack dependant API. This is inevitable. Hence it is required to use Apache Axis2 as SOAP stack. If you want to use another stack you have to reimplement some small but essential parts of the PEP and the Proxy/Proxy Generator.
Please note that you need at least a second instance of Apache Axis2 if your SOAP service to secure is already running on this stack. This is because the generated proxy service has the same WSDL file as the service it secures and it is not possible to run two services with the same WSDL in one Axis2 installation.
The security services need a backend to store the user data. Currently only a MySQL service backend implementation is available and so it is necessary to have a MySQL5 database running.
The AdministrationClient needs a Java Servlet Container such as Tomcat to be deployable.
Please install all required software. You can find documentation about the software on the corresponding sites and all over the web. Ensure that Axis2 is running with Java2 1.6 if you have multiple Java versions installed.
Due to some unpleasant Axis2 development EIG had to fix Axis2 bug 3191 to get services working. We did that for Axis2 version 1.4.1, so if you want to use another version, you will have to fix it for yourself (which is no big deal at all).
Once you have installed Axis2, locate the
${AXIS2_HOME}/WEB-INF/lib directory. Many jars should be located there. One of them is called 'axis2-kernel-1.4.1.jar'. Make sure Axis2 is not running and replace that jar with this one: axis2-kernel-1.4.1-AXIS-3191-fix_EIG.jar
NOTE: If you are running a Unix system remember to adjust the permissions of the file.
The deployment of the security services is rather easy. In general it is just creating a service database (if necessary), unpacking a zip file to the
${AXIS2_HOME}directory and then perform minimal editing of the configuration files. Overall procedure to create a new system is:
There is no need to follow this order but it is recommended to do so.
Have a look at the downloads page to find the binaries.
Download the SQL script corresponding to the service you want do deploy from the downloads page. Run the script corresponding to the service you want to deploy, but be aware that at first each of the scripts drops (!) the corresponding database if it exists and creates it again afterwards. It also creates a new user for the database. And certainly needed tables are installed, too. Here an overview of what will be created by default:
| Database name | Username | Password | |
|---|---|---|---|
| Identity Management and Authentication Service | identity_authen | identity_authen | identity_authen |
| Policy Management and Authorisation Service | policy_author | policy_author | policy_author |
| Profile Management Service | profile_management | profile_managemt | profile_management |
You may alter this values in the script as you please.
The IdentityAuthenService script also creates a new identity which is normally used for the first login with the AdministrationClient to initially set up the system:
First of all you have to put some libraries in the global Axis2 lib directory. Download the 'acs_xbeans.jar', the 'mysql-connector.jar' and the 'spring.jar' from the downloads page and put them in the
${AXIS2_HOME}/WEB-INF/libdirectory. The acs_xbeans.jar contains the Java classes representing the XML datatypes for all three AC services generated by XMLBeans.
HINT: If you (are planning to) have multiple web applications in this Tomcat installation it is recommended to place the mysql-connector in the Tomcat lib folder instead of the Axis2 lib folder to have one connector for all web applications.
After that you must remove the 'axis2-spring-1.4.1.jar' from the Axis2 lib folder.
Restart your Axis2 installation.
To deploy one of the services unpack the WEB-INF folder of the zip file to the
${AXIS2_HOME}directory. As there already is a WEB-INF folder you will have to merge the contents. NOTE: if you deploy a service again through merging the folders, be careful not to overwrite already existing configuration files, except you want to reset to the defaults again. After that locate the
${AXIS2_HOME}/WEB-INF/classes directory where you should see two "TODO files". They don't have any content but remind you of some of the steps you probably have to do to enable security for the service you are actually deploying. In addition to those steps you probably have to edit the service specific configuration file as well.
In the classes directory is a file called
PEPConfiguration_${SERVICE_NAME}.xmlThis file already contains a default configuration for a locally deployed service with an integrated PEP and locally deployed IdentityManagementAndAuthenticationService and PolicyManagementAndAuthorisationService. It also contains documentation of the elements of the configuration file. This in-file-documentation will help you understanding the single elements and their values.
The configuration of the integrated Proxy is even more easy. As you are about to configure an integrated version of the PEP the Proxy is secondary. It can be used to add some filters that are invoked during the authorisation process. As before there should be sufficient documentation within the configuration file.
To finish security configuration we will leave the classes directory for a moment and change to the
${AXIS2_HOME}/WEB-INF/conffolder. Open the axis2.xml file and search for the string Global Modules. There should be only one hit with the nearby element
<module ref="addressing"/>
Add another module element
<module ref="EIGSecurityHandler"/>
if it is not already present and save the file. So much for the "TODO files". Now we have to deal with the service configuration. Switch back to the
${AXIS2_HOME}/WEB-INF/classes folder again. There are two service configuration files. First one is the
${SERVICE_NAME}.propertiesfile which is only present for the service capabilities configuration. Open this file and alter the axisURL property to the URL where you are actually deploying the service. The other properties are self-explanatory and need not to be changed.
Second and more important file is the
${SERVICE_NAME}Config.xmlIt consists of a global configuration part and some service specific things. First of all change the value of the ServiceURI element within the Global element to the URL where you are actually deploying the service. The Authorisation element only contains a boolean flag which indicates whether the internal PEP shall be used or not. Change it as you please. After that search for the MySQLConnectorString element which is present in nearly every specific configuration block. This string will be used by the service to connect to the previously created service database. By default it points to a local database with service specific default values. Change it corresponding to your database settings.
The
IdentityAuthenServiceConfig.xml
contains one special element. It is the ValidityTime element within the <GeneralConfiguration> of the <AbstractSessionHandler>. Here you can adjust the validity time in minutes of the SAML assertions (or tickets) the services issues if a user logs in. Put a reasonable non-negative integer there.
Restart Axis2 and finally the services should be up and running.
PEP as a service means a dedicated SOAP services acts as PEP and can handle communication of multiple services. This means that there is only a single point of administration regarding the PEP.
A distribution of the PEP Service can be found at the downloads page. To deploy the PEP service just unpack the zip file to the
${AXIS2_HOME}folder. The
${AXIS2_HOME}/WEB-INF/classesdirectory contains the
PEPConfiguration.xml
file. The configuration file contains documentation about the single elements. This in-file-documentation will help you understand these elements and their values. When you finished editing restart Axis2 and the PEP should be up and running.