nsure ™ identity manager 2 (formerly dirxml ® ) driver development overview richard matheson...

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

Richard MathesonDirXML Driver Engineering ManagerNovell, [email protected]

© March 9, 2004 Novell Inc.2

one Net: Information without boundaries…where the right people are connected with the right information at the right time to make the right decisions.

The one Net vision

Novell exteNd™

Novell Nsure™

Novell Nterprise™

Novell NgageSM

:

:

:

:


The one Net vision

Novell Nsure solutions take identity management to a whole new level. Novell Nsure gives you the power to control access so you can confidently deliver the right resources to the right people — securely, efficiently, and best of all, affordably.

Novell Nsure™

Novell exteNd™

Novell Nsure™

Novell Nterprise™

Novell NgageSM

:

:

:

:


Vision…one NetA world where networks of all types—corporate and public, intranets, extranets, and the Internet—work together as one Net and securely connect employees, customers, suppliers, and partners across organizational boundaries

Novell® Vision and Mission

MissionTo solve complex business and technical challenges with Net business solutions that enable people, processes, and systems to work together and our customers to profit from the opportunities of a networked world


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

8

Identity Manager Architecture

IdentityVault

DirXMLDirXMLEngine

Identity Manager

DriverShim

Policies

Policies

Subscriber Channel

Publisher ChannelApplicatio

n

Novell DirXML Server

Identity Manager 2

9

Identity Manager ArchitectureThe Remote Loader

IdentityVault

DirXMLDirXMLEngine

Identity

Manager

DriverShim

Policies

Policies

Application

Novell DirXML Server

Remote

LoaderShim

Remote

LoaderService

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


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 for

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 definedin 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 ApplicationAccess methods

• Standards-based protocol• Proprietary API• Is it remotable?• Schema issues• Reading and writing information• Discovering changes in the application space

Authentication issuesAssociations

• 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

thanjust 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



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.



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‐ An serious error occurred. The event is removed and the

driver is stopped.



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



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.


Required Driver Interfaces

Interface Name Purpose Java Name C++ Name DriverShim General driver initialization and

shutdown com.novell.nds.dirxml.driver.DriverShim

DriverShim in NativeInterface.h

SubscriptionShim - Translates XML from NDS into application native format

- Reads application schema for DirXML

com.novell.nds.dirxml.driver.SubscriptionShim

SubscriptionShim in NativeInterface.h

PublicationShim Translate application native format data into XML for NDS

com.novell.nds.dirxml.driver.PublicationShim

PublicationShim in NativeInterface.h

XmlQueryProcessor Processes XML docs representing queries against the application

com.novell.nds.dirxml.driver.XmlQueryProcessor

XmlQueryProcessor in NativeInterface.h


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.


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

General DisclaimerThis document is not to be construed as a promise by any participating company to develop, deliver, or market a product. Novell, Inc., makes no representations or warranties with respect to the contents of this document, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc., reserves the right to revise this document and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes. All Novell marks referenced in this presentation are trademarks or registered trademarks of Novell, Inc. in the United States and other countries. All third-party trademarks are the property of their respective owners.

No part of this work may be practiced, performed, copied, distributed, revised, modified, translated, abridged, condensed, expanded, collected, or adapted without the prior written consent of Novell, Inc. Any use or exploitation of this work without authorization could subject the perpetrator to criminal and civil liability.


Appendix

The following slides represent additional technical notes.


Policy Processing Order Subscriber

ConvertEvent

toXML

EventTransformation

SchemaMapping

OutputTransformation

MatchingRule

CreateRule

PlacementRule

Subscriber Add Processor

SubscriberFilter Event

Cache

NO

YES

The DirXML Engine

CommandTransformation

Does an association

exist?


Policy Processing Order Publisher

ConvertEvent

toeDirectory

CommandTransformation

SchemaMapping

InputTransformation

MatchingRule

CreateRule

PlacementRule

Publisher Add Processor

NO

YES

The DirXML Engine

EventTransformation

Does an association

exist?

PublisherFilter


Building Associations Subscriber

One

Writeassociati

on

Applymatching

rule:QueryApp

Mergeattribute

s

Markassociati

onpending

Applyplacement

rule

Zero

NO

YES

CreateApp Object

ModifyApp object

Multiple

YES

NO

DesiredeDirectory

eventoccurs

Applycreaterule

QueryeDirecto

ry

ModifyApp Object

Modify eDirectory

object

Does this object have

an association?

Number of

matches

Error

Do wehave all required

attributes?


One

Writeassociati

on

Applymatching

rule:Query

eDirectory

Mergeattribute

s

Applyplacement

rule

Zero

NOYESCreateeDirectory

Object

ModifyeDirectory

object

Multiple

YES

NO

DesiredeDirectory eventoccurs Apply

createrule

ModifyApp Object

Modify eDirectory

object

Does this object have

an association?

Number of

matches

Error

Do wehave all required

attributes?

QueryeDirector

y

Query App

QueryApp

Building Associations Publisher

nsure ™ identity manager 2 (formerly dirxml ® ) driver development overview richard matheson...

Documents

nsure identity manager

identity vault

flow of data

sharing data

net vision

authoritative sources

net business solutions

islands of isolated