Release 2.x‎ > ‎

What's New

Release Notes

Feature List

RESTful-based Web Service

Server Tier

Framework Tier

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

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:

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

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

  • Property value arguments
  • Argument value arguments

Examples:

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

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

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. 

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

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

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.

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

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:

  1. Get the encrypted string that represents your password. Use the org.openptk.util.ptkadmin utility to generate the encrypted value.
  2. Configure an <Encryption ...> Element in the <Security> section of the configuration file.
  3. 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.
  4. Change the user.password Property in the <Defaults> or the <Connection> to be user.password.encrypted. Set the value to be output of the org.openptk.util.ptkadmin utility.
  5. The system will automatically look for the .encrypted value and decrypt it.

Setting the encrypted password in a Defaults Property:

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

Using the encrypted password in a Connection Property:

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

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

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.

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

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:

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

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

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

Util Package

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

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:

String random = org.openptk.util.RandomData.getString(8);

CLI usage:

$ java -cp ./build/package/OpenPTK/Base/openptk-base.jar \
           org.openptk.util.RandomData 32
QKBUobamQHtZdj0r3YWVq22yOJMpERuU

ptkadmin

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

java -cp openptk-base.jar org.openptk.util.ptkadmin

It supports the following options:

-help -h Display help information
-encrypt -e <password> encrypt the clear text password
-uuid -u generate a guid
-randomdata -r <#> generate ramdon data # characters long 
java -cp openptk-base.jar org.openptk.util.ptkadmin -e password
EnespBAb/hMwNylyxlh0jw==

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:

java -cp Provision-Framework.jar org.openptk.util.UniqueId

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

String myUid = org.openptk.util.UniqueId.getUniqueId()

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.

SPML 2.0 Operations

Packaging

Java class namespace

Distribution