Revision History
This DocumentThis document provides installation operation instructions for the Applications which are included in the Project OpenPTK. The OpenPTK is used to build custom end-user provisioning interfaces that leverage commercial user provisioning solutions. OverviewProject Open Provisioning ToolKit (OpenPTK) is an open source User Provisioning Toolkit which exposes API's, Web Services, HTML Taglibs, and JSR-168 Portlets with user registration, self-service, and administration examples.
This document describes the installation, configuration and operation of each of the sample applications which are available with the OpenPTK. This guide is intended for users of the OpenPTK sample applications and does not require any development expertise. Deploying and configuring these sample applications does require an understanding of java applications, application servers, and portal servers. The OpenPTK sample applications which are described in this document are:
The sample applications are configured by default to connect to a hosted instance of Sun Identity Manager using Service Provisioning Markup Language (SPML). The OpenPTK framework uses a configuration file (openptk.xml). This file can be modified to connect to alternatice services including locally deployed services, if desired. See Appendix A for the instructions to configure the openptk.xml file to point to a different instance of Sun Identity Manager. The OpenPTK also inclues services for JNDI, JDBC and alternative SPML services, see Appendix A for configuration information. OpenPTK Access InstructionsProject OpenPTK is an open source project which is publically available. Access instructions can be found at: OpenPTK Download. The Applications described in this guide can either be built using the and build process or they can be downloaded in binary form for use. In order to use the application which are included in the OpenPTK downloads, a provisioning infrastructure must be available. The setup instructions of the services which are used by the OpenPT are described in the Appendicies of this document. The supporting files which are used to setup these services can be obtained from the download page: openptk-external-files.zip. OpenPTK Applications Installation InstructionsDescriptionThe CLI scripts currently operate on unix, linux, and Mac OS operating systems. Command Line Interface (CLI) InstallationUnzip the cli file (openptk-cli-1.1.0.zip). It will create an openptk-cli-1.1.0 directory. To verify that the CLI is operational and display the help text: # cd openptk-cli-1.1.0 # bin/ptk -h To configure the OpenPTK framework, edit the: <install-root>/openptk-cli-1.1.0/lib/openptk.xml The default context used by the application is defined in this file to use SPML. <Contexts default="Person-SPML-Sun" logger="UnixLogFile" debug="4" audit="false" timestamp="true"> For complete OpenPTK Framework configuration instructions see Appendix A. OpenPTK User Management Lite (UML) InstallationDescriptionA Java Application Server which support a J2EE servlet/jsp container is required to deploy the UML. The tested application servers include:
Obtain the openptk-uml-1.1.0.war file and save to a temporary location. Deploy the UML war file:The following example shows how to use the glassfish cli to deploy the User Management Lite sample applications: <GLASSFISH_HOME>/bin/asadmin deploy --host localhost --port 4848 --user admin --contextroot /UML --precompilejsp=false --verify=false --name "User-Management-Lite-v1.1" --enabled=true openptk-uml-1.1.0.war Once deployed the application is accessible at (the context root used in this example is /UML): http://<server>:<port>/UML To configure the OpenPTK framework used by the UML application, edit the included openptk.xml file: <install-root>/User-Management-Lite-v1.1/WEB-INF/classes/openptk.xml
The default context used by the application is defined in this file to use SPML. <Contexts default="Person-SPML-Sun" logger="UnixLogFile" debug="4" audit="false" timestamp="true"> Restart the Application Server if this configuration file is modified. For complete OpenPTK Framework configuration instructions see Appendix A. WSDL-based Web Service InstallationDescriptionA Java Application Server which support a J2EE servlet/jsp container is required to deploy the web service. The tested application servers include:
Place the openptk-apps-webservicewsdl-1.1.0.war file to a temporary location Deploy Provision Web Service to glassfish command:<GLASSFISH_HOME>/bin/asadmin deploy --host localhost --port 4848 --user admin --contextroot /ProvisionWebService --precompilejsp=false --verify=false --name "Provision-Web-Service-v1.1" --enabled=true openptk-apps-webservicewsdl-1.1.0.war The Web Application which the web service was deployed on is now accessible at: http://<server>:<port>/ProvisionWebService/
Once it is deployed, the WSDL for this web service can be found at the following location: http://<server>:<port>/ProvisionWebService/ProvisionPerson?wsdl
To configure the OpenPTK framework used by the UML application, edit the included openptk.xml file: <install-root>/ProvisionWebService/WEB-INF/classes/openptk.xml
The default context used by the application is defined in this file to use SPML. <Contexts default="Person-SPML-Sun" logger="UnixLogFile" debug="4" audit="false" timestamp="true"> Restart the Application Server if this configuration file is modified. For complete OpenPTK Framework configuration instructions see Appendix A. Provisioning Portlets (JSR-168) InstallationDescriptionA portal server which supports JSR-168 and a Java Application Server which support a J2EE servlet/jsp container is required to deploy the sample portlets. The tested portal / application servers include:
Deploy the downloaded openptk-portlets war file into your Portlet container, using the deployment instructions from your chosen server. For simplicity, the recommended context root to use is: /ProvPortlets. Configure the portlets to appear on the portal desktop. Install the portlets on Jetspeed v2.1:
Deploy openptk portlets on Jetspeed v2.1:If there are no existing portlets you do not need to stop/restart jetspeed in order to deploy--just copy the war file to the deploy directory. If there are older copies of the portlets installed then follow the instructions below to remove them. Deploy portlet by copying the .war file to the Jetspeed deploy directory: cp openptk-portlets-1.1.0.war <Jetspeed-2.1.2-install>/webapps/jetspeed/WEB-INF/deploy Configuring the PortletsIn order to make the Provisioning portlets appear by default on the default jetspeed portal, the .psml files in the openptk must be deployed. These files are included in the openptk subversion tree (found in the ext/Apache/JetSpeed/psml_samples) <Jetspeed-2.1.2-install>/webapps/jetspeed/WEB-INF/pages These .psml files reference the webapp name used to deploy the portlets. If a context root for the portlets used id not ProvPortlets, these sample .psml files must be modified. <fragment id="dp-19" type="portlet" name="ProvPortlets::SelfService"> <property layout="TwoColumns" name="row" value="1" /> <property layout="TwoColumns" name="column" value="0" /> </fragment> <fragment id="dp-20" type="portlet" name="ProvPortlets::UserAdmin"> <property layout="TwoColumns" name="row" value="2" /> <property layout="TwoColumns" name="column" value="0" /> </fragment> To configure the OpenPTK framework used by the UML application, edit the included openptk.xml file: <Jetspeed-2.1.2-install>/webapps/ProvPortlet/WEB-INF/classes/openptk.xml The default context used by the application is defined in this file to use SPML. <Contexts default="Person-SPML-Sun" logger="UnixLogFile" debug="4" audit="false" timestamp="true"> Restart the Application Server if this configuration file is modified. For complete OpenPTK Framework configuration instructions see Appendix A. Install the portlets on Liferay:
OpenPTK Applications Operator InstructionsCommand Line Interface (CLI)DescriptionThe OpenPTK command line interface provides the ability to perform provisioning operations on a remote machine from the command line. The samples will connect to a hosted server by default. Appendix A describes how to configure the OpenPTK framework differently. Authentication and AuthorizationAuthentication is not required in this release of the cli. It is expected to be added to the next release. For this reason, the command line should be protected at the operating system in order to prevent unauthorized users from using it. Authorization is provided by limiting the capabilities of the administrative proxy account which is used to connect to the service. Installation and Operation For Unix/MacOSThe OpenPTK command line sample can be obtained from: Project OpenPTK. Unzip the downloaded file (openptk-cli-1.0.0.zip). It will create an openptk-cli-1.0.0 sub-directory. Then the read option can be used to obtain details regarding a subject: OpenPTK Command Line Provisioning ExamplesThe following examples show how to use the openPTK command line. These examples demonstrate how to use the different contexts in the OpenPTK both Identity Manager users and Identity Manager Service Provider Editions Users (IDMX). # cd <install-root>/openptk-cli-1.1.0/bin ./ptk create -u tuser1 -a firstname=Test,lastname=User1 ./ptk search ./ptk search -q firstname=Test ./ptk read -u tuser1 -r firstname,lastname,email ./ptk update -u tuser1 -a email=test.user1@test.com ./ptk delete -u tuser1 ./ptk config list-all Use the Context option to specify the SPML service: ./ptk create -u tuser1 -a firstname=Test,lastname=User1 -C Person-SPML-Sun ./ptk update -u tuser1 -a lastname=testing -C Person-SPML-Sun ./ptk search -C Person-SPML-Sun ./ptk read -u tuser1 -r firstname,lastname,email -C Person-SPML-Sun ./ptk delete -u tuser1 -C Person-SPML-Sun Use the Context option to specify the SPML SPE service: ./ptk create -u tuser1 -a firstname=Test,lastname=User1 -C Person-SPML-Sun-SPE ./ptk update -u tuser1 -a lastname=testing -C Person-SPML-Sun-SPE ./ptk search -C Person-SPML-Sun-SPE -q lastname=Test ./ptk read -u tuser1 -r firstname,lastname,email -C Person-SPML-Sun-SPE ./ptk delete -u tuser1 -C Person-SPML-Sun-SPE Use the Context option to specify the JNDI service: ./ptk create -u tuser1 -a firstname=Test,lastname=User1 -C Person-JNDI ./ptk update -u tuser1 -a lastname=testing -C Person-JNDI ./ptk search -C Person-JNDI -q lastname=Test ./ptk read -u tuser1 -r firstname,lastname,email -C Person-JNDI ./ptk delete -u tuser1 -C Person-JNDI Use the Context option to specify the JDBC service: ./ptk create -u tuser1 -a firstname=Test,lastname=User1 -C Person-JDBC-MySQL ./ptk update -u tuser1 -a lastname=testing -C Person-JDBC-MySQL ./ptk search -C Person-JDBC-MySQL -q lastname=Test ./ptk read -u tuser1 -r firstname,lastname,email -C Person-JDBC-MySQL ./ptk delete -u tuser1 -C Person-JDBC-MySQL OpenPTK User Management Lite (UML)DescriptionThe OpenPTK User Management Lite (UML) was designed to showcase user provisioning and self service functions. It is a sample application that uses the OpenPTK's provisioning tag library to provide a simple way to add user provisioning services to a java application. As described in the Overview section of this document, the samples will connect to a hosted server by default. Appendix A describes how to configure the OpenPTK framework differently. To access the User Management Lite (UML) application, browse to the deployed http://<server>:<port>/UML Authentication and AuthorizationAuthentication and Authorization are necessary for a complete solution deployment. The UML provides an interface for user authentication. The UML was designed to be protected by a web single signon infrastructure like Sun Acccess Manager or OpenSSO. If a web single signon infrastructure is not configured with the UML, it provides simulated authentication screens to enable the sample application's features to be used. In a real world deployment, it is expected that the authentication will be implemented in many different ways and is out of scope of the core OpenPTK framework features. The instructions below describe the steps to protect the UML application with OpenSSO. The same steps would be required with Sun Access Manager or another web single signon infrastructure. Configuring OpenSSO to protect the OpenPTK User Management Lite (UML)
Authorization is provided by limiting the capabilities of the administrative proxy account which is used to connect to the service. The SPML configuration instructions for the default service by can be found in Appendix B. OperationThe User Management Lite sample application provides 3 separate interfaces (User Administration, Self Service, Change Password) to demonstrate different operations of the OpenPTK framework. They all use the OpenPTK java tab library (taglib). User Administration
User Registration and Self ServiceThis scenario demonstrates a new user registration through a sample custom application which uses SPML for user registration. The user is also validated during the registration process. UML Customer Registration Instructions
UML Context ConfigurationThe OpnePTK contet used by the UML can be modified at runtime to test the OpenPTK services. Select the http://www.openptk.com/UML/anon/index.jsp?mode=config
link in the upper right corner of the UML application to change the context. The Context Name can be changed to one of the values available in the openptk.xml file, for example the default openptk.xml file defines these contexts:
The active Configuration file can be set and the debug information can also be turned on here. Select Set. WSDL-based Web ServiceDescriptionThe OpenPTK Provisioning Web Service provides the ability to perform provisioning using a JAX-RPC web service. The OpenPTK Provisioning Web Service currently supports user create, update, delete, change password, and reset password operations. As described in the Overview section of this document. Appendix A describes how to configure the OpenPTK framewor. In this release (v1.1), the Web Service is designed to handle user subjects. Other subject types like Roles will be considered for the next release. Authentication and AuthorizationAuthentication is not required in this release of the web service. It is expected that the application which is invoking the web service will provide the proper authentication or security infrastructure prior to invoking the web service. Other alternative for WS-* authentication and policy authorization will be explored in future releases of the OpenPTK. JAX-WS will also be explored in a future release. Authorization is provided by limiting the capabilities of the administrative proxy account which is used to connect to the service. The SPML configuration instructions for the default service can be found in Appendix B. OperationSince this is a web service, it can be tested and used in many ways. It has been tested with SOAPUI, a Netbeans project, and an OpenESB business process. Soap UIThis is a demonstration of using a web service sample client which connects to the OpenPTK Provisioning Web Service. This web service provides a wsdl interface which exposes common user provisioning scenarios.
NetbeansNOTE: Netbeans 5.5 or greater with the JAX-RPC plugin is needed for this configuration:
Portlets (JSR-168)DescriptionThe OpenPTK Provisioning Portlets provide several JSR-168 compliant portlets which can be deployed in a portal server to provide user provisioning services. These portlet are the Forgotten Password Portlet, the Self Service portlet and the User Administration Portlet. Appendix A describes how to configure the OpenPTK framework to specify the Context and service used by the portlets. Authentication and AuthorizationThe security infrastructure provided by the portal server where the portlets are deployed is expected to provide the authentication and authorization. The portal server should be configured to enable the proper portlets only for the appropriate users in order to prevent unauthorized users from using them. The typical deployment scenario will include anonymous users being provided the Forgotten Password Portlet, End Users will be provided the Self Service portlet and Administrators will be provided the User Administration Portlet. Authorization is provided by limiting the capabilities of the administrative proxy account which is used to connect to the service. The SPML configuration instructions for the default service can be found in Appendix B. Appendix A: OpenPTK Framework ConfigurationThe OpenPTK framework uses a configuration file called openptk.xml. This file can be modified in order to change the behavior of the framework. This process is the same for all the sample which are provided with the OpenPTK project. The relative location of the openptk.xml file can be found in the following table for each of the sample applications described in this document.
The OpenPTK architecture reads the openptk.xml configuration file in order to configure the framework. ContextsThe OpenPTK framework uses one or many Contexts to link a Subject to a Service. A default context is configured in the openptk.xml file. This is used by the samples to connect to the provisioning infrastructure. <Context id="Sample-OpenPTK"> <Subject id="Person"/> <Service id="SPML-1.0-SJS-IdMgr"> <Properties> <Property name="url" value="http://sample.openptk.org/idm/servlet/rpcrouter2"/> </Properties> </Service> <Query type="EQ" name="MemberObjectGroups" value="Top:Customers"/> </Context> In the example above, the URL property is configured to point to the hosted Sun Identity Manager SPML 1.0 interface. This infrastructure is for testing the samples only. A separate infrastructure of Sun Identity Manager can be deployed. Sun Identity Manager is not part of the OpenPTK and must be obtained and deployed separately. Configuration instructions for the Sun Identity Manager SPML interface required for the OpenPTK samples is described in Appendix B. The default context used by the application is defined in this file to use SPML. <Contexts default="Person-SPML-Sun" logger="UnixLogFile" debug="4" audit="false" timestamp="true"> This file can be configured for Identity Manager Service Provider Edition (SPE) by changing the default context to: <Contexts default="Person-SPML-Sun-SPE" logger="UnixLogFile" debug="4" audit="false" timestamp="true"> This file can be configured for Java Naming and Directory Interface (JNDI) by changing the default context to: <Contexts default="Person-JNDI" logger="UnixLogFile" debug="4" audit="false" timestamp="true"> This file can be configured for MYSQL (JDBC) by changing the default context to: <Contexts default="Person-JDBC-MySQL" logger="UnixLogFile" debug="4" audit="false" timestamp="true"> SubjectsThe Subject section of this file is used to specify the attributes which are used in the OpenPTK Framework. Each attribute available for a given subject is described as well as the transformations. Transformations in the OpenPTK framework are used for processing attributes in the framework. An excerpt of a subject is listed below. <Subject id="Person" key="uniqueid" password="password" role="Roles" classname="org.openptk.provision.api.Person"> <Attributes> <Attribute id="uniqueid" required="true" type="String"> <Transformations> <Transform type="toService" useexisting="true" classname="org.openptk.provision.transform.FirstInitialLastname"> <Operations> <Operation type="create"/> </Operations> <Arguments> <Argument name="maxlength" arg="literal" value="8"/> <Argument name="first" arg="attribute" value="firstname"/> <Argument name="last" arg="attribute" value="lastname"/> </Arguments> </Transform> </Transformations> </Attribute> <Attribute id="firstname" required="true" /> <Attribute id="lastname" required="true" /> ........... </Subject> ServicesThe service section of this file describes how to configure connectivity of the OpenPTK framework to a service. It also contains attributes which are mapped to the attributes in the Subject. <Service id="SPML-Sun" classname="org.openptk.provision.spi.SpmlSunService" description="SJS Identity Manager Lighthouse client" sort="lastname,firstname"> <Properties> <Property name="timeout" value="5000"/> <Property name="spmlTrace" value="false"/> <Property name="extreq.oper.changepwd" value="changeUserPassword"/> <Property name="extreq.oper.resetpwd" value="resetUserPassword"/> <Property name="extreq.attr.uid.name" value="accountId"/> <Property name="extreq.attr.pwd.name" value="password"/> <Property name="extreq.attr.pwd.subject.attr" value="password"/> <Property name="extreq.attr.resources.key" value="accounts"/> <Property name="extreq.attr.resources.value" value="Lighthouse"/> </Properties> <Operations> <Operation type="create"/> <Operation type="read" timeout="15000"/> <Operation type="update"/> <Operation type="delete"/> <Operation type="search" timeout="15000"/> <Operation type="passwordChange" timeout="8000"/> <Operation type="passwordReset" timeout="8000"/> </Operations> <Attributes> <Attribute id="uniqueid" servicename="uid"/> <Attribute id="firstname" servicename="gn" /> <Attribute id="lastname" servicename="sn" /> <Attribute id="password" servicename="password"/> <Attribute id="fullname" servicename="cn"/> <Attribute id="forgottenPasswordQuestions"/> <Attribute id="forgottenPasswordAnswers"/> <Attribute id="forgottenPasswordData"/> <Attribute id="roles"/> <Attribute id="manager"/> <Attribute id="email"/> <Attribute id="title"/> <Attribute id="resources"/> <Attribute id="telephone"/> <Attribute id="organization"/> </Attributes> </Service> LoggersThe loggers section of this file describe how to configure the OpenPTK framework to handle logging of framework information. <Loggers> <Logger id="UnixLogFile" classname="org.openptk.provision.logging.AtomicLogger"> <Properties> <Property name="file" value="/var/tmp/openptk.log"/> </Properties> </Logger> </Loggers> Appendix B: Sun Identity Manager SPML ConfigurationIdentity Manager SPML InterfaceOverviewSPML is capable of many things and the operations use SOAP / HTTP, however, due to the extensible nature of SPML to support extended operations and schema differences, SPML does not provide a .wsdl interface to define it's operations. This is not a limitation of Identity Manager, it is just how SPML was designed. It allows for tremendous flexibility using this approach. !SPML Handlers in Identity Manager 8
It is assumed that the SPML 1.0 interface for Identity Manager will be used with the OpenPTK samples for this (version 1.1) release. Configuring Identity Manager for the OpenPTKIn order to use the OpenPTK samples, a Sun Identity Manager infrastructure must be available with the SPML interface configured for the OpenPTK SPML service. This configuration includes setting up the following items:
There are many configuration options for SPML in Sun Identity Manager. The OpenPTK does not currently leverage all the features, but the sample artifacts can be used to quickly configure the server to support the OpenPTK framework. The following Identity Manager configuration artifacts are included in the OpenPTK Identity Manager configuration instructions: Extract the OpenPTK-external-files.zip file to obtain the artifacts.
# cd $WSHOME/WEB-INF/config/custom
# $WSHOME/bin/lh console
console> console import ext/Sun/IdentityManager/artifacts/custom/UseCase-SPML-IDM8.xml
console> exit
<!-- IDM encryption configuration -->
<ImportCommand name="include" file="WEB-INF/config/custom/Encryption/EncryptionKey_openptk.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/Configuration/Configuration-EncryptionConfig.xml"/>
<!-- SPE artifacts -->
<ImportCommand name="include" file="WEB-INF/config/custom/Resource/Resource-ServiceProviderEnd-UserDirectory-idm8.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/Configuration/Configuration-ServiceProvider-idm8.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/Configuration/Configuration-ServiceProviderTrackedEventsConfiguration-idm8.xml"/>
<!-- Shared resources -->
<ImportCommand name="include" file="WEB-INF/config/custom/Policy/Policy-IdMAccountPolicy.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/Policy/Policy-AccountIdPolicy.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/Policy/Policy-PasswordPolicy.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/ObjectGroup/objectGroup-init.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/TaskDefinition/TaskDefinition-SPMLRequest.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/TaskDefinition/TaskDefinition-SPMLChangeUserPassword.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/Configuration/Configuration-BasicUser.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/Configuration/Configuration-SPMLPerson.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/Configuration/Configuration-SPMLRole.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/Configuration/Configuration-ptkPerson.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/Configuration/Configuration-SysInfoForm.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/Configuration/Configuration-Empty.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/Configuration/Configuration-SPML.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/Configuration/Configuration-SystemConfiguration.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/User/User-SPMLProxy.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/User/Users-SPML-Sample.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/Role/Role-SPMLRoles.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/UserForm/UserForm-CustomSPML-ProxyForm.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/Resource/Resource-LDAP.xml"/>
<!-- Identity Manager 8 specific objects -->
<ImportCommand name="include" file="WEB-INF/config/custom/Configuration/Configuration-IDMSchemaConfiguration.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/Role/Role_IT_CorporateDirectory.xml"/>
<ImportCommand name="include" file="WEB-INF/config/custom/Role/Role_Business_Employee.xml"/>
Optional: Configure SPML Authentication on the ServerNOTE: This is only required if you choose not to use the client side authentications of the OpenPTK SPML Sun Service. The following lines are added to the $WSHOME/config/Waveset.properties in order to configure a authenticated channel for all SPML 1 operations. NOTE: this configuration is not ideal for production since it exposes SPML operations with no per request authentication requirements. Since authentication is opt of scope for this release of the OpenPTK, this configuration is recommended only for testing purposes.
The SPML options for interfacing with Identity Manager assume that you are using an SPML api. There is an openspml java api for SPML. Using the Identity Manager SPML Browser:You can test the SPML configuration using the SPML Browser: $WSHOME/bin/lh spml Note: This can also be done inside a netbeans project which uses the Identity Manager Netbeans plugin (Select project, right click, select IDM - Run LH command: spml) Enter:
Once you successfully connect, you can sheck the schema on the server. These steps just validate that SPML is running on the Identity Manager server. SPML TracingYou can enable SPML tracing from any sources using the SPML browser--this will capture not just traces caused by using the SPML browser but also SPML activity on the server from other SPML clients. You may also edit WEB-INF/web.xml file in the SIM deployment, in the section for <servlet-name>openspmlRouter</servlet-name> and you should see the traces in the app server log files: <init-param>
<param-name>trace</param-name>
<param-value>true</param-value>
</init-param>
Identity Manager Service Provider Edition's SPML interfaceIdentity Manager provides a separate handler for IDMXuser objects. The OpenPTK is configured to use the standard SPML handler /servet/rpcrouter2 to handle SPE user provisioning operations. Identity Manager Service Provider Edition must be configured for this to work. Please see the Identity Manager documentation for configuration details. The artifacts included in the OpenPTK for Identity Manager do provide a default configuration for Identity Manager SPE, however the following additional configuration must be performed for SPE features to work with Identity Manager.
<mysql-installroot>/bin/mysql -uroot -p<password> < create_spe_tables.mysql
SPE LDAP suffix and sample users: # cd <openDS Home> # bin/dsconfig --no-prompt set-backend-prop --backend-name userRoot --add base-dn:dc=openptkspe,dc=org --hostname localhost --port 389 --bindDN "cn=directory manager" --bindPassword <password> # bin/ldapmodify -a -D "cn=Directory Manager" -w <password> -p 389 -f spe-repository-users.ldif -a -c
Appendix C: OpenDS ConfigurationOpenDS Installation Exampleunzip OpenDS-1.0.0.zip # ln -s /work/OpenDS-1.0.0 opends # cd opends # ./setup --cli Anwers Supplied: root user DN -Use the default value cn=Directory Manager -(Press ENTER) # cd <opends-installroot>/bin # ./create-rc-script -f opends-openptk # opends-openptk start Create the JNDI and LDAP RA suffix and users for OpenDS:# ./dsconfig --no-prompt set-backend-prop --backend-name userRoot --add base-dn:dc=openptk,dc=org --hostname localhost --port 389 --bindDN "cn=Directory Manager" --bindPassword <password> # ./ldapmodify -a -D "cn=Directory Manager" -w <password> -p 389 -f OpenPTKLDAPobjects.ldif -a -c Processing ADD request for dc=openptk,dc=org ADD operation successful for DN dc=openptk,dc=org Processing ADD request for ou=People,dc=openptk,dc=org ADD operation successful for DN ou=People,dc=openptk,dc=org Processing ADD request for uid=idmadmin,ou=people,dc=openptk,dc=org ADD operation successful for DN uid=idmadmin,ou=people,dc=openptk,dc=org OpenDS Configuration for OpenPTK ServiceDue to a Reset Password permission issue, use a new admin account (instructions to create are below) the other option is to use the cn=Directory Manager for the LDAP resource adapter. NOTE: FOR INFORMATION ONLY - If you need to delete the suffix, use the ldapdelete command:# ldapdelete -D "cn=Directory Manager" -w Passw0rd -p 389 -x dc=openptk,dc=orgAppendix D: MySQL ConfigurationInstallation Example for MySQL (on Solaris x86)Obtain MySQL (version 5.0 or higher is recommended) unzip mysql Install MySQL# groupadd mysql # useradd -g mysql mysql # cd /usr/local # gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf - # ln -s full-path-to-mysql-VERSION-OS mysql # cd mysql # chown -R mysql . # chgrp -R mysql . # scripts/mysql_install_db --user=mysql # chown -R root . # chown -R mysql data # bin/mysqld_safe --user=mysql & # ./bin/mysqladmin -u root password 'threeamigos' # cp support-files/my-medium.cnf /etc/my.cnf Add the following configuration properties to this my.cnf file * [mysqld] * * [mysql] * # <mysql-installroot>/support-files/mysql.server stop # <mysql-installroot>/support-files/mysql.server start # <mysql-installroot>/bin/mysql -uroot -p<password> MySQL Configuration for OpenPTK ServiceCreating the MySQL database for the OpenPTK Service -- Example MySQL CREATE scripts. You may use these scripts to create a testdata table -- for testing using the supplied openptk-jdbc.xml configuration -- The following creates a table with the following structure. -- +----------+--------------+------+-----+---------+-------+ -- | Field | Type | Null | Key | Default | Extra | -- +----------+--------------+------+-----+---------+-------+ -- | id | int(11) | YES | | NULL | | -- | fname | varchar(255) | YES | | NULL | | -- | lname | varchar(255) | YES | | NULL | | -- | fullname | varchar(255) | YES | | NULL | | -- +----------+--------------+------+-----+---------+-------+ Obtain the DDL example file for the OpenPTK MySQL Service openptk/ext/Sun/MySQL/sql/create_testdata_mysql.sql # <mysql-installroot>/bin/mysql -uroot -ppassword < create_testdata_mysql.sql # <mysql-installroot>/bin/mysql -uroot -ppassword mysql> show databases; +--------------------+ | Database | +--------------------+ | information_schema | | mysql | | openptk | | test | +--------------------+ mysql> use openptk; Database changed mysql> show tables; +-------------------+ | Tables_in_openptk | +-------------------+ | testdata | +-------------------+ 1 row in set (0.00 sec) mysql> select * from testdata; +----------+-------+---------+---------------+----------------------+----------+--------------+----------+---------+---------+ | id | fname | lname | fullname | email | title | telephone | manager | roles | org | +----------+-------+---------+---------------+----------------------+----------+--------------+----------+---------+---------+ | dsmith | Don | Smith | Don Smith | jsmith@openptk.org | CEO | 123-456-7890 | fsinatra | emp | Top | | fsinatra | Frank | Sinatra | Frank Sinatra | fsinatra@openptk.org | Chairman | unlisted | | leader | Top | | jbauer | Jack | Bauer | Jack Bauer | jbauer@ctu.gov | Agent | secret | pres | agent | ctu | | jsarrow | Jack | Sparrow | Jack Sparrow | jsparrow@disney.com | Captain | secret | jbauer | captain | ctu | | dhan | Dean | Han | Dean Han | dhan@openptk.org | Sales | 123-456-7890 | jbauer | sales | Central | +----------+-------+---------+---------------+----------------------+----------+--------------+----------+---------+---------+ 5 rows in set (0.00 sec) Appendix E: Secure SPML communicationsThis section will cover how to configure the Sun Identity Manger (Server) and Project OpenPTK (Client) to use secure encrypted communications for SPML. Two Glassfish v2 domains are used throughout this example configurations: Enabling secure / encrypted SPML communications involves the following steps:
Configuring Project OpenPTKEnabling OpenPTK, and it's sample applications, to leverage secure SPML communications with Sun Identity Manager requires that the openptk.xml configuration file be updated. The URL Property for the Service needs to include the correct protocol and port number. The examples in this doc use the following values for the openptk.xml configuration file:
Here is the sample configuration: <Context id="Person-SPML-Sun" classname="org.openptk.provision.common.TimeoutContext"> <Subject id="Person"/> <Service id="SPML-Sun"> <Properties> <Property name="url" value="https://localhost:52091/idm8/servlet/rpcrouter2"/> <Property name="user.name" value="SPML-Proxy"/> <Property name="user.password" value="password"/> <Property name="objectclass" value="user"/> </Properties> </Service> <Query type="AND"> <Query type="EQ" name="MemberObjectGroups" serviceName="MemberObjectGroups" value="All People"/> <Query type="EQ" name="objectclass" value="user"/> </Query> </Context> If necessary, compile / build the OpenPTK project. This document will use the OpenPTK CLI sample application and the User Management Lite (UML) application to demonstrate end-to-end secure SPML communications. Setting up the Client and the Server
Two Glassfish V2 domains were created with the following configurations:
Server (idm8)It is assumed that the following has already been installed on the "Server" domain (idm8):
Ensure that the "Server" domain (idm8) is running and has the secure port enabled. Client (openptk)It is assumed that the following has already been installed on the "Client" domain (openptk):
Ensure that the "Client" domain (openptk) is running and has the secure port enabled. Creating trustBefore the OpenPTK application(s) (Client) can securely communicate with the Sun Identity Manager SPML Interface (Server), there needs to be a trust relationship. This is established by creating a certificate on the Server and then making it available to the Client.
Create a new Server-side certificateWhen a Glassfish domain is created, a default self-signed certificate is created and stored in it's Java Key Store: keystore. The keystore for a given domain is locate at $GLASSFISH_HOME/domains/$DOMAIN_NAME/config/keystore.jks. Before you begin, create a backup copy of the default keystore.jks file: % cd /usr/local/glassfish/domains/idm8/config % cp keystore.jks keystore.jks_orig You can list the existing certificates in the keystore using the keytool utility: % cd /usr/local/glassfish/domains/idm8/config % keytool -list -keystore keystore.jks -storepass changeit Keystore type: jks Keystore provider: SUN Your keystore contains 1 entry s1as, May 12, 2008, keyEntry, Certificate fingerprint (MD5): 2C:30:19:6E:32:19:FF:E5:7E:73:AB:F2:04:5D:D1:4F An existing certificate can not be replaced, it must deleted and then (re-)created. Delete the default certificate (alias=s1as) using the keytool utility: % cd /usr/local/glassfish/domains/idm8/config % keytool -delete -alias s1as -keystore keystore.jks -storepass changeit Generate a new self-signed certificate using a 1024-bit RSA key and lets make it good for a year. We need to use the same alias (s1as) and the same password (changeit):
% cd /usr/local/glassfish/domains/idm8/config % keytool -genkey -keyalg RSA -keysize 1024 -alias s1as -validity 365 -keystore keystore.jks -storepass changeit What is your first and last name? [Unknown]: localhost What is the name of your organizational unit? [Unknown]: Provision What is the name of your organization? [Unknown]: OpenPTK What is the name of your City or Locality? [Unknown]: Chicago What is the name of your State or Province? [Unknown]: IL What is the two-letter country code for this unit? [Unknown]: US Is CN=localhost, OU=Provision, O=OpenPTK, L=Chicago, ST=IL, C=US correct? [no]: yes Enter key password for (RETURN if same as keystore password): You can list your new certificate with the keytool utility: % cd /usr/local/glassfish/domains/idm8/config % keytool -v -list -alias s1as -keystore keystore.jks -storepass changeit Alias name: s1as Creation date: Aug 25, 2008 Entry type: keyEntry Certificate chain length: 1 Certificate[1]: Owner: CN=localhost, OU=Provision, O=OpenPTK, L=Chicago, ST=IL, C=US Issuer: CN=localhost, OU=Provision, O=OpenPTK, L=Chicago, ST=IL, C=US Serial number: 48b2bc10 Valid from: Mon Aug 25 09:05:04 CDT 2008 until: Fri Aug 14 09:05:04 CDT 2009 Certificate fingerprints: MD5: D6:AC:50:C8:37:03:33:75:5C:C5:4A:62:EB:06:3F:DA SHA1: 0B:57:F4:7D:1B:62:D0:DA:48:26:61:82:1F:89:4C:29:05:D6:B1:C7 You MUST restart the server (idm8) Glassfish domain Extract the Server's certificateWe need to extract the newly created Sun Identity Manager (Server) certificate to a file (/var/tmp/openptk/openptk.cer). This file will be used by the OpenPTK (Client) Use the keytool utility to export the certificate: % mkdir -p /var/tmp/openptk % cd /usr/local/glassfish/domains/idm8/config % keytool -export -alias s1as -file /var/tmp/openptk/server.cer -keystore keystore.jks -storepass changeit Certificate stored in file </var/tmp/openptk/server.cer> You can use the keytool utility to print the certificate: % keytool -v -printcert -file /var/tmp/openptk/server.cer
Owner: CN=localhost, OU=Provision, O=OpenPTK, L=Chicago, ST=IL, C=US
Issuer: CN=localhost, OU=Provision, O=OpenPTK, L=Chicago, ST=IL, C=US
Serial number: 48b2bc10
Valid from: Mon Aug 25 09:05:04 CDT 2008 until: Fri Aug 14 09:05:04 CDT 2009
Certificate fingerprints:
MD5: D6:AC:50:C8:37:03:33:75:5C:C5:4A:62:EB:06:3F:DA
SHA1: 0B:57:F4:7D:1B:62:D0:DA:48:26:61:82:1F:89:4C:29:05:D6:B1:C7
Add the certificate to the ClientThe Glassfish domain openptk (Client) stores its Trusted certificates in the /usr/local/glassfish/domains/openptk/config/cacerts.jks file. We can list the current certificates using the keytool utility: % cd /usr/local/glassfish/domains/openptk/config % keytool -list -keystore cacerts.jks -storepass changeit Keystore type: jks Keystore provider: SUN Your keystore contains 33 entries equifaxsecureebusinessca1, Jul 18, 2003, trustedCertEntry, Certificate fingerprint (MD5): 64:9C:EF:2E:44:FC:C6:8F:52:07:D0:51:73:8F:CB:3D ... equifaxsecureebusinessca2, Jul 18, 2003, trustedCertEntry, Certificate fingerprint (MD5): AA:BF:BF:64:97:DA:98:1D:6F:C6:08:3A:95:70:33:CA It's a good idea to copy the cacerts.jks to a backup file: % cd /usr/local/glassfish/domains/openptk/config % cp cacerts.jks cacerts.jks_orig The alias name on openptk (Client) is localhost, NOT s1as. Import the new certificate using the keytool utility: % cd /usr/local/glassfish/domains/openptk/config % keytool -import -trustcacerts -alias localhost -file /var/tmp/openptk/server.cer -keystore cacerts.jks -storepass changeit Owner: CN=localhost, OU=Provision, O=OpenPTK, L=Chicago, ST=IL, C=US Issuer: CN=localhost, OU=Provision, O=OpenPTK, L=Chicago, ST=IL, C=US Serial number: 48b2bc10 Valid from: Mon Aug 25 09:05:04 CDT 2008 until: Fri Aug 14 09:05:04 CDT 2009 Certificate fingerprints: MD5: D6:AC:50:C8:37:03:33:75:5C:C5:4A:62:EB:06:3F:DA SHA1: 0B:57:F4:7D:1B:62:D0:DA:48:26:61:82:1F:89:4C:29:05:D6:B1:C7 Trust this certificate? [no]: yes Certificate was added to keystore List the newly added certificate: % cd /usr/local/glassfish/domains/openptk/config % keytool -v -list -alias localhost -keystore cacerts.jks -storepass changeit Alias name: localhost Creation date: Aug 25, 2008 Entry type: trustedCertEntry Owner: CN=localhost, OU=Provision, O=OpenPTK, L=Chicago, ST=IL, C=US Issuer: CN=localhost, OU=Provision, O=OpenPTK, L=Chicago, ST=IL, C=US Serial number: 48b2bc10 Valid from: Mon Aug 25 09:05:04 CDT 2008 until: Fri Aug 14 09:05:04 CDT 2009 Certificate fingerprints: MD5: D6:AC:50:C8:37:03:33:75:5C:C5:4A:62:EB:06:3F:DA SHA1: 0B:57:F4:7D:1B:62:D0:DA:48:26:61:82:1F:89:4C:29:05:D6:B1:C7 You MUST restart the Glassfish domain openptk (Client) Command Line Interface (CLI)Project OpenPTK contains a command line interface (CLI) utility called ptk. This is nice way to test the SSL communications from the Java application to the Server (idm8). Either un-pack or build the OpenPTK project which includes the CLI. If the ptk command is executed, you will get a org.openspml.util.SpmlException: Error opening socket: null message: % ./ptk search SEVERE: org.openptk.provision.exception.ServiceException: SpmlSunService:doSearch(): org.openspml.util.SpmlException: Error opening socket: null Aug 25, 2008 2:58:05 PM org.openptk.provision.logging.AtomicLogger put INFO: Timestamp: 449 (msec) [TimeoutContext [Person-SPML-Sun] execute() search] Aug 25, 2008 2:58:05 PM org.openptk.provision.logging.AtomicLogger put SEVERE: org.openptk.provision.exception.ServiceException: SpmlSunService:doSearch(): org.openspml.util.SpmlException: Error opening socket: null ptk.doSearch(), (you may need to supply at least one query value): Person:execute(): ERROR: search: org.openptk.provision.exception.ServiceException: SpmlSunService:doSearch(): org.openspml.util.SpmlException: Error opening socket: null The ptk command failed because the Java Virtual Machine's (JVM) default keystore, for certificates, does not contain the new certificate generated from the "Server" (idm8) Updating the default JVM's keystore is out of scope for this document. For this example, we will define a Java Property javax.net.ssl.trustStore which will override the keystore. This will be set as an environment variable. The ptk scripts could also be modified to set this Property. We will set a variable used by the ptk command called JAVA_ARGS. The Property will be set to reference the Glassfish domain openptk Client cacerts.jks file: % export JAVA_ARGS=-Djavax.net.ssl.trustStore=/usr/local/glassfish_v2/domains/openptk/config/cacerts.jks Now we can run the ptk command, the SSL communications is established, the SPML message is sent and the output is returned: % ./ptk search -r lastname Aug 25, 2008 3:12:39 PM org.openptk.provision.logging.AtomicLogger put INFO: Timestamp: 477 (msec) [TimeoutContext [Person-SPML-Sun] execute() search] Aug 25, 2008 3:12:39 PM org.openptk.provision.logging.AtomicLogger put INFO: Timestamp: 0 (msec) [TimeoutContext [Person-SPML-Sun] sortResults()::search] ----------------------------- 1 of 5 ----------------------------- UniqueId : jbauer lastname : Bauer ----------------------------- 2 of 5 ----------------------------- UniqueId : jhancock lastname : Hancock ----------------------------- 3 of 5 ----------------------------- UniqueId : dmartin lastname : Martin ----------------------------- 4 of 5 ----------------------------- UniqueId : fsinatra lastname : Sinatra ----------------------------- 5 of 5 ----------------------------- UniqueId : jwayne lastname : Wayne User Management Lite (UML)Build the User Management Lite (UML) war file with a properly configured openptk.xml using the ant command. The openptk-uml-1.1.0.war file will be created. Log into the Admin Console for the Client (openptk) Glassfish domain. Deploy the WAR file using uml as the Context Root You should be able to access the User Management Lite (UML) application from your browser using https and port 38181 ... https://localhost:38181/uml The OpenPTK application (UML), is running in the Web Container of the Glassfish domain opentpk (Client) which has the certificate for the Glassfish domain idm8 (Server). |
Release 1.x >
