Nsure® Identity Manager 2 (formerly DirXML®)
Driver Development Overview

Richard Matheson

DirXML Driver Engineering Manager

Novell, Inc.

rmatheson@novell.com

Session Roadmap

Identity Manager Overview

Identity Manager Architecture

Identity Manager Driver Overview

Identity Manager Driver Considerations

Identity Manager Driver Architecture

Conclusion

HR

ERP

Operating
System

Database

Mail

PBX

Directory

Islands of isolated data

Sharing data through an identity vault

HR

ERP

PBX

Directory

Mail

Operating
System

Database

Identity Manager

Identity Manager Architecture

Identity

Vault

DirXML

DirXML

Engine

Identity Manager

Driver

Shim

Policies

Policies

Subscriber Channel

Publisher Channel

Application

Novell

DirXML

Server

Identity Manager 2

Identity Manager Architecture
The Remote Loader

Identity

Vault

DirXML

DirXML

Engine

Identity Manager

Driver

Shim

Policies

Policies

Application

Novell

DirXML

Server

Remote

Loader

Shim

Remote

Loader

Service

Subscriber Channel

Publisher Channel

Identity Manager 2

Components of Identity Manager

Engine

eDirectory™ interface

Join engine

Driver Shim

XML interface

Application’s native interface

Subscriber and publisher channels

Filters manage flow in both directions

Policies may be applied differently to each channel

Identity Manager Engine

eDirectory interface

Supports loading of multiple drivers

Guaranteed delivery of eDirectory events

eDirectory event loop-back detection

Join engine

Handles data transformations

Rules processor

XSLT processor

Publisher and Subscriber channels

Publisher channel

Propagates events from the application to eDirectory

Subscriber channel

Propagates events from eDirectory to the application

Filters

Manage the flow of data on both channels

A list of desired classes and their attributes

Determines the authoritative source(s) of data

Publisher and Subscriber channels

What is a DirXML Driver

Data Pipe

DirXML Engine to target application

Operates on passed data

In general, doesn’t make synchronization decisions

Standard objects & Methods

Drivershim

Subscriber

Publisher

Required Driver Interfaces

DriverShim Interface

The DriverShim interface consists of five methods in Java and six methods in C++

DriverShim init — Performs channel-independent initialization

DriverShim getSubscriptionShim — Returns a reference (Java) or pointer (C++) to the object implementing the SubscriptionShim interface

Driver getPublicationShim — Returns a reference (Java) or pointer (C++) to the object implementing the PublicationShim interface

DriverShim shutdown — Notifies the driver to disconnect from the application, cleanup, and otherwise shutdown

DriverShim getSchema — Called to obtain a representation of the application schema

SubscriptionShim Interface

The SubscriptionShim interface consists of two methods

SubscriptionShim init — Performs subscriber channel specific initialization

SubscriptionShim execute — Accepts commands from the DirXML engine and executes those commands on the application

Execute method is inherited from the XmlCommandProcessor interface

PublicationShim Interface

The PublicationShim interface consists of two methods

PublicationShim init — Performs publisher channel specific initialization

PublicationShim start — Monitors the application and publishes application changes to the DirXML engine

XmlQueryProcessor Interface

The XmlQueryProcessor interface is required because it is a parameter to XMLCOMMANDPROCESSOR.EXECUTE

Used by the DirXML interface to query publisher when additional data is required to complete an operation

Passed to Subscriber.Execute to allow subscriber to query back into eDir.

Driver Overview

Driver Communication and threads

Two Channels of Communication

Subscriber = eDir -> App

Publisher = App -> eDir

Two Threads

Subscriber thread

Initializes DriverShim

Initializes SubscriberShim

Waits in engine for Subscriber events

Publisher Threads

Initializes Publisher

Publisher polls app on this thread

Driver Lifecycle Overview

2 Modes of operation

Schema query

Driver started explicitly to determine app schema

No synchronization possible

Normal synchronization

Once driver is started for synchronization the getSchema method won’t be called

Driver Lifecycle—Normal Sync

Subscriber thread

Driver constructed

Init called

getSubscriptionShim

getPublicationShim

Subscriber init

The Identity Manager engine calls subscriber’s execute method to request the drivers identity.

The Identity Manager engine calls subscriber’s execute method zero or more times

Engine calls shutdown

Publisher thread

Publisher init

Publisher start

Publisher sends updates to eDirectory

Publisher thread returns on notice

Driver Lifecycle—getSchema

Subscriber thread

Driver constructed

getSchema called with all initialization parameters

Driver is destroyed

Publisher thread

Not used

Driver Design Considerations

Research

Target application information

Approaches to building a driver

Driver Design Considerations

Research

XML

Parsing

DOM or SAX

XDS Libraries!

NDS.DTD

Policies

Policy Manager

XSLT & Stylesheets

What are the XDS Libraries?

Utility to aid Identity Manager driver developers.

Object-oriented DOM wrapper customized to
enforce the constraints of the XDS DTD.

Class library providing an intuitive API for XDS
document handling and driver parameter handling.
All documents and elements are represented with
a corresponding class.

What are XDS Libraries? (cont…)

Ensures XDS Documents created through it and
documents parsed by it conform to the constraints
described in the XDS DTD.

Designed to be a replacement form CommonDriverShim.jar.

XDS Libraries are NOT…

a replacement to standardized API’s such as DOM or SAX.

Fact: XDS Libraries utilize DOM to parse XDS documents.

Why XDS Libraries?

Increase driver development productivity

The product was designed to facilitate rapid
driver development by providing an OO intuitive
API for document handling and parameter handling.

More than 50% of existing driver code written
focused on the repetitive task of parsing and
validating a XDS document. The XDS Libraries API
prevents developers from performing the
redundant task of manually dissecting
XDS Documents.

Why XDSLib? (cont…)

Enhance driver stability

Eliminates variations in XDS document and
parameter handling between drivers which
ultimately reduces potential driver inconsistencies.

Increases driver robustness by protecting the
driver from invalid or malformed XDS documents
that may have been transformed by style
sheet processing.

XDSLib Class Naming Conventions

Each XDS Document and Element has a corresponding
XDSLib class.

All documents instantiated by the end user are
prefixed with “XDS”. All elements defined
in the XDS DTS are prefixed with “XDS”

Example:

XDS Document Tag XDSLib Classname

<add> XDSAddElement

<add-attr> XDSAddAttrElement

XDS Libraries Method Naming Convention

Attribute Method Naming Convention

Attributes are set and gotten.

Attribute methods follow the set and get
naming convention. set<attribute name>
or get<attribute name>

- e.g. setClassName

- e.g. getClassName

XDS Libraries Method Naming Convention
(cont…)

Node Method Naming Conventions

Nodes such as elements and text are
appended and extracted.

Element methods follow this naming convention:
append<tag name>Element or extract<tag name>
Element(s). Text is also appended and extracted:
appendText, extractText.

e.g. appendAddAttrElement

e.g. extractAddAttrElements

e.g. appendText

e.g. extractText

Utility Method Naming Conventions

Utility methods are not prefixed and do not
implement any particular naming convention
other than avoiding reserved prefixes

XDSLib Method Naming Conventions
(cont…)

End users only instantiate the 7 top level document
classes for document parsing or creation.

XDSInitDocument

XDSResultDocument

XDSSchemaResultDocument

XDSCommandDocument

XDSCommandResultDocument

XDSQueryDocument

XDSQueryResultDocument

After document instantiation, users use the element
append/extract and attribute get/set methods for
reading and writing.

Document classes are readable or writeable depending
on which constructor is used.

Document Classes

Document Class Coding Sample

{

XDSCommandDocument commands;

ListIterator c, addAttrs;

CommandElement command;

// Parse/validate command document; it may have been malformed or invalidated

// during style sheet processing

commands = new XDSCommandDocument(commandXML);

//initialize iterator for the document child elements

c = commands.childElements().listIterator();

… // iterate the child elements

while (c.hasNext()) {

command = (commandElement) c.next();

class commandClass = command.getClass();

// If the current child element is an add, extract the addattrElements

if (commandClass == XDSAddElement.class) {

addAttrs= (XDSAddElement)command.extractAddAttrElements().listIterator();

} // end if

} //end while

}

Parameter Handling

XDS Libraries provides classes to parse and validate
driver parameters.

Parameter validation is accomplished via constraints
defined by the driver developer.

Parameters may be constrained as required,
constrained by data type and constrained by value
using Java XDS Libraries.

C++ has limited functionality for parameter parsing
in initial release.

Parameter Handling Coding Example

subParams = new HashMap(NO_OF_PARAMS);

param = new Parameter(“server-id”, //tag name

“152.155.155.1”, //default value

DataType.STRING); //data type

subParams.put(param.tagName(), param);

param = new Parameter(“port-id”,

“15000”,

DataType.INT);

param.add(RangeConstraint.POSITIVE);

subParams.put(param.tagName(), param);

Where to get XDS Libraries?

Available in Novell NDK CD

Researching the Target Application

Access methods

Standards-based protocol

Proprietary API

Is it remotable?

Schema issues

Reading and writing information

Discovering changes in the application space

Authentication issues

Associations

What value uniquely identifies objects in the application space?

Researching the Target Application

Data synchronization and application behavior

In general, drivers are just data pipes

Don’t make decisions about data, just route it

Supporting an application may require more than
just moving data

Creation of system entities

Mailbox creation, for instance

Establishment of credentials on new system

Approaches to Building a Driver

Am I building for a specific case or for general reuse?

Custom behaviors modeled in code or XSLT?

Become an expert in the target application

Understanding of application data

Understanding of application behavior based on data

Understanding of user expectations

Mining changes from the application is the hardest part of driver development

Application Native Format

An NDS object is passed as XDS (XML representation of NDS object)

The driver must have application native format data to submit to the application

Schema mapping translates namespace

XSLT can transform XDS to another format

Driver can implement data translation for APIs

Application Integration Points

How can I get at the application data?

Protocol

Is the protocol standard?

Is it remotable?

Application Programming Interface (API)

Driver will be application-specific

Can I get change events?

Flat-file import/export mechanism

Unable to properly manage associations or queries

Platform and Language Choice

What language should I use?

What language best supports my application’s integration points?

XDS Helper libraries available for both Java and C++ on the NDK

Where can my driver run?

Drivers execute as part of Dhost

Can the driver securely bind remotely to the application?

Remote Loader solves driver remoteability!

Driver Architecture

Driver responsibilities

Deployment responsibilities

Required driver interfaces

Policies and stylesheets

Driver Responsibilities

Initialization and shutdown

Read application schema for Identity Manager engine

Translate XML from NDS (XDS) to app format

Identify changes in target application

Translate application native format into XDS

Process queries against application

Submit queries against eDirectory

Provide foreign key for driver associations

Requirements for ‘Production’ Drivers

Effective change event detection

Publish only changed attributes, if possible

Guaranteed delivery

Can’t drop events for the Publisher channel

Loopback detection

Prevents driver-caused changes from causing unnecessary replication traffic or erroneous data

Prefiltering publisher data

Prevents unnecessary traffic by only processing changes interesting to the driver

‘Production’ Drivers - cont.

Support for multiple running instances

Avoid static, global data

Support Remote Loader

Shouldn’t require code changes. Just validate the functionality.

Can cause configuration problems.

Filesystem parameters must be relative to the remote box

Stylesheets are evaluated on eDir. Be careful about using resources in stylesheets.

Driver identity query

In DirXML 1.1 the engine queries each driver for its identity and activation levels

‘Production’ Drivers - cont.

Support multiple events/commands in a single XML document

Engine doesn’t send more than one.

Additional events added by XSLT

Generate a <status> line in the output document for each event based on event-id.

Don’t ‘batch’ events in a single XML doc on the publisher channel

Support Publisher Heartbeat

Publisher issues a status document on regularly scheduled interval.

‘Production’ Drivers - cont.

Support Nsure Audit

Currently shipping drivers already supported.

Contents of <status></status> tagset copied to description tag.

Additional tags supported

<code> - Message Error Code

<description> - Short description of error

<data> - text or base64 encoded data

<type> - data type of the <data> element

Production Drivers & NSure™ Audit

Status Level & Status Type

Status Level

Provides a high-level ‘result code’ for an operation.

Success / Failure kind of information

Status Types

Types represent functional areas or operation types that can result in failures.

Using both Level and Type in an RNS configuration provides for a highly customizeable error reporting and handling scheme.

Production Drivers & NSure Audit – cont.

Status Level

Success

Operation succeeded

Warning

Operation succeeded with a warning

Retry

Driver requests the event to be cached and re-transmitted

Error

An error occurred. The event is removed from the cache.

Fatal Error

A serious error occurred. The event is removed and the driver is stopped.

Production Drivers & NSure Audit – cont.

Status Types

app-authentication

Error occurred when driver tried to authenticate to the application

app-connection

Error with the health of the app connection

app-general

General error reported by the application

Production Drivers & NSure Audit - cont.

Status Types

driver-general

General memory, data or execution error

driver-status

Engine events around driver start-up and shutdown

password-set-operation

Status doc has the result of a password set op

remoteloader

Errors generated by Remote Loader

Production Drivers & NSure Audit – cont.

Status Types

Definitions not owned by Novell

3rd parties can create their own status types

Serve as a trigger or tag to Audit configurations

Deployment Responsibilities

Data requirements

Schema mapping

Filtering objects and attributes

Authoritative Source

Required data

Data translation

Additional functionality

Deployment Responsibilities - cont.

Driver selection

Where is the data?

What protocols or transports are supported?

What application features are needed?

Remote?

Deployment Responsibilities - cont.

Useful Tools

DXCmd

Provides a command-line interface to NCPs around driver management

Attrmove

Moves attribute values from one attribute name to another

Useful for Schema Normalization

DirXML License Auditing Tool (DLAT)

Useful to determine Identity Manager usage.

DirXML Version Discovery Tool (DVDT)

Determines Engine and Driver versions.

Support Code

Driver State support

Driver can save state information between invocations

Done by adding an <input-params> tag to a return doc or a published document

Can set state for driver, subscriber, or publisher state

<driver-state>

<subscriber-state>

<publisher-state>

Support Code

Additional utility code to ease your burden...

com.novell.xml.dom.DOMQuery

A class that uses XPath expressions to find nodes in a DOM tree.

com.novell.xml.dom.DOMUtil

Utility class implementing, among others, things that XSLT and DirXML need for DOM that aren't defined by the 1.0 DOM spec (namespaces, serialization, whitespace stripping, id resolution, etc.).

com.novell.xml.dom.DOMWriter

A class for serializing DOM trees, used by XmlDocument and DOMUtil. Using this class directly allows for finer control of the serialization process.

Support Code - cont.

com.novell.xsl.util.Util

Has a method called getXSLStringValue() which evaluates the string value of a Node according to the XPath definition. Useful for the text content of an Element.

com.novell.nds.dirxml.driver.DriverFilter and

com.novell.nds.dirxml.driver.ClassFilter

Allows easy use of the Publisher Event Filter or the Subscriber Event Filter passed to the shim init() method.

com.novell.nds.dirxml.driver.Trace

Facility for drivers to use to output debugging trace messages to the DSTRACE console and to the DirXML log file.

Support Code - cont.

com.novell.nds.dirxml.driver.DelimitedText

class for representing a delimited text file as XML.

com.novell.nds.dirxml.driver.ThreadBridge

implements a method of calling methods on a different thread.

com.novell.xml.util.Base64Codec

implements encoding and decoding of binary data using Base64 encoding. Base64 encoding is used by DirXML to encode binary data in command and event notification documents

Policies & Customization

New capabilities in Identity Manager 2.0

Policy Manager

New verbs/commands abstract logic commonly implemented in XSLT

Interface guides you through creation process

Global Configuration Variables

Named Passwords

Role Based Entitlements

Policies and Customization

XSL Stylesheets

Event transformation defines how to map one event to another based on XSLT logic

Using XSL to override XML rules

Create, match and placement rules can be implemented as XSL

Create rule object

Paste XSL into object editor

Add the rule as a attribute of the subscriber or publisher

Appendix

The following slides represent additional technical notes.

Policy Processing Order Subscriber

Convert

Event

to

XML

Event

Transformation

Schema

Mapping

Output

Transformation

Matching

Rule

Create

Rule

Placement

Rule

Subscriber Add Processor

Subscriber

Filter

Event

Cache

NO

YES

The DirXML Engine

Command

Transformation

Does an

association

exist?

Policy Processing Order Publisher

Convert

Event

to

eDirectory

Command

Transformation

Schema

Mapping

Input

Transformation

Matching

Rule

Create

Rule

Placement

Rule

Publisher Add Processor

NO

YES

The DirXML Engine

Event

Transformation

Does an

association

exist?

Publisher

Filter

Building Associations Subscriber

One

Write

association

Apply

matching

rule:

Query

App

Merge

attributes

Mark

association

pending

Apply

placement

rule

Zero

NO

YES

Create

App Object

Modify

App object

Multiple

YES

NO

Desired

eDirectory

event

occurs

Apply

create

rule

Query

eDirectory

Modify

App Object

Modify

eDirectory

object

Does this object have an association?

Number of

matches

Error

Do we

have all required

attributes?

One

Write

association

Apply

matching

rule:

Query

eDirectory

Merge

attributes

Apply

placement

rule

Zero

NO

YES

Create

eDirectory

Object

Modify

eDirectory

object

Multiple

YES

NO

Desired

eDirectory

event

occurs

Apply

create

rule

Modify

App Object

Modify

eDirectory

object

Does this object have an association?

Number of

matches

Error

Do we

have all required

attributes?

Query

eDirectory

Query App

Query

App

Building Associations Publisher

Required Driver Interfaces

The Directory becomes the “hub” for all of the systems. It enables us to share information with systems that are otherwise desperate.

The Directory becomes the “hub” for all of the systems. It enables us to share information with systems that are otherwise desperate.

Micah Bauer

2004-03-05T11:21:14