What a directory holds

A shared record

Years ago, every system at Harbor Clinic kept its own list of staff. Patient records had one, scheduling had another, and the pharmacy system had a third, each with its own spelling of people's names and its own idea of who still worked there. When a nurse changed surname, someone had to update each list by hand, and usually missed one. When someone left, the lists nobody remembered kept them.

The staff directory at directory.harborclinic.example replaced most of those lists with one shared record. A directory is a store of information about people, groups, and other things an organization needs to look up, such as shared mailboxes or devices, kept in one place so that many applications can read the same answers. Scheduling asks the directory who Dana Okafor's manager is. Email reads it to build the address book. Patient records checks it to see which groups Dana belongs to.

Directories are built to be read far more often than they are written. Applications might look Dana up thousands of times a week, while Dana's entry changes a few times a year. That is why so many applications can lean on one directory at once. It also points to a limit. A directory is a good place to publish information, but it is usually not where that information is decided. Dana's department is decided in the HR system and copied into the directory, a distinction the next lesson explores.

Applications reach a directory through a protocol. LDAP, covered in Searching a directory with LDAP, has been used for decades to read directories. SCIM, covered in SCIM users, groups, and schemas, is widely used to create and update accounts. The ideas here apply whichever protocol an application uses.

Entries and attributes

The directory holds an entry for each person, and others for each group and shared resource. An entry is a collection of attributes, each with a name and one or more values. Some attributes hold a single value, such as a job title. Others can hold several: a person might have two phone numbers, and a group's entry lists many members.

Here is Dana's entry, written as a table. The last column matters most for the rest of this lesson.

All names and identifiers in these examples are fictional.

Most of these values are copies of facts that are decided elsewhere. The job title, department, and manager come from HR. The user name and email address come from the clinic's naming rules. The manager attribute deserves a second look, because its value is not a name typed in by hand. It is a reference to another entry, so an application can follow it to the manager's current details, including the manager's own manager when a request needs to go higher.

Identifiers that do not change

Some time after joining, Dana changes surname to Mensah. HR updates Dana's legal name. The clinic's naming rules produce a new user name, dana.mensah, and a new email address, [email protected], and the old address keeps receiving mail for a while so nothing is lost. The display name changes everywhere it is read from the directory.

Three attributes in Dana's entry have just changed. The unique ID has not. It was assigned when the entry was created and stays the same until the entry is deleted, whatever happens to Dana's name, job, or department. Many directories assign an identifier like this, usually a long generated value that means nothing to people and is never reused.

Look at two applications the morning after the change. Patient records stored the directory's unique ID the first time it saw Dana and keeps Dana's preferences and recent patient list under it. When Dana signs in as dana.mensah, patient records looks up the entry, finds the same ID, and carries on as before.

Scheduling stored everything under the email address. When Dana signs in with the new address, scheduling finds no profile for [email protected] and creates an empty one. Dana's shift preferences, saved availability, and pending shift swaps sit under the old address, attached to nobody. Someone will spend an afternoon moving them across by hand. Worse, if the clinic ever gives the address [email protected] to a new employee, scheduling will hand that person Dana's history.

An application should key its records on the identifier that never changes, and treat user names and email addresses as attributes for display and contact. Employee numbers are stable too, but they come from HR and exist only for employees. Dr. Lee Moreau, a locum physician, has a contractor register ID instead, so an application keyed on employee numbers would have no key for Dr. Moreau at all. The directory's own identifier covers everyone who has an entry.

Groups

Applications rarely grant access one person at a time. It is easier to say "everyone in this group can use the pediatrics rota" and then manage who is in the group. In a directory, a group is an entry whose main attribute is its list of members.

Groups differ in how that list is kept up to date. A static group has members that someone adds and removes by hand. "Pediatrics charge nurses" is static at Harbor: the nurse manager asks IT to add someone when they take on the role. Static groups are simple and exact, and they depend entirely on someone remembering to take people out.

A rule-based group, often called a dynamic group, computes its members from attributes. "Oncology nurses" contains everyone whose department is Oncology and whose job is registered nurse. Some directories evaluate rules like this themselves. At Harbor, the identity system evaluates them and updates each group's member list automatically. When Sam Reyes transfers from pediatrics to oncology, HR changes Sam's department, and Sam leaves "Pediatrics nurses" and joins "Oncology nurses" without anyone editing either group. A rule-based group is only as accurate as the attributes it reads, which is where the next lesson picks up.

Groups can also contain other groups. "All nursing staff" might contain "Pediatrics nurses", "Oncology nurses", and "Emergency nurses", so that something granted once to all nurses reaches every unit. These nested groups save effort, and they make it much harder to see who really has access. Suppose someone adds "Students on placement" to "All nursing staff" so that students can read the nursing policies in the shared files. Patient records also gives "All nursing staff" a basic role for viewing ward lists, and now gives it to students too. Anyone checking patient records' settings sees only "All nursing staff", which sounds right. Finding out who is really in it means expanding every level. Applications do not even agree on whether to expand: some follow nested membership, and others look only at direct members, so the same group can mean different things in different systems.

Above all, a group says only "these people". What it grants depends on the systems that use it. The directory has no idea that patient records gives "Pediatrics nurses" the EHR_PED_RW role, that scheduling gives the same group the pediatrics rota, or that email gives it the unit's shared mailbox. Adding one person to that group grants all three. Someone reviewing the group's members needs to know what each system does with it, which is the information an entitlement catalog keeps beside each group.

How applications use a directory

Applications read a directory in a few common ways. They look up attributes: scheduling reads Dana's manager to route shift swap approvals, and email reads display names and job titles for its address book. They check group membership: patient records asks whether Dana belongs to "Pediatrics nurses" before deciding which role applies.

Older designs also check passwords against the directory. Dana types a user name and password into the application, which passes them to the directory and asks whether they are correct. It works, but every application built this way handles Dana's password, and each one runs its own sign-in page with its own idea of how strong a sign-in should be. A compromised application collects the password of everyone who signs in to it.

Federated sign-in moves that job to an identity provider. The application sends Dana to the provider, which authenticates Dana and returns a signed statement about the sign-in, so the application never sees the password. Trust across systems explains how that works, and History of SSO follows how the two approaches came to exist side by side. The directory does not disappear. The identity provider often checks credentials against it, and applications still read attributes and groups from it or receive them in the sign-in message.

Some applications do not ask the directory every time. They copy it into their own database overnight, or remember group memberships for a few hours to avoid repeated lookups, and copies and caches go stale. When Sam's department changes on a Monday morning, an application that copied the directory on Sunday night still sees Sam in pediatrics until its next copy. When a locum's contract ends, an application that cached group membership can keep granting access for hours. A change has not really arrived until every copy has caught up, so it matters which applications keep copies and how often they refresh them.

A directory is only as accurate as the information that reaches it, and most of that information starts somewhere else. Continue to Sources of truth to see which system owns each attribute and what happens when two of them disagree.