Docs 1.1 Installation Guide

Version 111 by harcey
on Jan 06, 2009 21:16.
<< Changes from 110 to 111
compared with
Current by harcey
on Jan 07, 2009 07:52.
Key
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (2)

View page history
{anchor:Top}
{warning}This documents is *under construction*{warning}

{toc:maxLevel=1}

[Top|#Top]
----

h1. Revision History

|| Description || Author || Version || Date ||
| Initial Creation | Derrick Harcey | 0.9.0 | September 2006 |
| Update for release | Derrick Harcey | 1.0.0 | August 2007 |
| Update for release, move to wiki | Scott Fehrman | 1.1.0 | August 2008 |


[Top|#Top]
----

h1. This Document

This document provides installation instructions related to Project Open Provisioning Toolkit (OpenPTK). The OpenPTK is used to build custom end-user provisioning interfaces that leverage commercial user provisioning solutions.

[Top|#Top]
----

h1. Related Documents

Project OpenPTK includes a collection of related documents to assist teams that want to:

* Install Project OpenPTK in their environment
* Configure it for a specific situation
* Customize the samples
* Develop extra features

The following Project OpenPTK documents are available:

* [Overview|openptk:Docs 1.1 Overview]
* [Release Notes|openptk:Docs 1.1 Release Notes]
* [Architecture Guide|openptk:Docs 1.1 Architecture Guide]
* [Configuration Reference Guide|openptk:Docs 1.1 Configuration Reference Guide]
* [Installation Guide|openptk:Docs 1.1 Installation Guide]
* [Developers Guide|openptk:Docs 1.1 Developers Guide]
* [Samples Guide|Docs 1.1 Applications Guide]
* [NetBeans Reference Guide|openptk:Docs 1.1 NetBeans Reference Guide]
* [Sample XML Configuration File (openptk.xml)|openptk:Release 1.1 Sample XML file]
* [Java Client (Consumer) APIs javadocs|http://sample.openptk.org/javadoc]

[Top|#Top]
----

h1. Overview

This document will cover the installation of Project OpenPTK.

[Top|#Top]
----

h1. Source Code

[Top|#Top]
----

h1. Secure SPML communications

This 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:

!openptk-secure-arch-overview.png|align=centre!

Enabling secure / encrypted SPML communications involves the following steps:

# Configuring OpenPTK applications to use SSL/HTTPS
# Replacing the default certificate on the *Server*, Sun Identity Manager
# Adding the certificate to the *Client*, OpenPTK

[Top|#Top]
----

h2. Configuring Project OpenPTK

Enabling 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:

|| Protocol: | {{https}} |
|| Host: | {{localhost}} |
|| Port: | {{52091}} |

Here is the sample configuration:

{code:xml}
<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>
{code}

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.

[Top|#Top]
----

h2. Setting up the Client and the Server

{info:title=Useful Information}
The examples covered in this document will use the following values:
||Server|
|Java Key Store: | {{/usr/local/glassfish/domains/idm8/config/keystore.jks}} |
|Keystore password: | {{changeit}} (default)|
|Certificate Alias: | {{s1as}} (default)|
||Client|
|Java Key Store: | {{/usr/local/glassfish/domains/openptk/config/cacerts.jks}} |
|Keystore password: | {{changeit}} (default)|
|Certificate Alias: | {{localhost}} |
{info}

Two Glassfish V2 domains were created with the following configurations:

||Name||Ports||Applications/Services||
| *idm8* \\ (Server) |admin: http://localhost:24848 \\ http: http://localhost:28080 (disabled) \\ https: https://localhost:52091|Glassfish Administration Console \\ Sun Identity Manger Admin Interface \\ Sun Identity Manager SPML Interface |
| *openptk* \\ (Client) |admin: http://localhost:34848 \\ http: http://localhost:38080 (disabled) \\ https: https://localhost:38181|Glassfish Administration Console \\ Sun Identity Manger Admin Interface \\ Sun Identity Manager SPML Interface |

h3. Server (idm8)

It is assumed that the following has already been installed on the "Server" domain *(idm8)*:
* Sun Identity Manager
* SPML is enabled
* The sample Project OpenPTK artifacts have been imported

Ensure that the "Server" domain *(idm8)* is running and has the secure port enabled.

h3. Client (openptk)

It is assumed that the following has already been installed on the "Client" domain *(openptk)*:
* OpenPTK's User Management Lite (UML) Sample Application

Ensure that the "Client" domain *(openptk)* is running and has the secure port enabled.

[Top|#Top]
----

h2. Creating trust

Before 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*.

{note:title=Security Alert}
This example uses a self-signed certificate, for development and testing. Deployed production applications should use certificates that are signed by an external trusted authority.
{note}

h3. Create a new Server-side certificate

When 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:

{code}
% cd /usr/local/glassfish/domains/idm8/config
% cp keystore.jks keystore.jks_orig
{code}

You can list the existing certificates in the keystore using the {{keytool}} utility:

{code}
% 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

{code}

An existing certificate can not be replaced, it *must* deleted and then (re-)created. Delete the default certificate (alias={{*s1as*}}) using the {{keytool}} utility:

{code}
% cd /usr/local/glassfish/domains/idm8/config
% keytool -delete -alias s1as -keystore keystore.jks -storepass changeit
{code}

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}}):

{note:title=Be Careful}
In addition to the *alias* and the *password*, the values you enter during this process are *CRITICAL*. These values are used to build a Distinguished Name (DN). Even though the question says "{{first and last name}}", this *must* be the hostname that the client will use. The {{hostname}} should be the FQDN of the "Server" *(idm8)*. In this example, {{hostname}} is set to {{localhost}} because both the "Server" *(idm8)* and "Client" *(openptk)* domains are running on the same system. This table contains the values used in this example:

||Name||Sample Value||Comment
|first and last name | {{localhost}} |The actual hostname that is being used for the Server.|
|organizational unit| {{Provision}} | This can be any value |
|organization| {{OpenPTK}} | This can be any value |
|City or Locality| {{Chicago}} |Use your location|
|State or Province| {{IL}} |Use your location|
|Country Code| {{US}} |Use your country|
{note}

{code}
% 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): 
{code}

You can list your new certificate with the {{keytool}} utility:

{code}
% 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
{code}

You *MUST* restart the server (idm8) Glassfish domain

h3. Extract the Server's certificate

We 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:

{code}
% 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>
{code}

You can use the {{keytool}} utility to print the certificate:

{code}
% 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
{code}

h3. Add the certificate to the Client

The 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:

{code}
% 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
{code}

It's a good idea to copy the {{cacerts.jks}} to a backup file:

{code}
% cd /usr/local/glassfish/domains/openptk/config
% cp cacerts.jks cacerts.jks_orig
{code}

The *alias* name on openptk *(Client)* is *{{localhost}}*, NOT *{{s1as}}*. Import the new certificate using the {{keytool}} utility:

{code}
% 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
{code}

List the newly added certificate:

{code}
% 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
{code}

You *MUST* restart the Glassfish domain {{openptk}} *(Client)*

[Top|#Top]
----

h2. 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:

{code}
% ./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
{code}

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:

{code}
% export JAVA_ARGS=-Djavax.net.ssl.trustStore=/usr/local/glassfish_v2/domains/openptk/config/cacerts.jks
{code}

Now we can run the {{ptk}} command, the SSL communications is established, the SPML message is sent and the output is returned:

{code}
% ./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

{code}

[Top|#Top]
----

h2. 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

!openptk-uml-https.png|align=centre!

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).

[Top|#Top]
----
{warning}This documents has been merged with the [Applications Guide|Docs 1.1 Applications Guide]{warning}

The individuals who post here are part of the extended Sun Microsystems community and they might not be employed or in any way formally affiliated with Sun Microsystems. The opinions expressed here are their own, are not necessarily reviewed in advance by anyone but the individual authors, and neither Sun nor any other party necessarily agrees with them.

Copyright 1994-2009 Sun Microsystems, Inc.
Powered by Atlassian Confluence Sun Guidelines on Public Discourse Privacy Policy Terms of Use Trademarks Site Map Employment Investor Relations Contact