Tech-Blog

Extracting IdM Configuration from a Running Instance

Posted by Mike Sat, 25 Apr 2009 02:16:00 GMT

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:

1. export configuration from running system via lh
2. split export file, one file per top level element
3. mangle XML objects (remove date based attributes, GUID etc)
4. repeat above for reference, out-of-the-box, IdM deployment
5. 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!

Posted in technology | Tags idm, sun | 1 comment | no trackbacks

Documenting Sun IDM XML Objects

Posted by Mike Fri, 23 Jan 2009 18:23:00 GMT

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:

1. Add a <Comments> element or @description XML comment to your waveset object. See below for list of supported elements.

2. 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.)

3. 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">
     

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

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.

Posted in programming | Tags docbook, idm, xsl | no comments | no trackbacks

links for 2007-02-13

Posted by Mike Tue, 13 Feb 2007 00:18:57 GMT

• TextDrive Accelerator Hosting
  (tags: solaris hosting)
• IDM 7: Developing adapters
  (tags: sun idm java identity)

Posted in delicious | Tags hosting, identity, idm, java, solaris, sun | no comments | no trackbacks