Docs 2.0 What's New

This document will cover the new features contained within this release

Overview

Server deployment
RESTful interface
Client API
Security Model
Framework Enhancements
Updated Samples
Service Re-Design

Top

Architecture

Server

RESTful-based Web Service

  • Implemented using JAX-RS (Jersey)

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:

http://host:port/ProvisionService/ProvisionPerson?wsdl

Client

Command Line (console)

User Management Lite (UML)

JSR-168 Portlets

Top

Sample Applications

Command Line Interface

New search output format

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

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

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.

Notice

The actual use (or non-use) of the uniqueid is dependent on the configuration of the Context that is being used.

Top

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

Top

Java API

Some of the Java API Interfaces and Classes have changed.

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:

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

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

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

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

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>

Top

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>

Top

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/Framework/Provision-Framework.jar org.openptk.util.RandomData 24
McP7NoBoPTPHrJZLfXsnDEod

ptkadmin

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

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

It supports the following options:

-h help information
-e <password> encrypt the clear text password 
java -cp Provision-Framework.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()

Top

Service Tier

Service / Operation

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.

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.

Top

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

SPML 2.0 Operations

Top

Packaging

Java class namespace

Distribution

Top

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Sign up or Log in to add a comment or watch this page.


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