Revision History
This DocumentThis document provides architectural information related to Project Open Provisioning Toolkit (OpenPTK). The OpenPTK is used to build custom end-user provisioning interfaces that leverage commercial user provisioning solutions. Related DocumentsProject OpenPTK includes a collection of related documents to assist teams that want to:
Introduction:Project Open Provisioning ToolKit (OpenPTK) contains the core infrastructure, service modules and sample applications. Core Infrastructure:The core infrastructure is based on a three tier model; Consumer Tier, Framework Tier and Service Tier.
Service Modules:Project OpenPTK is designed to support multiple different provisioning solutions, through the use of a Service Provider Interface (SPI). A given provisioning solution can be support by implementing the Service Tier's SPI. The following Service Implementation are included:
Sample Applications:A number of sample application are provide. These samples applications demonstrate various capabilities:
Project OpenPTK is a set of tools that Web developers and Java developers can use to create custom identity focused applications . Project OpenPTK provides an abstraction to the back-end services. Developers don't need to worry about the details of a specific provisioning interface. Project OpenPTK allows the developer to focus on the end-user (presentation tier) interface of their application. Project OpenPTK's Client Tier provides interfaces that use abstract representations of Identity Subjects (e.g. People). Project OpenPTK is designed using a messaging architecture where requests/responses are passed from the Client Tier, over the network (using REST/JSON/XML) to the Server Tier, through the Framework Tier, to the Service Tier, and back again. The Server Tier manages the Client/User Session and handles the processing of REST/JSON/XML requests and responses. The Framework Tier handles the incoming messages (Requests), sends them to the configured back-end Service, and handles the return of messages (Responses). Web developers and Portal developers can leverage the Client Tier's Java Server Pages (JSP) Tag Library to easily implement provisioning functions. Java developers can directly access the Client Tier's Java API. Applications built using the Client Tier interfaces are separated from the actual provisioning back-end implementation. A single application can be built that uses one or more back-end Services. Java developers can create new (or extend) Services to support specific back-end provisioning requirements. Again, the end-user application uses the Consumer Tier, and can be easily re-configured to use other Services as they become available. Modules
Tests:
PackagingThe following diagram illustrates the dependency between JAR files, applications and samples. ![]() Base
Framework
Server
Service-JDBC
Service-JNDI
Service-SPML
Service-SPML2
Client
Taglib
UML
Portlets
SOAP-WS
Client Tier:Project OpenPTK's Client Tier provides a collection of utilities, services and APIs that communicate with the Server Tier (using REST/JSON/XML). The Client Tier provides a Java Server Pages (JSP) Tag Library (taglib) that is used by Web page designers to perform provisioning tasks. A set of Java APIs are exposed at this tier which allows the Java developer to leverage Project OpenPTK. JSP Tag Library Interface:A web-site developers usually focus on the user experience, site navigation and the applications "look and feel". One way to access Java APIs are to insert actual Java code into a Java Server Page (JSP). This is not considered to be a "best practice", it merges complex business/technical logic into the Presentation Tier (HTML/JSP). This makes the application hard to maintain and some Web developers may not be comfortable having Java code embedded within a web page. Project OpenPTK provides a standards-based Java Server Pages (JSP) Tag Library for performing provisioning tasks. Instead of placing complex Java code in a web-page, simple XML-style tags are used. Web developers that have used other JSP Taglibs, like the Java Standard Tag Library (JSTL), will be comfortable using Project OpenPTK's taglib. All of the tags are implemented in the org.openptk.taglib Java package. The diagram below lists all the tags in the library. Each tag sub-classes a base class called ProvisionTag. The ProvisionTag abstract class defines a common set of variables and methods that are used by all of the tags. The ProvisionTag supports the JSP taglib architecture by extending the SimpleTagSupport class. Developers that want to create new provisioning tags should extend the ProvisionTag class. See the JSP Tag Library Guide for details. Command Line Interface:The provisioning command line interface (CLI) is a Java application that utilizes Project OpenPTK's Consumer Tier Java API. The provisioning CLI is a single command that performs basic provisioning operations: OpenPTK CLI ptk -h Usage: ptk <action> [global_options] [action_options] The accepted values for action are: search Search the service based on query read Read the service for particular entry create Create entry on the service update Update entry on the service delete Delete entry on the service config Conguration Utilities For more info on each action and options, use help Example: ptk search -h The accepted values for global_options are: -C <context> -- Context to use. ptk config list-contexts for help -c <config_file> -- Configuration File URL or File (xml) Optionally set environment variable PTK_CONFIG -h -- Show usage information. These CLI tool can be used interactively or within operating system scripting languages to automate provisioning tasks. Java Application Programing Interface:There are situations where an End-User application needs to communicate directly with a Java API. The developer of a Java Swing-based or command-line application can use Project OpenPTK's Consumer Tier, Java APIs to perform provisioning operations. Java applications interact with Project OpenPTK's Consumer Tier primarily through the Subject class. The Subject is created through the use of a configuration object. The Configuration object will initialize support utilities (logging and debugging), start the configured Service Tier and handle the processing of Input / Output objects with the Subject. The diagram below outlines the interaction of Project OpenPTK's Java Interface. Project OpenPTK's Java API uses the following steps:
// ptk.xml, Project OpenPTK's configuration file Configuration cfg = new Configuration("openptk.xml");
SubjectIF subject = cfg.getContextSubject(); Input input = new Input(); input.addAttribute("firstname","Bob"); input.addAttribute("lastname","Smith");
Output output = subject.doCreate(Input);
output.getStatus(); The Project OpenPTK Development Guide contains a detailed example of how to use the Consumer Tier Java APIs. SOAP-based Web Service:A SOAP-based Web Service (SOAP-WS) example was built using NetBeans and JAX-WS 2.x annotation and demonstrated how to expose OpenPTK functionality via WSDL/SOAP/XML interface. The SOAP-WS example uses the Client Tier Java API to implement provisioning tasks. JSR-168 Portlet Interface:The sample Provisioning Portlets implement the JSR-168 Portlets interface by extending the standard GenericPortlet Java class. Three sample JSR-168 Portlets are provided which demonstrate different provisioning functions.
Server Tier:User Interface:Engine:Session:Framework Tier:The Framework Tier provides core capabilities that are used to manage the interaction between the Consumer Tier and the Service Tier. The Framework Tier provides:
The Framework Tier contains the following Java packages The Common package:org.openptk.provision.common Component:The Component class is a foundation class that is used as a base-class more many of the other classes within the OpenPTK. The Component class provides many convenient attributes with related getter/setter methods:
A Component can have one of the following States:
The diagram below shows the states and their related transitions: Context:The abstract Context class (and it's default BasicContext class) provides the mechanism for associating a Consumer Tier with a Service Tier. The Context is responsible for starting, configuring and running a solution that is built using the OpenPTK. The Context leverages many of the features that it inherits from the Component class. A BasicContext reads configuration parameters from a Java properties file, initiates infrastructure processes (logging, debugging) starts the specified Service and processes Request/Response messages. Once started, the Context basically receives Requests from a Consumer, sends them to the Service, receives Responses from the Service and hands them back to the Consumer. The Context has the ability of recording Timestamps. If enabled, the Context will record when a Request is received and when the Response is returned. It's possible to create a new Context (or extend the BasicContext) to support more robust capabilities like connection retries, HA functionality and load-balancing. Request:The Request class is an extension of the Component class. A Request object represents in "in-bound" provisioning operation. The Request object must contain a "type" setting. Valid types include:
The Request will also contain a Subject. The Subject is actually a Component object that contains information need to support the particular operation. The illustration below is an example of a simple Request that will instruct the Context/Service to perform a Search operation: Response:The Response class is an extension of the Component class. A Response object represents the results of a provisioning operation. The returned Response object will contain important meta information about the provisioning operation:
The Response object will contain successful provisioning operation data in one or more related Components. The components are accessible through the response.getResults() method which returns a List of Components. If configured, the Context will sort the results based on attributes defined in the properties file. The Response object will also contain the original Request object. The diagram below illustrates a Response object from a Search operation: The Debugging package:com.sun.idmkit.provision.debug Debugger:The Debugger provides a means to interrogate and dump information about Provision Toolkit objects. The Debugger objects knowns about the base Component class, the Context, Request and Response classes. The Debugger is designed to assist the developer and operator. When the state of a Component is needed, simply pass-it to the Debugger, it will determine what it is, extract information from the object and send it to the defined Logging facility. The Debugger is typically created in a Context where it can assist the Service, Request, Response and the Context. if ( request.isDebug() ) debug(request, callerId);
The Debugger class writes plain ascii data to the Logger facility. A sample of the output is below: Aug 15, 2006 2:53:07 PM com.sun.idmkit.provision.logging.AtomicLogger put FINEST: DebugRequest, callerId=BasicContext::execute() com.sun.idmkit.provision.common.Request Metadata: UniqueId=3583619 Category=request (3) Description=Provision Request: Read Sort=(not set) Status=(not set) State=Ready (2) Error=false Debug=true, Level=finest (4) Type=Read (2) Properties: (no properties) Items: (no items) Timestamps: (no timestamps) ----- BEGIN: Subject ----- com.sun.idmkit.provision.common.Component Metadata: UniqueId=jhancock Category=person (6) Description=Component: userdetail Sort=(not set) Status=Created: Tue Aug 15 14:53:07 CDT 2006 State=Ready (2) Error=false Debug=true, Level=finest (4) Properties: (no properties) Items: person.attribute.firstname person.attribute.lastname person.attribute.title person.attribute.fullname person.attribute.email person.attribute.phonework person.attribute.organization person.attribute.manager Timestamps: (no timestamps) ----- END: Subject ----- (No Conditions) The Debugger will only interrogate those objects that have the isDebug value set to true. DebugComponent:The DebugComponent class knows how to extract and dump the common information for any class that is either a Component or extends Component. The information extracted includes: Metadata:
Properties:
Items:
Timestamps:
Subject (a Component) DebugContext:The DebugContext class knows how to extract and dump specific information about the Context object. If the Context's debug level is set to "4", then the Context's Service information will be added to the Logging service. DebugRequest:The DebugRequest class knows how extract and dump specific information about the Request object. The extra information includes:
DebugResponse:The DebugResponse class knowns how to extract and dump specifc information about the Response object. The extra information includes:
The Logging Package:org.openptk.provision.logging INSERT LOGGIN ARCH DIAGRAM The Logging package provides a facility for recording audit, timestamps and debugging information. The Logging uses the Java Logging facility. The OpenPTK currently offers two Logger implementations:
Attribute Rules:When a Request is sent to the Service Tier, via the Context, the Service can contact a Model object to perform the derivation of attributes. Subject Properties: (attributes)
The Service can use a Model's Attributes and the Subject to obtain other required attributes such as UniqueId, Full Name and Email. Once the Model has been told what Attribute Rule (java class) to use for a give Attribute Name, the new attribute can be generated by providing the Model with the Subject information. The following Attribute Rules are available:
Custom Attribute Rules can be created by implementing the AttributeIF interface. The Service Package:org.openptk.provision.service The Service package contains an abstract class called Service. This class must be extended and implements the ServiceIF interface. This interface is what the Context uses to perform all of the back-end provisioning operations. The Service abstract class has implemented several "common" methods that will be needed by a Service that extends this class. The Service class provides the following capabilities:
When a Service is created (usually by the Context) it is given a set of Properties that contain Target specific information. This information can include connection data, meta data, operational data and attribute mapping data. Provisioning Methods:The Service's interface (ServiceIF) defines the methods that the actual Service must implement or can overload.
Attribute Translation:The Provisioning Toolkit can be used to perform provisioning operations on different Target systems. Each Target system may (probably does) have a specific schema for defining a Subjects (Person) attributes. For example, SPML uses "gn" to define a "first name", while LDAP uses "givenname" for the "first name". The OpenPTK uses an abstracted naming schema to define a Subjects attributes. The attribute names are abstracted so that the Consumer Tier of the OpenPTK only has to deal with a single set of attribute names. The Service (specifically an implementation) MUST perform the translation of attributes from the OpenPTK Framework schema to a native schema before performing a given operation. Then, when the operation is complete, the Service implementation must translate the native schema attributes back to the OpenPTK Framework schema. The attribute schema mapping is specified in a Properties file that is unique to a given service. Here is an example of an SPML schema mapping Properties file: person.attribute.uniqueid=uid person.attribute.firstname=gn person.attribute.lastname=sn person.attribute.title=title person.attribute.fullname=cn person.attribute.email=email person.attribute.password=password person.attribute.epassword=epassword person.attribute.phonework=telephone person.attribute.organization=organization person.attribute.manager=manager The abstract Service class has a method called translate() where you tell it which way to translate the provided Component, either Framework-to-Service or Service-to-Framework. Service Tier:The Service Tier is the "back-end" of the Open Provisioning Toolkit (OpenPTK) ... "where the rubber meets the road". A Service is a Java class that performs Target specific provisioning operations using the Targets Java APIs. A given Service must extend the OpenPTK Framework's Service class and implement the ServiceIF interface. See the "Service Package" section within the "Framework Tier" part of this document for details on the Service's capabilities. INSERT IMAGE OF SERVICE TIER ARCHITECTURE Service Provisioning Markup Language (SPML) Service:This Service implementation is based on the Service Provisioning Markup Language 1.0 as defined by the OASIS Provisioning Services Technical Committee (PSTC).
Java Naming Directory Interface (JNDI) Service:This Service implementation is based on the Java Naming and Directory Interface (JNDI) Service, part of the Java platform, providing applications based on Java technology with a unified interface to multiple naming and directory services. The JNDI Service leverages the following APIs to implement the Framework's provisioning operations:
Java DataBase Connectivity (JDBC) Service:This Service implementation is based on the Java DataBase Connective (JDBC) Service, part of the Java platform, providing applications based on Java technology with a unified interface to database services. The JDBC Service leverages the following APIs to implement the Framework's provisioning operations:
Appendix: Forgotten PasswordWhen a Consumer-Tier application (UML / Portlets / Samples) initiates 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.
|
Release 1.x >