If you’re looking for a simple way to authenticate Active Directory users within your iTunes U portal site, dscl is your friend. To show how you can use dscl to help manage an iTunes U portal site, I thought I would do a little write-up in the hopes that it would be useful to others.

Okay, here’s what you’ll need:

You’ll need an instance of Mac OS X (Mac OS X Server is simpler to work with) and you’ll need to setup that instance to use Mac OS X’s Active Directory directory service plugin. Setting up the AD plugin is usually straightforward, but if you are not a directory services guru, it might be best to find your local AD expert (to setup the plugin, you will need to have the ability to add a computer object into your local AD tree…this often requires that you talk to an AD administrator). When setting up OS X’s AD plugin, you generally want to follow Apple’s instructions. Specific steps for authenticating against AD are described in this document (starting at page 100). It’s a lot less intimidating than it seems (if you are not an AD guru, your local expert will find the setup trivial in most instances).

Okay, now that you have an OS X machine authenticating against Active Directory, you’re ready to have some fun with dscl. dscl is the “Directory Services Command Line” utility…it is meant to be the successor to nicl…the “Netinfo Command Line” utility. dscl can tell you about local users (that is, users created directly on your OS X machine itself)…or AD users.

For example, let’s say I setup a local user on my OS X machine called richwolf-local with password abc123. To verify that richwolf exists as a local user, I can type (in Terminal, % is the OS X command-line prompt):

  % dscl . -list /Users/richwolf-local

If you receive another command-line prompt (that is, another prompt with no message or error), the dscl command “worked” (dscl can actually return a lot of information, but we didn’t ask it to do so). If it doesn’t work, you’ll get a response like this:

  % dscl . -list /Users/goofy-local list: Invalid Path

To verify a password, you can type:

  % dscl -u richwolf-local -P abc123 . -list /Users/richwolf-local

Again, if the command “works”, you get no messages or errors, otherwise something is likely wrong.

The general form of the dscl command looks something like this…

  dscl <options> <source of directory services info> <dscl subcommand>

The options -u and -P mean “authenticate as user”— -u for “user” and -P for “password”. The period (.) in the command represents the default directory services store (since we’re testing it with a local user account, the directory store is Netinfo). list is a dscl subcommand…it asks dscl to list information about a particular directory services object (there are other subcommands that can be used to add, update, or delete information within a directory services store, but these are beyond the scope of this article). Finally, the list subcommand requires a path to an object in the directory…in the case of our local/Netinfo examples, that’s /Users/richwolf-local.

Here is where the magic comes in. To dscl, AD is just another directory. So you can replace the period in the dscl commands with AD specific info. Suppose now that I have an AD account called richwolf-ad and the same password as before (abc123). dscl can verify me this way:

% dscl -u richwolf-ad -P abc123 /Active Directory/hostDN-for-tree.myuniversity.edu -list /Users/richwolf-ad

At my university, for example, I would verify myself this way:

% dscl -u richwolf -P xxxxxxxx /Active Directory/ad.uic.edu -list /Users/richwolf

Again, if dscl returns nothing, the command “worked”, otherwise you get an error string.

Now dscl can be scripted in…oh, just about any scripting language. So CGI is simple (I like Python):

  #!/usr/bin/env python
  
  from cgi import *
  from os import *
  
  f = FieldStorage(keep_blank_values=1)
  
  username = f["username"].value
  password = f["password"].value
  
  # The dscl command should look something like this:
  # /usr/bin/dscl -u username -P password /Active Directory/mydomain.edu -list /Users/username
  # That is "typical" for a default AD setup
  dscl_command = r"/usr/bin/dscl"
  dscl_command = dscl_command + r" -u " + username
  dscl_command = dscl_command + r" -P " + password
  dscl_command = dscl_command + r" /Active Directory/ad.uic.edu"
  dscl_command = dscl_command + r" -list /Users/" + username
  stdout_handle = popen(dscl_command, "r")
  return_text = stdout_handle.read()

Now most directory services (AD, eDirectory, OpenLDAP, etc.) have tons of attributes and dscl can show you most of them. So if you have AD attributes that restrict access even further (to specific courses, say), you can ask dscl to pull those and alter your CGI appropriately, so that a very specific set of credentials are sent to Apple for a user’s iTunes U session.