{anchor:top}
This document will cover the new features contained within this release
{toc}
h1. New features:
Following features and enhancements are new in Release 1.1:
* New forgotten Password Architecture
* Configurable Timeouts
* Dynamic Attributes
* SPML Client-side Authentication
* Disable mis-configured Services and Contexts
* Remove Dependancies On "default" Context
* Added support for SPML objectclasses
* Context ID added to messages
[Top|#top]
----
h2. New Forgotten Password Architecture:
*Problem*
The previous release used a two-step process to handle forgotten password. The first step called the _Service_ to obtain the Forgotten Question. These questions were then presented to the user (UML / Portlets / Samples) and the user would provide the answers. The second step involved contacting the _Service_ a second time to obtain the answers to the questions. Then the users responses were compared with the second response. This was fine as along as the the first and second calls to the _Service_ always returned the same related data. This did not work when the _Service_ randomly returned different questions/answers each time it was contacted. This was the case with the Sun Identity Manager, it was configured to randomly return different questions/answers.
*Solution*
The Framework was modified. When the Consumer-Tier application (UML / Portlets / Samples) now initiate the forgotten password process, the Framework makes a single call to the _Service_ and it stores both the questions and answers internally. When the user responds to the questions, the APIs compare the users input to the answers that are internally stored.
[Top|#top]
----
h2. Configurable Timeouts:
*Problem*
Some _Operations_ for certain _Services_ were getting timeouts from the infrastructure. Handling of the timeouts, and related Exceptions were not ideal.
*Solution*
The Framework was enhanced to support the configurable timeouts per _Operation_, per _Service_. Configuring the timeout values is done by setting values in the {{openptk.xml}} file. If no default timeout is set, then 5000 milliseconds will be used. This new feature uses the Java concurrent facility to implement timeouts.
To enable this feature, the {{classname}} must be set to {{org.openptk.provision.common.TimeoutContext}} for each _Context_.
{code:xml}
<Context id="Person-SPML" classname="org.openptk.provision.common.TimeoutContext">
<Subject id="Person"/>
<Service id="SPML">
<Properties>
<Property name="url" value="http://sample.openptk.org:80/idm/servlet/rpcrouter2"/>
<Property name="objectclass" value="user"/>
</Properties>
</Service>
<Query type="EQ" name="MemberObjectGroups" value="All People"/>
</Context>
{code}
To set a _Service_ timeout value that will be inherited by all of its _Operations_, set a _Service_ level _Property_
{code:xml}
<Service id="SPML" ...>
<Properties>
<Property name="timeout" value="5000"/>
...
</Service>
{code}
To set a _Operation_ timeout value (within a _Service_), add the {{timeout}} argument to the _Operation_.
{code:xml}
<Service id="SPML" ...>
<Properties>
<Property name="timeout" value="5000"/>
...
</Properties>
<Operations>
<Operation type="create" />
<Operation type="read" timeout="2000"/>
<Operation type="update"/>
<Operation type="delete"/>
<Operation type="search" timeout="2000"/>
<Operation type="passwordChange" timeout="8000"/>
<Operation type="passwordReset" timeout="8000"/>
</Operations>
...
</Service>
{code}
In the above example, the follow logic will be used ...
* The default timeout for _Service_ will be *5 seconds*.
* The {{create}} Operation_ will inherit the default value, *5 seconds*.
* The {{read}} _Operation_ will use a smaller value, *2 seconds*.
* The {{update}} _Operation_ will inherit the default value, *5 seconds*.
* The {{delete}} _Operation_ will inherit the default value, *5 seconds*.
* The {{read}} _Operation_ will use a smaller value, *2 seconds*.
* The {{passwordChange}} _Operation_ will use a larger value, *8 seconds*.
* The {{passwordReset}} _Operation_ will use a larger value, *8 seconds*.
[Top|#top]
----
h2. Dynamic attribute definition:
*Problem*
The _Attributes_ defined in a given _Subject_ and a given _Service_ may not match. There were runtime issues when a _Service_ would define a given _Attribute_ that the _Subject_ did not have. This issue led to the creation of multiple (similar) _Subjects_ that matched a given _Service_. This quickly became difficult to manage and limited the idea of re-useable _Subjects_.
*Solution*
The Framework, during initialization, will evaluate the defined _Contexts_ and determine the "run time" set of available _Attributes_. The _Subject_ (for a given _Context_) may have 15 _Attributes_ defined. The _Service_ (for the same _Context_) may only have 10 _Attributes_ defined. At most, the _Context_ could not have any more than 10 _Attributes_ available at run-time. The actual available _Attributes_ for the _Context_ will be the "intersection" of the defined _Service_ _Attributes_ and _Subject_ _Attributes_. Only the _Attributes_ (names) that match between the _Service_ and _Subject_ will be available to the _Context_.
[Top|#top]
----
h2. SPML Client-side Authentication:
*Problem*
The SPML Service supports the standard SPML APIs. This API does not address access control (Authentication) to the SPML interface. Sun's Identity Manager supports the standard SPML API by storing the credentials of a _"proxy user"_ on the deployed server. For many organizations this is a security issue. There are requirements to support client-side authentication the the SPML service.
*Solution*
Sun's Identity Manager implements the standard SPML capabilities and offers an extension this standard by providing a SPML implementation that supports client-side authentication. A new _Service_ was created that sub-classes the SPML _Service_. The new _Service_ is called {{org.openptk.provision.spi.SpmlSunService}}. To leverage this feature create a _Service_ that uses this class:
{code:xml}
<Service id="SPML-Sun"
classname="org.openptk.provision.spi.SpmlSunService"
description="SJS Identity Manager Lighthouse client"
sort="lastname,firstname">
...
</Service>
{code}
Configure a _Context_ to use the _Service_ and then set _Properties_ that define the client-side "proxy-user" accountId and Password:
||Name||Value||
|user.name|SPML-Proxy|
|user.password|password|
{code:xml}
<Context id="Person-SPML-Sun" classname="org.openptk.provision.common.TimeoutContext">
<Service id="SPML-Sun">
<Properties>
<Property name="user.name" value="SPML-Proxy"/>
<Property name="user.password" value="password"/>
...
</Properties>
</Service>
...
</Context>
{code}
[Top|#top]
----
h2. Disable mis-configured Services and Contexts:
*Problem*
The Framework configuration file {{(openptk.xml)}} can be modified to include collections of _Services_ and _Subjects_ that are combined to create multiple _Contexts_. It was possible to configure _Services_ and _Contexts_ that could not be used (for various reasons). Run time errors occurred when applications tried to access an invalid _Context_.
*Solution*
During initialization of the Framework, _Services_ and _Contexts_ are checked to ensure that their Framework and Service classes can be found and instantiated. If either a _Service_ or _Context_ does not pass basic requirements, the _Service_ and/or _Context_ will not be created and thus unavailable to applications. *Note*: These tests do not validate / check the actual "back end" infrastructure. A _Context_ and _Service_ can still be initiated and have a related infrastructure that is off-line.
[Top|#top]
----
h2. Remove Dependancies On "default" Context:
*Problem*
The Framework used the "default" _Context_ for some core internal feature ... it was assumed that the "default" _Context_ would always be properly configured and available. When the [Disable mis-configured Services and Contexts|#DisableServicesContexts] feature was added, it was possible that the "default" _Context_ may not get initiated. Without a "default" _Context_, the Framework would not start.
*Solution*
The Framework's core features were re-written to no longer depend on a "default" _Context_.
[Top|#top]
----
h2. Support for SPML objectclasses:
*Problem*
The Framework did not explicitly specify and objectclass for SPML operations, and therfore, used the "default" SPML objectclass defined on ther server. This did not allow the ability to operate on objectclasses other than the default in the openptk through SPML (examples: user, speperson, BasicUser, role).
*Solution*
The SPML Service was enhanced to no longer depend on a "default" SPML objectclass. If an objectclass property is supplied in the Context definition in the openptk.xml file, it will be used for all operations on that context. Note: This is not used for the change password and reset password operations since they are extended operations and do not use the objectclass. For this reason, the speperson objectclass does not currently support change password and reset password. A subclass of the SPML service will be created for a future release which will support SPE change and reset password.
[Top|#top]
----
h2. Context ID added to messages:
*Problem*
Messages sent to Consumer Tier applications and written to log files do not contain information about the Context (context id). It was hard to debug problems that are Context specific issues.
*Solution*
The Context ID has been added to many of the debug / info methods that output information. The Context ID will make it easier to determine if a problem might be related to the Context that is being used.
[Top|#top]
----
h1. Resolved Issues:
|| Description || Issue Id ||
| Portlets session state being shared | [5|https://openptk.dev.java.net/issues/show_bug.cgi?id=5] [13|https://openptk.dev.java.net/issues/show_bug.cgi?id=13] |
| Portlets and J2ee security | [6|https://openptk.dev.java.net/issues/show_bug.cgi?id=6] |
| Create an LDAP Service | [8|https://openptk.dev.java.net/issues/show_bug.cgi?id=8] |
| Create a JDBC service interface | [10|https://openptk.dev.java.net/issues/show_bug.cgi?id=10] |
| ability to flexibly convert portal user id to openptk id | [12|https://openptk.dev.java.net/issues/show_bug.cgi?id=12] |
| Forgotten questions are not questions | [16|https://openptk.dev.java.net/issues/show_bug.cgi?id=16] |
| use response.setRenderParameter() | [18|https://openptk.dev.java.net/issues/show_bug.cgi?id=18] |
| Person and Role classes in api should be non-public | [24|https://openptk.dev.java.net/issues/show_bug.cgi?id=24] |
| update Configuration to support different types of Subjects | [26|https://openptk.dev.java.net/issues/show_bug.cgi?id=26] |
| Setting SPML proxy user in Configuration XML file | [31|https://openptk.dev.java.net/issues/show_bug.cgi?id=31] |
| Operation time-outs, per service / operation | [32|https://openptk.dev.java.net/issues/show_bug.cgi?id=32] |
| Base JNDI/LDAP operations off of BaseDN | [34|https://openptk.dev.java.net/issues/show_bug.cgi?id=34] |
| Context Subject Attributes overrides configuration | [36|https://openptk.dev.java.net/issues/show_bug.cgi?id=36] |
| Services should test for Casting of attributes | [38|https://openptk.dev.java.net/issues/show_bug.cgi?id=38] |
| Make use of PTK_CONFIG Environment Variable for CLI | [42|https://openptk.dev.java.net/issues/show_bug.cgi?id=42] |
| Additional entries returned from JDBC service | [44|https://openptk.dev.java.net/issues/show_bug.cgi?id=44] |
| Forgotten Password fails | [47|https://openptk.dev.java.net/issues/show_bug.cgi?id=47] |
| Forgotten Password Enhancements for single Service call | [48|https://openptk.dev.java.net/issues/show_bug.cgi?id=48] |
| Startup should skip Services/Contexts not instantiated | [49|https://openptk.dev.java.net/issues/show_bug.cgi?id=49] |
| Dynamic attribute mapping for the Contexts | [51|https://openptk.dev.java.net/issues/show_bug.cgi?id=51] |
| CLI support for setting multivalued attributes | [58|https://openptk.dev.java.net/issues/show_bug.cgi?id=58] |
[Top|#top]
----
h1. Known Issues:
|| Description || Issue Id ||
| debug/info/audit entries in log show up multiple times | [15|https://openptk.dev.java.net/issues/show_bug.cgi?id=15] |
| Add support for Windows for CLI | [23|https://openptk.dev.java.net/issues/show_bug.cgi?id=23] |
| Null attributes in Transformation throw exception | [52|https://openptk.dev.java.net/issues/show_bug.cgi?id=52] |
| Catch exceptions and provide error output | [54|https://openptk.dev.java.net/issues/show_bug.cgi?id=54] |
[Top|#top]
----
This document will cover the new features contained within this release
{toc}
h1. New features:
Following features and enhancements are new in Release 1.1:
* New forgotten Password Architecture
* Configurable Timeouts
* Dynamic Attributes
* SPML Client-side Authentication
* Disable mis-configured Services and Contexts
* Remove Dependancies On "default" Context
* Added support for SPML objectclasses
* Context ID added to messages
[Top|#top]
----
h2. New Forgotten Password Architecture:
*Problem*
The previous release used a two-step process to handle forgotten password. The first step called the _Service_ to obtain the Forgotten Question. These questions were then presented to the user (UML / Portlets / Samples) and the user would provide the answers. The second step involved contacting the _Service_ a second time to obtain the answers to the questions. Then the users responses were compared with the second response. This was fine as along as the the first and second calls to the _Service_ always returned the same related data. This did not work when the _Service_ randomly returned different questions/answers each time it was contacted. This was the case with the Sun Identity Manager, it was configured to randomly return different questions/answers.
*Solution*
The Framework was modified. When the Consumer-Tier application (UML / Portlets / Samples) now initiate the forgotten password process, the Framework makes a single call to the _Service_ and it stores both the questions and answers internally. When the user responds to the questions, the APIs compare the users input to the answers that are internally stored.
[Top|#top]
----
h2. Configurable Timeouts:
*Problem*
Some _Operations_ for certain _Services_ were getting timeouts from the infrastructure. Handling of the timeouts, and related Exceptions were not ideal.
*Solution*
The Framework was enhanced to support the configurable timeouts per _Operation_, per _Service_. Configuring the timeout values is done by setting values in the {{openptk.xml}} file. If no default timeout is set, then 5000 milliseconds will be used. This new feature uses the Java concurrent facility to implement timeouts.
To enable this feature, the {{classname}} must be set to {{org.openptk.provision.common.TimeoutContext}} for each _Context_.
{code:xml}
<Context id="Person-SPML" classname="org.openptk.provision.common.TimeoutContext">
<Subject id="Person"/>
<Service id="SPML">
<Properties>
<Property name="url" value="http://sample.openptk.org:80/idm/servlet/rpcrouter2"/>
<Property name="objectclass" value="user"/>
</Properties>
</Service>
<Query type="EQ" name="MemberObjectGroups" value="All People"/>
</Context>
{code}
To set a _Service_ timeout value that will be inherited by all of its _Operations_, set a _Service_ level _Property_
{code:xml}
<Service id="SPML" ...>
<Properties>
<Property name="timeout" value="5000"/>
...
</Service>
{code}
To set a _Operation_ timeout value (within a _Service_), add the {{timeout}} argument to the _Operation_.
{code:xml}
<Service id="SPML" ...>
<Properties>
<Property name="timeout" value="5000"/>
...
</Properties>
<Operations>
<Operation type="create" />
<Operation type="read" timeout="2000"/>
<Operation type="update"/>
<Operation type="delete"/>
<Operation type="search" timeout="2000"/>
<Operation type="passwordChange" timeout="8000"/>
<Operation type="passwordReset" timeout="8000"/>
</Operations>
...
</Service>
{code}
In the above example, the follow logic will be used ...
* The default timeout for _Service_ will be *5 seconds*.
* The {{create}} Operation_ will inherit the default value, *5 seconds*.
* The {{read}} _Operation_ will use a smaller value, *2 seconds*.
* The {{update}} _Operation_ will inherit the default value, *5 seconds*.
* The {{delete}} _Operation_ will inherit the default value, *5 seconds*.
* The {{read}} _Operation_ will use a smaller value, *2 seconds*.
* The {{passwordChange}} _Operation_ will use a larger value, *8 seconds*.
* The {{passwordReset}} _Operation_ will use a larger value, *8 seconds*.
[Top|#top]
----
h2. Dynamic attribute definition:
*Problem*
The _Attributes_ defined in a given _Subject_ and a given _Service_ may not match. There were runtime issues when a _Service_ would define a given _Attribute_ that the _Subject_ did not have. This issue led to the creation of multiple (similar) _Subjects_ that matched a given _Service_. This quickly became difficult to manage and limited the idea of re-useable _Subjects_.
*Solution*
The Framework, during initialization, will evaluate the defined _Contexts_ and determine the "run time" set of available _Attributes_. The _Subject_ (for a given _Context_) may have 15 _Attributes_ defined. The _Service_ (for the same _Context_) may only have 10 _Attributes_ defined. At most, the _Context_ could not have any more than 10 _Attributes_ available at run-time. The actual available _Attributes_ for the _Context_ will be the "intersection" of the defined _Service_ _Attributes_ and _Subject_ _Attributes_. Only the _Attributes_ (names) that match between the _Service_ and _Subject_ will be available to the _Context_.
[Top|#top]
----
h2. SPML Client-side Authentication:
*Problem*
The SPML Service supports the standard SPML APIs. This API does not address access control (Authentication) to the SPML interface. Sun's Identity Manager supports the standard SPML API by storing the credentials of a _"proxy user"_ on the deployed server. For many organizations this is a security issue. There are requirements to support client-side authentication the the SPML service.
*Solution*
Sun's Identity Manager implements the standard SPML capabilities and offers an extension this standard by providing a SPML implementation that supports client-side authentication. A new _Service_ was created that sub-classes the SPML _Service_. The new _Service_ is called {{org.openptk.provision.spi.SpmlSunService}}. To leverage this feature create a _Service_ that uses this class:
{code:xml}
<Service id="SPML-Sun"
classname="org.openptk.provision.spi.SpmlSunService"
description="SJS Identity Manager Lighthouse client"
sort="lastname,firstname">
...
</Service>
{code}
Configure a _Context_ to use the _Service_ and then set _Properties_ that define the client-side "proxy-user" accountId and Password:
||Name||Value||
|user.name|SPML-Proxy|
|user.password|password|
{code:xml}
<Context id="Person-SPML-Sun" classname="org.openptk.provision.common.TimeoutContext">
<Service id="SPML-Sun">
<Properties>
<Property name="user.name" value="SPML-Proxy"/>
<Property name="user.password" value="password"/>
...
</Properties>
</Service>
...
</Context>
{code}
[Top|#top]
----
h2. Disable mis-configured Services and Contexts:
*Problem*
The Framework configuration file {{(openptk.xml)}} can be modified to include collections of _Services_ and _Subjects_ that are combined to create multiple _Contexts_. It was possible to configure _Services_ and _Contexts_ that could not be used (for various reasons). Run time errors occurred when applications tried to access an invalid _Context_.
*Solution*
During initialization of the Framework, _Services_ and _Contexts_ are checked to ensure that their Framework and Service classes can be found and instantiated. If either a _Service_ or _Context_ does not pass basic requirements, the _Service_ and/or _Context_ will not be created and thus unavailable to applications. *Note*: These tests do not validate / check the actual "back end" infrastructure. A _Context_ and _Service_ can still be initiated and have a related infrastructure that is off-line.
[Top|#top]
----
h2. Remove Dependancies On "default" Context:
*Problem*
The Framework used the "default" _Context_ for some core internal feature ... it was assumed that the "default" _Context_ would always be properly configured and available. When the [Disable mis-configured Services and Contexts|#DisableServicesContexts] feature was added, it was possible that the "default" _Context_ may not get initiated. Without a "default" _Context_, the Framework would not start.
*Solution*
The Framework's core features were re-written to no longer depend on a "default" _Context_.
[Top|#top]
----
h2. Support for SPML objectclasses:
*Problem*
The Framework did not explicitly specify and objectclass for SPML operations, and therfore, used the "default" SPML objectclass defined on ther server. This did not allow the ability to operate on objectclasses other than the default in the openptk through SPML (examples: user, speperson, BasicUser, role).
*Solution*
The SPML Service was enhanced to no longer depend on a "default" SPML objectclass. If an objectclass property is supplied in the Context definition in the openptk.xml file, it will be used for all operations on that context. Note: This is not used for the change password and reset password operations since they are extended operations and do not use the objectclass. For this reason, the speperson objectclass does not currently support change password and reset password. A subclass of the SPML service will be created for a future release which will support SPE change and reset password.
[Top|#top]
----
h2. Context ID added to messages:
*Problem*
Messages sent to Consumer Tier applications and written to log files do not contain information about the Context (context id). It was hard to debug problems that are Context specific issues.
*Solution*
The Context ID has been added to many of the debug / info methods that output information. The Context ID will make it easier to determine if a problem might be related to the Context that is being used.
[Top|#top]
----
h1. Resolved Issues:
|| Description || Issue Id ||
| Portlets session state being shared | [5|https://openptk.dev.java.net/issues/show_bug.cgi?id=5] [13|https://openptk.dev.java.net/issues/show_bug.cgi?id=13] |
| Portlets and J2ee security | [6|https://openptk.dev.java.net/issues/show_bug.cgi?id=6] |
| Create an LDAP Service | [8|https://openptk.dev.java.net/issues/show_bug.cgi?id=8] |
| Create a JDBC service interface | [10|https://openptk.dev.java.net/issues/show_bug.cgi?id=10] |
| ability to flexibly convert portal user id to openptk id | [12|https://openptk.dev.java.net/issues/show_bug.cgi?id=12] |
| Forgotten questions are not questions | [16|https://openptk.dev.java.net/issues/show_bug.cgi?id=16] |
| use response.setRenderParameter() | [18|https://openptk.dev.java.net/issues/show_bug.cgi?id=18] |
| Person and Role classes in api should be non-public | [24|https://openptk.dev.java.net/issues/show_bug.cgi?id=24] |
| update Configuration to support different types of Subjects | [26|https://openptk.dev.java.net/issues/show_bug.cgi?id=26] |
| Setting SPML proxy user in Configuration XML file | [31|https://openptk.dev.java.net/issues/show_bug.cgi?id=31] |
| Operation time-outs, per service / operation | [32|https://openptk.dev.java.net/issues/show_bug.cgi?id=32] |
| Base JNDI/LDAP operations off of BaseDN | [34|https://openptk.dev.java.net/issues/show_bug.cgi?id=34] |
| Context Subject Attributes overrides configuration | [36|https://openptk.dev.java.net/issues/show_bug.cgi?id=36] |
| Services should test for Casting of attributes | [38|https://openptk.dev.java.net/issues/show_bug.cgi?id=38] |
| Make use of PTK_CONFIG Environment Variable for CLI | [42|https://openptk.dev.java.net/issues/show_bug.cgi?id=42] |
| Additional entries returned from JDBC service | [44|https://openptk.dev.java.net/issues/show_bug.cgi?id=44] |
| Forgotten Password fails | [47|https://openptk.dev.java.net/issues/show_bug.cgi?id=47] |
| Forgotten Password Enhancements for single Service call | [48|https://openptk.dev.java.net/issues/show_bug.cgi?id=48] |
| Startup should skip Services/Contexts not instantiated | [49|https://openptk.dev.java.net/issues/show_bug.cgi?id=49] |
| Dynamic attribute mapping for the Contexts | [51|https://openptk.dev.java.net/issues/show_bug.cgi?id=51] |
| CLI support for setting multivalued attributes | [58|https://openptk.dev.java.net/issues/show_bug.cgi?id=58] |
[Top|#top]
----
h1. Known Issues:
|| Description || Issue Id ||
| debug/info/audit entries in log show up multiple times | [15|https://openptk.dev.java.net/issues/show_bug.cgi?id=15] |
| Add support for Windows for CLI | [23|https://openptk.dev.java.net/issues/show_bug.cgi?id=23] |
| Null attributes in Transformation throw exception | [52|https://openptk.dev.java.net/issues/show_bug.cgi?id=52] |
| Catch exceptions and provide error output | [54|https://openptk.dev.java.net/issues/show_bug.cgi?id=54] |
[Top|#top]
----