Walking through the Banner Driver - Part 1

There are many drivers available out of the box from NetIQ and even more available from various partners. You can get a feel for the scope in the article below, where I have listed the DirXML-Associations values for the various drivers that are known: Open Call – IDM Association Values for eDirectory Objects

One of the issues with supporting an out of the box driver is that when something does not go quite right, often you assume, well it must work that way for a reason. But there is no really good way of knowing what that reason is, or whether it is really a bug.

I have been trying to work on that issue by walking through a variety of drivers, policy by policy, item by item, explaining as best I can what is going on. This way you get an idea for what should be happening and why. My hope is that this has been a useful tool for troubleshooting issues for folk out there. Please let me know if one of my walk throughs has helped you out, I am curious to know. I fully get they are probably as boring as watching paint dry, but when you need them, I imagine there is nothing quite like them.

Next on my list of drivers I need to review is the Banner driver, that came post IDM 4.02. I remember seeing a presentation on this driver back in 2008 or 2009 at a pre-BrainShare event, and it looks a fair bit different now, from what I remember so that is good.

One of the neat things about Packages, is that I can identify the very specific version the driver configurations I am reviewing. I learned the hard way when doing some drivers that took a very long time, that the packages can get updated quite significantly in the time it took me to complete the series. Thus it is important to specify the exact package versions being reviewed.

For the Banner driver, I used the latest packages in August of 2014, and they were:

Banner Base
Banner Account Tracking Package
Banner Managed System Information
Banner Password Polices and GCV's
Banner User Objects
Password Synchronization Common

When I saw this driver presented, I watched and came out of the session with the thought, this is a SOAP driver, but the schema mapping is hidden inside the shim so that it can be licensed as a new driver. That was a 1.0 version and this one looks different in many ways so far. Lets see how different that really is.

It is still talking SOAP to a Sunguard HE server (which is what the configuration calls it, but I seem to recall the servers name is really BEIS, Banner Enterprise Integration Server). Which is really a SOAP endpoint to talk to.

This shim is focused on the UCIdentity object, and not much else. If you want to get course information you need to do that on your own elsewhere. In that case, you probably want to connect over SOAP to the LIS standard interface (Learning Information System).

It was funny, a friend presented at a conference on the IMS Global set of standards, and there was literally just me, actively interested in the session. (Hey Johnny!) I was only interested since I had recently worked on a project getting the course information out of Peoplesoft (now owned by Oracle) from the SAIP (Student Administration Integration Pack) module.

But it turns out these standards are becoming more and more relevant, since various LMS/CMS systems (Learning/Course Management Systems) and SIS (Student Info Systems) are supporting these standards to describe class enrollments. Things like Banner, BlackBoard, Oracle PeopleSofts SAIP module, Canvas, and others are supporting it. A standard that is actually see widespread adoption. Whoda thunk it?

Anyway, installed the driver into my Designer project using the Package versions listed above, so feel free to do the same and follow along. It may be easier to follow along that way, if you would like.

Lets start with the driver properties, specifically the Driver Parameters. Two sets here, Sub and Pub channel stuff, as you would expect.

Subscriber side, you need the URL of the Sunguard HE server, which is basically the SOAP endpoint. An Authentication ID and password, and a keystore file (in the local engines file system) that holds the public key, of the Certificate Authority, that signs the SSL certificate used on that endpoint.

I think this minor detail confuses people and is worth digressing about. SSL works with two methods. Almost the entire conversation is managed by using a shared secret that is the key to decrypt the communications in a symmetric encryption, because that is a fast encrypt and decrypt model.

But there is a problem, how do you get that shared secret in a secure fashion? That is where the SSL certificates come in. They are used just to start the conversation, since they are asymmetric encryption and 'slow' to process. In order to 'trust' the certificate being offered, you need to have a keystore (Mozilla, Chrome, IE, Java, and .NET all come with built in keystores with tons of well known Certificate Authorities included) that has the Public key of the Certificate Authority in it, flagged as a trusted signer.

In the JKS Keystore world (JKS= Java KeyStore) that means when you import the trusted root into your cacerts file (in the lib/security folder of your JVM), you need the -trustcacert flag set.

Anyway, this driver expects a JKS Keystore which has a password, but I do not see a password option in the driver configuration, which makes me think it is expecting the cert to be in the standard cacerts file for Java, which for some reason almost always uses the password 'changeit' or 'default'.

Finally, if you need to go through a web proxy for communications, a host and port option are available. But I see no username/password option for the proxy, so you may need to use something like stunnel in that case to open secure tunnel to the proxy on your server, and then talk to the local end of the tunnel for communications.

Publisher side there is a listening host and port field, so that the BEIS can reach out and send you events. If it is doing so, the next option is, does it need authentication? If so, create a username and password that the BEIS server should send. I.e. It is not picking an eDirectory user to authenticate in, it is picking a 'pseudo user' you create right here. After all, as a SOAP driver, if you allow it, then it acts as the server context.

If you allow authentication, you are sending a password, in which case you should probably encrypt that session, so the next option is Accept HTTPS connections. If so, you now need to pick a certificate to expose in the web service endpoint being enabled as the Publisher channel.

Here you have two options.

  1. Use a Key Material object in eDirectory, like you use for remote loader connections. This is nice since the public and private key are stored securely in eDirectory and the engine has permission to retrieve them securely, so not much more configuration is needed. As in the Remote Loader case, remember that while in eDirectory the object may be named "SSL CertificateDNS - ServerName" for the Remote Loader configuration you address it as "SSL CertificateDNS" only. The dash followed by a server name is ignored, even if it is a real part of the object name. Same here. The KMO name value would be "SSL CertificateDNS" only. (Minus the quotes of course).

  • Use a certificate stored in a keystore. If so, you need to specify more information.


    A keystore file
    Password for the keystore
    Alias for the server key (I.e. WHICH cert to use, since a keystore can have many.)
    Server key password (the private key has another password)

Seems a lot easier to just use a KMO object doesn't it? You can create a CSR in eDirectory (Certificate Signing Request which basically generates the private key, and asks a CA to sign it, which you return and is used to sign the Private Key in eDirectory) and get a real external CA to sign it, so the Sunguard/Banner side has fewer issues.

I know a lot of people are getting lazy and just buying wild card certificates (They used to be crazy money. I recall 3 years ago, Verisign wanted something like $70,000 for one. But some of their competitors started offering them for less than $1000 and that price point ended) and I am pretty sure you can import that into a KMO as well, but I forget all the specific steps required to do so.

The next field in Content-Type, set to text/xml, which on the Publisher channel is interesting, I guess it just rejects any other content type? In the context of a REST endpoint this matters a lot, since REST can use text/xml or text/json and thus you need to match that to the type of data you are sending.

Finally a heartbeat interval in minutes field is standard for most drivers.

I see there are two ECMA objects linked in. One if the ubiquitous Lib AJC. I love Lib AJC. So useful, and comes with many useful functions. I actually went through all 100 functions and explained what they do in plain english, as an appendix to my book on IDM Tokens. (I guess I never did publish that bit public, oh well, buy the book, value add, whatever) You can find my book that discusses all 121 tokens that the engine uses in DirXML Script at this link.

Hmm, I wonder with IDM 4.5 coming soon (as I write this) are any new engine tokens coming? May have to update the book darn it!

The AJC (Advanced Java Class) was a Java class written by Novell Consulting, that they would use in many of their engagements. Mostly things that in the olden days were not built into Policy, but are nowadays and deprecated. Lots of time comversion stuff, random password generators, etc. Around IDM 3.5 or 3.6 this class was ported to ECMA Script and made available for all of us to use. It is worth perusing the functions some time there are some great nuggets, and tons of great ECMA examples.

The second ECMA object comes from the NOVLBNNRBASE package. It has one function, convertPhoneToBanner() that takes two parameters, a number string and a number format. I have seen behavior like this in SAP UM and Workday HRIS, where a phone number is anything but a simple number. Usually things that span countries often try to avoid storing a phone number as a simple string.

The format string has the characters CATXS:

C Country Code
A Area Code
T Telephone Number
X Extension Number
S Subscriber Number

So I guess a sample US number might be passed in as:

121255512121234 with a filter of CAAATTTTTTTXXXX
Parsing that, I have a C (Country Code) of 1.
An AAA (area code) of 212
A TTTTTT (telephone number) of 5551212
A XXXX (extension number) of 1234

The ECMA uses the filter to split up the number into the components, and then reformat them as the return string of:
return countryCode   '^'   areaCode   '^'   telephoneNumber   '^'   extension   '^'   subscriberNumber

Which seems that is using a caret (^ or shift 6 on US keyboard) as a delimiter. Which is only slightly stranger than usual as a way to store phone numbers.

I should go look up how Workday does it since it is even goofier, and probably a funnier story, but maybe another day.

That wraps up the kick off to this series. Lets see if I can finish it faster than the Office 365 series that took me 16 articles. That turned out to be much more work than I expected, and being lazy, I am hoping this one is easier!


How To-Best Practice
Comment List