Docs 2.0 What's New

{anchor:top}

This document will cover the new features contained within this release

{toc}

----

[Top|#top]
----

h1. Architecture

h2. Server

h3. RESTful-based Web Service

* Implemented using JAX-RS (Jersey)

h3. WSDL-based Web Service (new design)

The WSDL-based Web Service (sample application) has been updated to use the JAX-WS API [http://metro.dev.java.net]. The previous version used the JAX-RPC Web Service API.

The WSDL has not changed from the previous release (1.1). The following operations are provided:

* Create
* Read
* Update
* Delete
* Search

The WSDL is available using the following syntax:

{code}
http://host:port/ProvisionService/ProvisionPerson?wsdl
{code}

h2. Client

h3. Command Line (console)

h3. User Management Lite (UML)

h3. JSR-168 Portlets

[Top|#top]
----

h1. Sample Applications

h2. Command Line Interface

h3. New {{search}} output format

The CLI sample application has a new *SEARCH* output format. Data is displayed in a column format:

{code}
ptk search -C Person-OpenDS-JNDI
Dec 15, 2008 4:00:24 PM org.openptk.provision.logging.AtomicLogger put
INFO: Timestamp: 15 (msec) [BasicContext [Person-OpenDS-JNDI] execute()::SEARCH]
Dec 15, 2008 4:00:24 PM org.openptk.provision.logging.AtomicLogger put
INFO: Timestamp: 0 (msec) [BasicContext [Person-OpenDS-JNDI] sortResults()::SEARCH]
uniqueid lastname firstname email fullname
-----------------------------------------------------------------------------------------
eapi API jimmy herbyt@openptk.org Example API
jbower Bower Jack jack@ctu.gov Jack Bower
depps Epps David david.epps@openptk.org David Epps
sfehrman Fehrman Scott sfehrman@openptk.org Scott Fehrman
thanks Hanks Tom tom.hanks@openptk.org Tom Hanks
dharcey Harcey Derrick derrick@openptk.org Derrick Harcey
jharkne Harkness Jack jack@torchwood.gov.uk Jack Harkness
jjsplna jsplname jspfname jspfname.jsplname@identric.com jspfname jsplname
gscott Scott George George Scott
tsigle Sigle Terry terry@openptk.org Terry Sigle
csmith Smith Chris Chris Smith
jsparo Sparo Jack captain@blackpearl.org Jack Sparo
jtrainer Trainer Jack jtrainer@testing.org Jack Trainer
cuser User CLI CLI.User@openptk.org CLI User
dvader Vader Darth lord.vader@empire.org Darth Vader
twebser WebService Test Test WebService
-----------------------------------------------------------------------------------------
Records: 16
{code}

h3. The uniqueid argument optional for {{create}}

The {{create}} sub-command no longer requires the {{-u <uniqueid> }} arguments. If the Context has a process for deriving a unique identifier then the {{-u}} argument is not needed. This option is still available for manually setting (overriding) the uniqueid.

{info:title=Notice}
The actual use (or non-use) of the uniqueid is dependent on the configuration of the Context that is being used.
{info}

[Top|#top]
----

h1. Framework Tier

h2. Configuration File Schema

The XML file {{openptk.xml}} has a new schema format. The schema leverages the new Service / Operation Architecture. The schema uses the following components:

|| Name || Description ||
| {{Context}} | The top level construct used by the OpenPTK APIs. The Context contains references to a Definition, Service, Association, AttrGroup and Operation(s) |
| {{Definition}} | Defines the Subject used by the OpenPTK APIs. The Definition contains Attributes and their optional Functions. |
| {{Association}} | Contains the mapping of OpenPTK Attribute names to the Service / Operation specific Attribute names. Attributes defined in an Association can also contain Functions. |
| {{AttrGroup}} | Defines a collection of Attributes. An AttrGroup is assigned to an Operation (CREATE,READ,UPDATE,DELETE,SEARCH). Only the Attributes defined in an AttrGroup are available to the Operation. |
| {{Service}} | Identifies the back-end user repository connection information. A Service, via the {{Context}}, has the ability to support different back-end user repositories on a per Operation basis. A different Operation can be used for: CREATE, READ, UPDATE, DELETE, SEARCH, PWDCHANGE, PWDRESET. |
| {{Operation}} | Provides the back-end user, repository specific, which implements the provisioning logic. Operations are used by being assigned to a Service for one or more logical Operations |
| {{Security}} | Declares Security related information. Supported sub-Elements include {{Encryption}} |

h3. Configuration Defaults

The XML configuration file has a new *Defaults* section. Properties defined within the *Defaults* section can be accessed by parts of the configuration file as a variable using the %\{property_name\} syntax. Variable replacement is *only* done at initial start-up.

Sample Defaults:

{code:xml}
<Defaults>
<Properties>
...
<Property name="jndi.basedn" value="ou=People,dc=openptk,dc=org"/>
...
<Property name="jdbc.driver" value="com.mysql.jdbc.Driver"/>
...
</Properties>
</Defaults>
{code}


Variable replacement can be used within the following parts of the XML file:

* Property {{value}} arguments
* Argument {{value}} arguments

Examples:

{code:xml}
<Property name="driver" value="%{jdbc.driver}"/>
{code}

{code:xml}
<Argument name="basedn" arg="literal" value=",%{jndi.basedn}"/>
{code}

h3. Context enable/disable

A {{Context}} can be enabled/disabled by setting its {{enable}} argument. Setting the argument to *true* enables the {{Context}}, *false* will disable the {{Context}}.

{code:xml}
<Context id="Person-OpenDS-JNDI" enabled="true" definition="Person" service="OpenDS" association="JNDI">
...
</Context>
<Context id="Person-MySQL-JDBC" enabled="false" definition="Person" service="MySQL" association="JDBC">
...
</Context>
{code}

This feature is useful when a configuration file {{openptk.xml}} might have multiple configured {{Contexts}} while only a few may be used.

h3. Virtual Attributes

A virtual attribute is defined within the OpenPTK Framework and does not exist in a back-end User repository. A virtual attribute is derived from a combination of static literal strings and other "real" attribute values.

{code:xml}
<Attribute id="lastcommafirst" virtual="true">
<Functions>
<Function id="OutputLastFirst" classname="org.openptk.provision.definition.functions.ConcatStrings">
<Arguments>
<Argument name="arg1" type="attribute" value="lastname"/>
<Argument name="arg2" type="literal" value=", "/>
<Argument name="arg3" type="attribute" value="firstname"/>
</Arguments>
<Operations>
<Operation type="read"/>
<Operation type="search"/>
</Operations>
</Function>
</Functions>
</Attribute>
{code}

h3. Encrypted Passwords

The Framework uses {{Property}} Elements to set the "user" credentials for all of the {{Connections}}. The *password* can now be encrypted and stores in the configuration file. To enable encrypted passwords, these steps need to be used:

# Get the encrypted string that represents your password. Use the {{org.openptk.util.ptkadmin}} utility to generate the encrypted value.
# Configure an {{<Encryption ...>}} Element in the {{<Security>}} section of the configuration file.
# Add the Property {{security.encryption}} to {{Contexts}} or a specific {{Context}}, the value needs to match the {{id}} of the {{<Encryption>}} Element in the {{<Security>}} section.
# Change the {{user.password}} Property in the {{<Defaults>}} or the {{<Connection>}} to be {{user.password.encrypted}}. Set the value o be output of the {{org.openptk.util.ptkadmin}} utility.
# The system will automatically look for the {{.encrypted}} value and decrypt it.

Setting the encrypted password in a *Defaults* Property:

{code:xml}
<Defaults>
<Properties>
<Property name="spml1.url" value="http://www.openptk.org/idm/servlet/rpcrouter2"/>
<Property name="spml1.user.name" value="SPML-Proxy"/>
<Property name="spml1.user.password.encrypted" value="EnespBAb/hMwNylyxlh0jw=="/>
...
</Properties>
</Defaults>
{code}

Using the encrypted password in a *Connection* Property:

{code:xml}
<Connection id="SunSPML1">
<Properties>
<Property name="connection.description" value="Sun Identity Manager Lighthouse client (SPML1)"/>
<Property name="url" value="%{spml1.url}"/>
<Property name="user.name" value="%{spml1.user.name}"/>
<Property name="user.password.encrypted" value="%{spml1.user.password.encrypted}"/>
<Property name="spmlTrace" value="false"/>
</Properties>
</Connection>
{code}

The features leverages Password Base Encryption (PBE). The default implementation uses the {{PBEWithMD5AndDES}} Java Cryptographic Architecture (JCA) Provider.

[Top|#top]
----

h2. Java API

Some of the Java API Interfaces and Classes have changed.

h3. {{org.openptk.provision.api.SubjectIF}}

The identifiers for the *Operation* has changed from {{int}} to {{enum}}. The following {{enum}} values are used to identify the *Operation*.

* CREATE
* READ
* UPDATE
* DELETE
* SEARCH
* PWDCHANGE
* PWDRESET

The individual methods for each *Operations* have been replaced with a single {{execute()}} method. The {{execute()}} method does require an *Operation* {{enum}} value. Here is the interface for the method:

{code}
public Output execute(SubjectIF.Operation oper, Input input) throws ProvisionException;
{code}

h3. {{org.openptk.provision.api.ElementIF}}

The identifiers for the *State* has changed from {{int}} to {{enum}}. The following {{enum}} values are used to identify the *State*.

* NULL
* NEW
* READY
* SUCCESS
* FAILED
* RUNNING
* WAITING
* STOPPED
* ERROR

h3. {{org.openptk.provision.api.AttributeIF}}

A new {{enum}} was added to indicate the *Attribute* type. The following {{enum}} values are used to defined the type. The default type is *String*.

* OBJECT
* STRING
* INTEGER
* BOOLEAN

h3. {{org.openptk.provision.common.ComponentIF}}

The identifier for the *State* has changed from {{int}} to {{enum}}. The following {{enum}} values are used to identify the *State*.

* NULL
* NEW
* READY
* SUCCESS
* FAILED
* RUNNING
* WAITING
* STOPPED
* ERROR

The identifier for the *Category* has changed from {{int}} to {{enum}}. The following {{enum}} values are used to identify the *Category*.

* GENERIC
* CONTEXT
* SERVICE
* REQUEST
* RESPONSE
* PERSON
* RESOURCE
* ROLE
* GROUP
* ORGANIZATION
* OPERATION
* ASSOCIATION
* ATTRGROUP
* DEFINITION

The identifier for the *Debug* has changed from {{int}} to {{enum}}. The following {{enum}} values are used to identify the *Debug*.

* NONE
* CONFIG
* FINE
* FINER
* FINEST

[Top|#top]
----

h2. {{Functions}} replace {{Transformations}}

A given *Attribute* defined within a *Definition* or a *Association* can now have multiple *Functions*. Functions can do more than just transform attributes, they can also be used to validate data.

The {{mode}} Element Argument is no longer used.

{code:xml}
<Attribute id="manager">
<Functions>
<Function id="buildDN" classname="org.openptk.provision.definition.functions.ConcatStrings">
<Arguments>
<Argument name="prefix" type="literal" value="uid="/>
<Argument name="uid" type="attribute" value="manager"/>
<Argument name="basedn" type="literal" value=",%{jndi.basedn}"/>
</Arguments>
<Operations>
<Operation type="create"/>
<Operation type="update"/>
</Operations>
</Function>
<Function id="getUid" classname="org.openptk.provision.definition.functions.SubString">
<Arguments>
<Argument name="after" type="literal" value="uid="/>
<Argument name="before" type="literal" value=","/>
</Arguments>
<Operations>
<Operation type="read"/>
</Operations>
</Function>
</Functions>
</Attribute>
{code}

[Top|#top]
----

h2. Security Crypto Package

The package {{org.openptk.security.crypto}} along with abstract and implementation classes are used to support basic encryption ad decryptio. There is a Password Base Encryption (PBE) class which uses MD5 and TripleDES. These classes are used to encrypt / decrypt Strings. The default Constructor uses an internal Pass Phrase for encrypting the String.

|| Name || Type || Extends || Implements || Methods || Notes ||
| {{CryptoIF}} | Interface | n/a | n/a | encrypt(), decrypt(), getId(), setId() | |
| {{Crypto}} | Abstract Class | n/a | {{CryptoIF}} | encrypt(), decrypt(), getId(), setId() | |
| {{PBECrypto}} | Class | {{Crypto}} | {{CryptoIF}} | | |
| {{DESCrypto}} | Class | {{PBECrypto}} | {{CryptoIF}} | | Can be used to encrypt config file data |
| {{TripleDESCrypto}} | Class | {{PBECrypto}} | {{CryptoIF}} | | Can be used to encrypt config file data |
| {{KeyGenCrypto}} | Class | {{Crypto}} | {{CryptoIF}} | | |
| {{AESCrypto}} | Class | {{KeyGenCrypto}} | {{CryptoIF}} | | |

To use a Crypto within the Framework, for encrypting a Password, only the Password Based Encryption (PBE) classes can to be used. An *Encryption* Element needs to be created in the *Security* Element:

{code:xml}
<Security>
<Encryptions>
<Encryption id="PBEWithMD5AndDES">
<Properties>
<Property name="crypto.classname" value="org.openptk.crypto.DESCrypto"/>
</Properties>
</Encryption>
</Encryptions>
</Security>
{code}

The Encryption *id* needs to set as a Property for all *Contexts* or within each *Context*

{code:xml}
<Contexts>
<Properties>
<Property name="context.default" value="Person-SunIdm-SPML1"/>
<Property name="context.classname" value="org.openptk.provision.common.TimeoutContext"/>
<Property name="security.encryption" value="PBEWithMD5AndDES"/>
...
</Properties>
<Context ...>
</Context>
...
</Contexts>
{code}

[Top|#top]
----

h2. Util Package

The package {{org.openptk.util}} was created to contain various helper classes that can be applicable to multiple parts of the OpenPTK.

h3. {{RandomData}}

This class will generate a random String to the specified length. The String will contain characters from the following set of data:
* \[a-z\]
* \[A-Z\]
* \[0-9\]

It has one static method {{getString(int)}} that requires an {{int}} argument to specify the length of the random string.

API usage:
{code}
String random = org.openptk.util.RandomData.getString(8);
{code}

CLI usage:
{code}
java -cp ./build/package/OpenPTK/Framework/Provision-Framework.jar org.openptk.util.RandomData 24
McP7NoBoPTPHrJZLfXsnDEod
{code}

h3. {{ptkadmin}}

A command-line utility that provides various administrative capabilities. Use the following syntax to access the utility:

{code}
java -cp Provision-Framework.jar org.openptk.util.ptkadmin
{code}

It supports the following options:

| -h | help information |
| -e <password> | encrypt the clear text password |

{code}
java -cp Provision-Framework.jar org.openptk.util.ptkadmin -e password
EnespBAb/hMwNylyxlh0jw==
{code}

h3. {{UniqueId}}

Uses the {{java.util.UUID}} to generate a Universal Unique ID. There is a {{static main}} method so that it can be call from a command-line:

{code}
java -cp Provision-Framework.jar org.openptk.util.UniqueId
{code}

There's also a {{static getUniqueId()}} method that can be used from other Java code. It returns a String with the unique id.

{code}
String myUid = org.openptk.util.UniqueId.getUniqueId()
{code}

[Top|#top]
----

h1. Service Tier

h2. Service / Operation

h3. New Architecture

Prior to Release 2.0, OpenPTK's Service architecture is used to define and implement access to a provisioning backing-store (SPML, JNDI, LDAP). A Service provided an implementation of some or all of the OpenPTK Framework "operations" (Create, Read, Update, Delete, ...). All "operations" when to the same backing-store.

In this new release (2.x), OpenPTK's Service architecture separates the definition and implementation of access to the various provisioning backing-stores.

!ProvisionFW_Arch_Contxt_2.png|align=centre!

With Release 2.0, a *Service* can be configured where each *Operation* could reference a different backing-store. For example, a *Service*, related to a *Context* could have its CREATE, UPDATE, and DELETE Operations use SPML, while its READ and SEARCH Operations use JNDI.

!ProvisionFW_Arch_Contxt_Hybrid.png|align=centre!

[Top|#top]
----

h2. Password Change / Password Reset

All of the {{Services}} / {{Operations}} have been updated to support the PWDCHANGE and PWDRESET {{Operations}}. Back-end Service repositories that do not provide a native facility for management will implement these Operations by using an {{UPDATE}} Operation to a specific Attribute (SPML/SPE, JNDI and JDBC). A random password generation utility was created to support the PWDRESET Operations.

[Top|#top]
----


h2. SPML 2.0 Operations

[Top|#top]
----

h1. Packaging

h2. Java class namespace

h2. Distribution

[Top|#top]
----