OpenAM: Open season on doc bugs

For some time I’ve been more or less head down at ForgeRock, writing about what is going to become OpenAM 10. Perhaps you’ve seen things taking form under the core docs page on the OpenAM community site.

The OpenAM Wiki is growing more and more. At the same time, with the major release coming up, we want to provide core docs that we have reviewed and tested alongside the software. I’m expecting to squash lots of doc bugs between now and the final release.

Here’s the docset table of contents as it stands today (minus the release notes, which will be updated closer to the release date):

Installation Guide

Preface

1. Installing OpenAM Core Services

2. Installing OpenAM Tools

3. Installing OpenAM Console Only

4. Installing OpenAM Core Only

5. Installing OpenAM Distributed Authentication

6. Installing OpenAM Client SDK Samples

7. Customizing the OpenAM End User Pages

8. Setting Up OpenAM Session Failover

9. Upgrading OpenAM Core Services

10. Removing OpenAM Software

Index

Administration Guide

Preface

1. Administration Interfaces & Tools

2. Defining Authentication Services

3. Defining Authorization Policies

4. Defining Entitlements

5. Configuring Realms

6. Configuring Policy Agent Profiles

7. Configuring Password Reset

8. Configuring Cross-Domain Single Sign On

9. Managing Federation

10. Backing Up and Restoring OpenAM Configurations

11. Managing Certificates

12. Monitoring OpenAM Services

13. Tuning OpenAM

14. Troubleshooting

Index

Developer’s Guide

Preface

1. OpenAM APIs and Protocols

2. Developing Client Applications

3. Using RESTful Web Services

4. Using the OpenAM Java SDK

5. Authenticating Using OpenAM Java SDK

6. Handling Single Sign On Using OpenAM Java SDK

7. Requesting Policy Decisions Using OpenAM Java SDK

8. Using Fedlets in Java Web Applications

9. Using the OpenAM C API

10. Extending OpenAM

11. Customizing Profile Attributes

12. Customizing Authentication Modules

13. Creating a Post Authentication Plugin

14. Customizing Policy Evaluation

15. Customizing Identity Data Storage

Index

Reference

Preface

I. OpenAM Command Line Tools

1. Log Messages

2. Error Messages

3. Ports Used

4. Localization

5. File Layout

6. Supported Standards

Index

Policy Agent 3 Installation Guide

Preface

1. About OpenAM Web Policy Agents

2. Installing the Apache 2.0.x Policy Agent

3. Installing the Apache 2.2 Policy Agent

4. Installing the Microsoft IIS 6 Policy Agent

5. Installing the Microsoft IIS 7 Policy Agent

6. Installing the Sun Web Server Policy Agent

7. About OpenAM Java EE Policy Agents

8. Installing the Apache Tomcat Policy Agent

9. Installing the GlassFish Policy Agent

10. Installing the JBoss Application Server Policy Agent

11. Installing the Jetty Server Policy Agent

12. Installing the IBM WebSphere Policy Agent

13. Installing the Oracle WebLogic Policy Agent

14. Troubleshooting

Index

Under the core docs page you’ll also find other formats, like the entire books in PDF or as a single HTML page, and also a link to the Javadoc.

If you want to help out as you test the latest OpenAM nightly builds on the road to OpenAM 10, I would live to hear from you. You’re welcome to sign up for a chapter or two on the OpenAM doc review dashboard.

OpenDJ: Identity Store for Tomcat and JSPWiki

What I like about JSPWiki is that it is generally pretty easy to set up, and instead of using a database to store content out of the box, it lets you store your wiki pages in files. The file-based storage can be handy when you want to grep through your content or change a bunch of files with sed and awk.

Apache Tomcat is one of the easiest web application containers to get up and running. Lots of people use it to set up OpenAM for testing, and also for deployment.

Tomcat can do container managed security, so you can set up users and groups in OpenDJ and let users login to Tomcat applications by authenticating with their OpenDJ username and password. Container managed security is not so versatile as OpenAM, but it can be handy if you have your identities in OpenDJ and want quickly to set up an application like JSPWiki with authentication through to OpenDJ. Today I took a break from other writing and added a couple of how to docs to the ForgeRock OpenDJ Wiki:

• Configure Apache Tomcat with OpenDJ as an Identity Store
• Configure JSPWiki for Authentication to OpenDJ

All three Java applications worked fine for me with OpenJDK on an Ubuntu virtual machine. There are lots of other LDAP-enabled applications out there that work with OpenDJ. It will be great to see more how-tos on the wiki.

OpenDJ 2.4.4 released

OpenDJ 2.4.4 has released today. OpenDJ 2.4.4 is the latest update, fixing a bunch of issues mentioned in the Release Notes.

To perform an evaluation install if you already have Sun Java 6 on your system, try the Java WebStart version. For additional install instructions, see the Installation Guide. (The IcedTea bug preventing WebStart installs by default on Linux was fixed late September, so if you have a cutting edge version of that, you might be able to WebStart install without downloading Sun Java 6.)

For much more on using the server, note that although the Admin Guide is aimed at 2.5.0, the changes are listed in What’s New in OpenDJ 2.5.0. Therefore, you might find the 2.5.0 Admin Guide useful with 2.4.4 as well.

You are of course welcome to join the community, and also to sign up for the mailing list.

JavaScript to manage wide lines

Some commands to manage servers tend to lend themselves to examples that do not fit in 80 columns. Command with subcommands that take a string of options with arguments typically fall into this category.

One alternative to make the examples readable is to insert line breaks.

$ dsconfig
 -p 4444
 -h `hostname`
 -D "cn=Directory Manager"
 -w password
 create-plugin
 --plugin-name "Samba Password Synchronisation"
 --type samba-password
 --set enabled:true
 --set pwd-sync-policy:sync-nt-password
 --set
 samba-administrator-dn:"uid=samba-admin,ou=Special Users,dc=example,dc=com"
 -X -n

Trouble comes, then, when you want to copy the example into a terminal window. What do you do? Copy line by line? Copy into a text editor and remove the newlines?

This morning I wished my browser would just do it for me. Then after a coffee, I realized my browser probably could. I learned just enough JQuery to do join the continuation lines in <screen> (terminal window) content when clicked:

$(document).ready(function(){
  $(".screen").click(function(event){
    $(this).replaceWith(
      "<pre>" + $(this).text().replace(/\n /g," ") + "</pre>");
  });
});

Going to give it a whirl in OpenDJ HTML documentation. Unfortunately, once you click, this code cannot take you back. You have to reload the page again to see the command unfolded. It would be cool to have click be a toggle.

On click, the above folds to:

$ dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password create-plugin --plugin-name "Samba Password Synchronisation" --type samba-password --set enabled:true --set pwd-sync-policy:sync-nt-password --set samba-administrator-dn:"uid=samba-admin,ou=Special Users,dc=example,dc=com" -X -n

(I cannot figure out how else to show you in this hosted WordPress blog.)

Even cooler would be the equivalent in DocBook to allow authors to drop in exactly what they see in the terminal, reformatting the output for presentation, but leaving a JavaScript toggle in the HTML version to go back to the original presentation for copying.

OpenAM: 7 ± 2 core docs

To echo William of Ockham’s concern, I think I postulated too many entities.

Right now, the OpenAM core docs include 8 separate documents. That’s getting close to the 7 ± 2 limit (or should it be 4?), leaving little room if it turns out we want to expand.

The reference could probably fit in the back of the Admin Guide, despite the length of the generated log ref. Currently, everything in there pertains to administration rather than client or SDK development. The installation and policy agent installation guides could merge as well.

I’m tempted to make the changes before OpenAM 10, unless one of you has a good objection. Let me know if reducing the number of separate docs would be a mistake.

OpenDJ: 2.5 docs up for review

As mentioned on the OpenDJ discussion list yesterday, the draft OpenDJ core documentation for 2.5 is up for review. (The core doc is all labelled 3.0.0-SNAPSHOT, but the Install and Admin Guide content applies to 2.5.)

If you either do not mind reading, or simply cannot find a cure for your September insomnia, pick an Install Guide or Admin Guide chapter out from the review dashboard, get a nightly build of OpenDJ installed, and try it out.

Looking forward to your suggestions, comments, and bug reports.

OpenDJ: Which accounts are active?

Perhaps you want to know which of your users are logging in regularly, and which have not logged in for some time. Ludo explained how to do time-based comparison searches in OpenDJ.

Yet, OpenDJ directory server does not record last login time by default. You must set it up by adjusting password policy if you want to track which users are actively logging in.

Assuming you have installed OpenDJ and generated a few test users, then you have users subject to the default password policy.

$ ldapsearch
 -p 1389
 -b dc=example,dc=com
 uid=user.0
 pwdPolicySubentry
dn: uid=user.0,ou=People,dc=example,dc=com
pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config

To have OpenDJ record when a user logs in, you set last-login-time properties in the password policy. One of the properties to set is the attribute to use, the other is the format of the time stamps to save.

OpenDJ comes with an attribute named ds-pwp-last-login-time defined in the schema. The ds-pwp-last-login-time attribute has string syntax, and so does not benefit from the time-based matching Ludo described in his blog. Instead, you can define an attribute with generalized time syntax to store the last login time.

$ cat /path/to/OpenDJ/config/schema/98-lastLogin.ldif
#
# Schema definition for a generalizedTimeMatch lastLoginTime attribute
#
dn: cn=schema
objectClass: top
objectClass: ldapSubentry
objectClass: subschema
attributeTypes: ( lastLoginTime-oid
  NAME 'lastLoginTime'
  DESC 'Last time the user logged in'
  EQUALITY generalizedTimeMatch
  ORDERING generalizedTimeOrderingMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
  SINGLE-VALUE
  NO-USER-MODIFICATION
  USAGE directoryOperation
  X-ORIGIN 'http://marginnotes2.wordpress.com' )

Next, adjust the password policy to put a generalized time stamp on lastLoginTime.

$ dsconfig
 -p 4444
 -h `hostname`
 -D "cn=Directory Manager"
 -w password
 set-password-policy-prop
 --policy-name "Default Password Policy"
 --set last-login-time-attribute:lastLoginTime
 --set last-login-time-format:"yyyyMMddHHmmss'Z'"
 -X -n

Check that OpenDJ tracks last login time, by first performing an LDAP search with a user name and password (effectively logging in), and then reading the value of lastLoginTime on the user’s entry.

$ ldapsearch
 -p 1389
 -D uid=user.0,ou=people,dc=example,dc=com
 -w password
 -b dc=example,dc=com
 uid=user.0
 cn
dn: uid=user.0,ou=People,dc=example,dc=com
cn: Aaccf Amar

$ ldapsearch
 -p 1389
 -b dc=example,dc=com
 uid=user.0
 lastLoginTime
dn: uid=user.0,ou=People,dc=example,dc=com
lastLoginTime: 20110915210256Z

Now use Ludo’s advice to see who has logged over the last 3 months.

$ ldapsearch
 -p 1389
 -b dc=example,dc=com
 "(lastLoginTime:1.3.6.1.4.1.26027.1.4.5:=-13w)"
 uid cn
dn: uid=user.0,ou=People,dc=example,dc=com
uid: user.0
cn: Aaccf Amar

A nice way of checking which users are actively logging in by authenticating to OpenDJ directory server.

OpenAM, OpenDJ: Looking for doc reviewers

OpenAM core documentation is starting to come together on the project site. Install documentation for core services is up, with agent install documentation off to a good start. The admin guide now has some meat. The reference is coming together. There’s plenty of work on federation, use of entitlements, a whole dev guide, and tips on monitoring, tuning, and troubleshooting still to write. But it’s about time to start taking feedback.

OpenDJ core docs are mostly up to date with the trunk. Matt’s still developing pass-through authentication, and the doc on that is pending. So too with native packaging for Linux distros. Yet what’s there could definitely benefit from your comments.

By the way, the core docs will cover the product features, and so won’t necessarily cover specific use cases in detail, or how to integrate OpenAM or OpenDJ with other software. For that, a good place to check is the ForgeRock Wiki.

OpenDJ to store Kerberos principals

Lately I’ve been head down working mainly on the OpenAM core documentation here at ForgeRock as we work towards OpenAM 10.

But I took some time out recently to set up OpenDJ directory server to store Kerberos principals. The example I wrote up is with MIT Kerberos on CentOS 6. Everything was on one VM for that example, so it’s fairly simple to try.

One thing I’m still scratching my head about is how to get the /etc/init.d scripts working for the Kerberos daemons. If I don’t start the daemons on the command line, they won’t run. Suggestions appreciated.

XML validation in Eclipse

Eclipse is the XML editor I have been using the most to edit ForgeRock core docs, which are in DocBook 5 XML. The tag completion works for me. So does document validation.

But I am not using the default XML file validation preferences. First, I want to see all the errors, so have checked “Enable markup validation.”

Second, the core docs use XInclude so the book files include chapters and so forth with <xinclude:include href='chap-name.xml' /> elements. Therefore, I have checked “Process XML Inclusions” as well.

Seems like “Process XML Inclusions” should be checked by default, but it is not.

Now I can right-click (or Ctrl+click) an XML file, and then run Validate from the context menu.