Tech-Blog: Tag idm

Extracting IdM Configuration from a Running Instance

Mike — Fri, 24 Apr 2009 22:16:00 -0400

An IdM customer recently found themselves in a pickle: they wanted to integrate additional resources into their IdM deployment, but did not have access to the original configuration files or CBE.

Here are the steps we took to extract configuration from their production repository:

export configuration from running system via lh
split export file, one file per top level element
mangle XML objects (remove date based attributes, GUID etc)
repeat above for reference, out-of-the-box, IdM deployment
diff XML object sets (custom deployment vs. reference deployment)

And the details...

Export Configuration

Use the lh command to extract the running configuration:

   mpierson:$ export WSHOME=/var/lib/tomcat/webapps/idm
   mpierson:$ $WSHOME/bin/lh console -c "export /tmp/export.xml"

Note: the export process may take some time, and consume significant cycles on the host and the repo; the resulting export.xml file will be of the order of 100Mb, depending on the number of user/resource accounts.

Split Export File

To facilitate comparison of the custom configs to the reference deployment, split the export file into many files, one per top level waveset element:

   mpierson:$ xsltproc split-waveset.xslt /tmp/export.xml

We used a simple XSL transform that writes each child of the top level waveset element to a file, using file names based on name or id attributes, if available.

Note: the example XSL transform will write the files to a directory called 'split', and there will potentially be many files created.

Mangle XML Objects

Again, to facilitate comparison of the custom config objects to the reference deployment, we mangled the split XML files to remove date based attributes, owner/modifier attributes, and GUIDs:

   mpierson:$ ./remove-transient-attrs.sh split-dir idm-key-prefix

... where split-dir is the name of the directory containing XML files to be cleansed, and idm-key-prefix is the first 5-6 characters of the instance ID prefix (i.e. '123456' in "#ID#123456789ABC...")

Note: here is the bash script that utilized find and perl to strip the relevant attributes.

Repeat for Reference Deployment

Repeat steps 1 thru 3 to produce an reference set of waveset objects. Ensure that you reference IdM deployment matches the version, including hotfixes, of the running instance being analyzed.

Catalog Differences in Custom Deployment

We applied diff recursively over the two sets of waveset objects:

   mpierson:$ diff -N -r --brief -w reference-elements/ custom-elements/

The results of a diff will likely include a number of run-time objects, including User, Account, XmlData, and Syslog elements. Filter run-time objects from the diff for a better view of configuration:

   mpierson:$ diff -N -r --brief -w reference-elements/ custom-elements/ |\
    grep -v Account| grep -vi syslog |\
    grep -v TaskInstance | grep -v "User-" |\
    grep -v TaskResult | grep -v XmlData |\
    grep -v WorkItem

We used a similar approach to produce a list of the XML objects that define the IdM configuration:

   mpierson:$ diff -N -r --brief -w reference-elements/ custom-elements/ |\
    grep -v Account| grep -vi syslog |\
    grep -v TaskInstance | grep -v "User-" |\
    grep -v TaskResult | grep -v XmlData |\
    grep -v WorkItem |\
    awk '{print $4;}' > files.txt

Notes: the results of this process provides a starting point for a rigorous reverse engineering endeavour. Manual inspection of the results, and extensive testing are recommended!

Documenting Sun IDM XML Objects

Mike — Fri, 23 Jan 2009 13:23:00 -0500

Note 1: this post details an approach for documenting the configuration objects of Sun's Identity Manager product. It's propbably not interesting unless you're an IDM developer.

Note 2: the following article applies to IDM 7.1. Not sure about earlier or later versions.

IDM's XML configuration objects have limited support for in-situ programmer comments. Most high-level elements allow <Comments> elements, while others support a description attribute. Herewith an approach that leverages the existing documentation aspects of the Waveset.dtd, generic XML comment notation, and the waveset XML data iteself to generate IDM implementation documentation.

A schematic that shows how the approach takes waveset XML objects and converts them to standard document formats:

For the impatient, the XSL that transforms Waveset XML to Docbook XML is waveset2docbook.xsl.

Documenting a Single XML Object

A recipe for generating documentation from an IDM configuration XML file:

Add a <Comments> element or @description XML comment to your waveset object. See below for list of supported elements.
Using your favourite XSL processor, transform the waveset XML object to Docbook format using waveset2docbook.xsl.
I use xsltproc, e.g.:
```
mpierson:$ xsltproc --stringparam fileName "custom/WEB-INF/config/MyResource.xml" \
  waveset2docbook.xsl custom/WEB-INF/config/MyResource.xml > docs/MyResource.xml
```
(The fileName stringparam allows the file's path in the CBE to be included in the documentation.)

Add an XML declaration to the generated Docbook file:

<?xml version="1.0"?>
<!DOCTYPE article
  PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

Open the generated Docbook XML in OpenOffice using file type Docbook. This should work in versions 2.x and 3.x of OpenOffice.

- or -

Use the Docbook XSL stylesheets to convert your generated Docbook file to HTML or PDF (or many other formats).

Using the above recipe, I've documented a sample LDAP resource adapter definition:

MyResource.xml -> MyResource.dbk -> MyResource.doc

Documenting the Entire IDM Implementation

A more practical application of this approach to IDM docs, is to produce a single 'as-built' document for all configured XML objects. This is best achived via a script, which repeats the procedure for a single XML waveset object, and appends each result to a single Docbook document.

An example script that does just this (including the required Docbook XML declaration) is here. You'll see in the script that I like the generated docs to be included as an appendix in the project documentation.

Supported Waveset Elements

The current version of waveset2docbook.xsl supports a subset of the waveset.dtd, but includes most of the high-level elements.

Element	Description Element	Other Aspects Documented
Configuration:User Extended Attributes	none	extended attributes are enumerated
Configuration:UserUIConfig	none	SummaryAttrNames, QueryableAttrNames, FindSearchAttrs, RepoIndexAttrs
Configuration:Reconciliation Policy	none	reconciliation policy attributes (fetch timeout etc.), plus per-resource type configuration (correlation rule, confirmation rule, proxy user, etc.)
LoginApp	@description	LoginModGroups are enumerated
LoginModGroup	none	resource type, module type, control type, correlation rule, authentication parameters
Organizations	@description	path from Top, policies
Policy:Account Policy	Description element	account ID policy, password policy
Policy:String Quality Policy	Description element	string quality policy attributes are enumerated
Resource	@description	flat file format attributes, @prodRef for reference to IDM resource documentation, active sync attributes (proxy user, correlation rule, confirmation rule),
Rule	Comments element	rule type (correlation, confirmation, other)
Configuration:Rule Library	none	documented rules are enumerated, including contents of Comment element in each rule
EmailTemplate	Comments element	status of 'html enabled' flag
TaskDefinition	Comments element	referenced sub-tasks, referenced forms
Configuration:WFProcess (sub-task)	Comments element	referenced sub-tasks, referenced forms
Configuration:Custom Catalog	none	name and value of each message is listed
TaskSchedule	Description element	task to run, repitition count and unit
User	@description	user form, admin groups, organizations
User Form	Comments element	referenced forms

OpenOffice And Docbook

It's worth noting that OpenOffice supports Docbook 'out-of-the-box', but not all elements are supported. I've adapted the docbook XSL filter from OpenOffice 3.0 to do a better job of rendering the <literallayout> elements generated by waveset2docbook.xsl. Download it here, your results may vary. The OpenOffice site has instructions for customizing the XML filters, but I just used the Tools -> XML Filter Settings in OO 3.0.

links for 2007-02-13

Mike — Mon, 12 Feb 2007 19:18:57 -0500

TextDrive Accelerator Hosting

(tags: solaris hosting)
IDM 7: Developing adapters

(tags: sun idm java identity)