LDAP schema

The embedded directory enforces no schema: no object class is required, no attribute syntax is checked, and no must/may is consulted. LDAP explains why and lists the five structural rules it enforces anyway. This service still writes a large and consistent set of object classes and attributes, and this page is the map of them: what each container holds, the classes its entries carry, and every attribute this service reads or writes.

Two things to know first:

• Names starting sts, oauth, saml, fed, spiffe, xacml, gnap, app, x509, krb5 and similar are this service’s own. None is registered and none has an OID. They exist because the standards they serve (OAuth, WebAuthn, SPIFFE, DID Core and so on) came after the LDAP schema documents. Standard names (RFC 4519, RFC 2798 inetOrgPerson, draft-behera password policy, RFC 4530) are used wherever one fits.
• Attribute names are case-insensitive. The directory keeps a table of canonical spellings (STANDARD_NAMES and OWN_NAMES in ldap/ldap_server.js) so that an entry is displayed as written. An attribute missing from that table still works, but is shown lower-cased on /admin/ldap/directory.

In PostgreSQL every entry is one row of sts_ldap_entries, with these attributes in the attrs JSONB column. With persistence.mode=ldif an entry is one LDIF record.

The tree

Each trust realm has its own tree, rooted at the RFC 2247 form of the realm’s DNS domain (LDAP → A tree per trust realm).

dc=example,dc=com                       domain, dcObject
├── ou=users                            people, and every identity that authenticates
├── ou=groups                           groupOfNames
├── ou=applications                     applicationProcess + stsApplication
├── ou=federations                      applicationProcess + stsFederation
├── ou=roles                            stsRole
├── ou=policies                         xacmlPolicy
├── ou=peps                             xacmlPep
├── ou=passwordPolicies                 pwdPolicy + stsPasswordPolicy
├── ou=spiffe
│   ├── ou=entries                      applicationProcess + spiffeRegistrationEntry
│   └── ou=agents                       applicationProcess + spiffeAgent
├── ou=devices                          device + stsDevice          (#130, #164)
├── ou=oidfed                           stsOidfedEntry              (#132)
├── ou=claimproviders                   stsClaimProvider            (#147)
├── ou=trustAnchors                     stsTrustAnchor              (default realm only)
└── ou=crl                              cRLDistributionPoint        (created on first CRL)

Every container is top, organizationalUnit with a description. All of them are seeded, in both modes.

Operational attributes

People: ou=users

objectClass: top, person, organizationalPerson, inetOrgPerson. The RDN is uid=<username>. One person is one entry, however they arrive. An identity that names nobody by itself (a DID, a SPIFFE ID) gets an entry named by a digest of its identifier.

Standard attributes

All the inetOrgPerson attributes (RFC 2798, RFC 4519) can be stored, and /portal draws all fifty of them. This service reads and writes these:

Credentials

Assertion key pairs (RFC 7523 and RFC 7522)

A person may hold a key pair to sign assertions about themselves only. The two sets share no names.

…KeySource says whether the pair was issued here or a certificate was uploaded instead.

Certificates issued by enrollment (ACME, EST, SCEP)

common/cert_enrollment.ts keeps every certificate on the entry it names.

What this service learned about the person

Flags an administrator or a flow sets

Groups: ou=groups

objectClass: top, groupOfNames, with cn, member (DNs) and description. Referential integrity is not enforced: deleting a person leaves their DN in member. A group grants nothing by being a group. It grants only what a roster or a role names it for:

The console groups are created on first grant, and the bootstrap admin holds both. remote-peps and xacml-users are seeded, empty in product mode. In development, demo data adds cn=developers and cn=directory-admins (which grant nothing), the people alice, bob and carol, and cn=admin,<base>.

The names are the defaults of admin.readGroup, admin.writeGroup, roles.remotePepGroup and roles.xacmlUserGroup. The directory also treats groupOfUniqueNames, posixGroup and groupOfURLs entries as groups, and reads uniqueMember and memberUid as well as member.

Applications: ou=applications

objectClass: top, applicationProcess, stsApplication. One entry per client, relying party, service provider, Kerberos service or GNAP client. Nothing caches this registry: an ldapmodify takes effect on the next request. common/applications.js holds the field table, and /admin/applications draws it with a description of every field.

Federation relationships: ou=federations

objectClass: top, applicationProcess, stsFederation. Each relationship is created disabled, and changing one is a security change: see federation. federation/federation.js holds the schema, and /admin/ldap/federations publishes it.

Attribute sources: ou=attributesources

objectClass: top, stsAttributeSource, named cn=<source id>, with the source’s whole definition as one JSON value, stsAttributeSourceData. It holds the database, the row it reads, the column map, when it reads and what a failure does, and never a password (#94). On a person, stsAttributeSourced names each attribute a source wrote (<source>:<attribute>), and stsAttributeSourceSeen records when each source last read them (<source>=<time>). See Attribute sources.

Roles: ou=roles

objectClass: top, stsRole, named cn=<role>, with roleName, description, the three kinds of holder (roleMemberUser, roleMemberGroup and roleMemberApplication), and rolePermission: the permissions a holder may be issued (#303), named as a client asks for them, and roleApplication: the one application a role belongs to (#310). Such a role is named <role>@<application>, and only a token for that application carries it, as <role>. roleAllowedMemberType (user, application, or both when absent) says who may hold the role, and a member of another kind is refused (#93); the two console roles cannot be restricted. displayName is an optional label for the console and the API, and is never what a token carries. The entry’s entryUUID is the role’s stable id. A role saved by an earlier version was written with no object class and gains one on its next save. common/roles.js keeps apart who holds a role and what requires one (appRequiredRole on an application). Which of an application’s permissions need a role at all is oauthRoleGatedPermission on the resource application. Every realm is seeded with two roles, ADMIN_READ and ADMIN_WRITE, which authorize admin:read and admin:write. Their groups come from admin.readGroup and admin.writeGroup and are not stored on the entry; sts-management-api is a member of both. A third seeded role, DEVICE_COMPLIANCE, authorizes device:compliance and has no members until the MDM feed’s application is added (#309). None of the three can be deleted, and their permissions are fixed. The service also computes eight built-in roles that are not stored: EVERYBODY, ALL_AUTHENTICATED_USERS, ALL_UNAUTHENTICATED_USERS, ALL_APPLICATIONS, ALL_AUTHENTICATED_APPLICATIONS, ALL_UNAUTHENTICATED_APPLICATIONS, REMOTE_PEPS and XACML_USER.

XACML: ou=policies and ou=peps

ou=policies is the policy repository itself, not a copy of it (xacml/xacml_store.ts). objectClass: top, xacmlPolicy, with xacmlPolicyId, xacmlVersion, xacmlKind (policy or policy set), xacmlCombiningAlgId, xacmlPolicyDocument (the XACML XML), xacmlPolicy, xacmlEnabled, xacmlIsRoot and xacmlDetail.

ou=peps holds the remote PEPs (xacml/xacml_pep_registry.ts). objectClass: top, xacmlPep, with xacmlPepIdentity, xacmlPepEnabled, xacmlPepCertificateSubject, xacmlPepThumbprint, xacmlPepBias, xacmlPepResource, xacmlPepNotifyUrl, xacmlPepVersion, xacmlPepRegisteredAt, xacmlPepLastSeen, xacmlPepLastNotify, xacmlPepSyncToken, xacmlPepPolicyCount, and the counters xacmlPepDecisions, xacmlPepAllowed, xacmlPepRefused, xacmlPepAuthenticated and xacmlPepUndischargeable. See remote PEP.

Password policies: ou=passwordPolicies

objectClass: top, pwdPolicy, stsPasswordPolicy. The draft-behera attributes pwdAttribute, pwdMinLength and pwdInHistory sit beside this service’s stsPwd* attributes (stsPwdRequireUppercase, stsPwdRequireDigit, stsPwdMinSymbols, stsPwdGeneratedLength and others), which cover the composition rules and the generator. The default profile is not seeded: the defaults apply until an administrator saves one. See common/password_policy.ts.

SPIFFE: ou=spiffe

The registry is kept in the directory (spiffe/spiffe_registry.ts).

Registration entries (ou=entries, objectClass: top, applicationProcess, spiffeRegistrationEntry): spiffeEntryId, spiffeId, spiffeParentId, spiffeSelector, spiffeX509SvidTtl, spiffeJwtSvidTtl, spiffeDnsName, spiffeFederatesWith, spiffeAdmin, spiffeDownstream, spiffeHint, spiffeStoreSvid, spiffeEntryExpiresAt, spiffeRevisionNumber, spiffeCreatedAt, spiffeOrigin, spiffeSvidsIssued, spiffeLastSvidAt.

Attested agents (ou=agents, cn=agent-<12 hex>, objectClass: top, applicationProcess, spiffeAgent): spiffeAgentId, spiffeAttestationType, spiffeAgentSelector, spiffeAgentSvidHash, spiffeAgentExpiresAt, spiffeAgentBanned, spiffeAgentCanReattest, spiffeAttestations, spiffeFirstSeen, spiffeLastSeen.

Deleting an entry, or banning or deleting an agent, sets spiffeCredentialStatus on the affected people in ou=users.

Devices: ou=devices (#130, #164)

Every phone, computer and host the realm knows, each owned by ONE person or ONE application. Made by OpenID Connect Native SSO for Mobile Apps 1.0 (OAuth 2.0 and OpenID Connect) and by an administrator on Directory → Devices or POST /admin-api/devices/create; see Devices. People see theirs on /portal/devices; /admin/ldap/devices shows the entries as the directory holds them, with this schema.

The DN is cn=<uuid>,ou=devices,<base>, and common/devices.ts owns what an entry means.

The secret is never rotated, because every app on the device shares it. A new sign-in that presents the secret re-binds the same device to the new session; a device given to another owner loses it. One person holds at most devices.maxPerPerson devices: at that limit a Native SSO sign-in replaces the least recently used device whose session has ended (or, if none has ended, the least recently used one), and an administrator’s registration is refused.

OpenID Federation: ou=oidfed (#132, #136, #137)

The realm’s register as an OpenID Federation entity (OpenID Federation). Every entry is of class stsOidfedEntry and is named cn=<prefix><digest>, where the digest is SHA-256 of what the entry is about (hex, 32 characters). oidfed/oidfed_store.ts owns what an entry means.

Claims Providers: ou=claimproviders (#147)

The OpenID Providers this realm fetches aggregated or distributed claims from (OpenID Connect). One entry per provider, named cn=<id>; oauth-oidc/claims_providers.ts owns what an entry means.

Trust anchors and CRLs

ou=trustAnchors exists only in the default realm, with one objectClass: top, stsTrustAnchor entry per CA trusted for client certificates: stsTrustAnchor, stsTrustAnchorCertificate, stsTrustAnchorFingerprint, stsTrustAnchorAddedBy. A certificate is public, so none of these is sealed. An entry here decides whose client certificate becomes an identity. See TLS.

ou=crl holds objectClass: top, cRLDistributionPoint entries (cn=<caId>, certificateRevocationList;binary) once a CRL is published. They are a cache of the register, readable anonymously (PKI).

What an LDAP read never returns

In product mode (mode.withholdsDirectorySecrets()), these attributes are withheld from every search result, filter and compare, administrators included (SECRET_ATTRIBUTES in ldap/ldap_server.js):

• passwords: userPassword, pwdHistory, stsAppPassword, stsActivationToken, stsPasswordResetToken, stsMailVerifyToken
• second factors and subjects: stsTotpCredential, stsBackupCodes, stsSelfIssuedSubject, stsIdaVerification, stsCibaUserCode
• devices: stsDeviceSecretHash
• client secrets: oauthClientSecret, appRegistrationAccessToken, fedClientSecret, stsClaimProviderSecret
• tokens held for a person at another provider: stsClaimSourceTokens
• private keys: oauthAssertionPrivateKey, oauthSamlAssertionPrivateKey, stsAssertionPrivateKey, stsSamlAssertionPrivateKey, stsEnrolledPrivateKey, appEnrolledPrivateKey, fedEncryptionKey
• enrollment credentials: stsAcmeEabKey, appAcmeEabKey, stsScepChallenge, appScepChallenge
• Kerberos and GNAP keys: stsKrb5Keys, krb5ServiceKeys, gnapSymmetricKey, gnapMacaroonKey
• devices: stsDeviceSecretHash (from #130)
• the Federation Entity Key table: stsOidfedKeys (from #132)

Some are withheld in every mode, replaced by a placeholder in searches and in the directory dump: the certificate-enrollment secrets, the Kerberos keys, and the private key inside each fedEncryptionKey row and each stsOidfedKeys row.

Hashed (scrypt): userPassword, pwdHistory, the activation, reset and mail-verification tokens, each recovery code and each app password. stsScepChallenge holds a SHA-256 digest. Sealed ($aesgcm$1$… under the key-encryption key, in product; clear in development): the TOTP secret, stsKrb5Keys, krb5ServiceKeys, every RFC 7523 and RFC 7522 private key, the EAB keys, enrolled private keys and fedEncryptionKey private keys. oauthClientSecret, appRegistrationAccessToken, fedClientSecret and stsIdaVerification are sealed too, but only where the key-encryption key is durable (not development’s ephemeral one, and not a product-mode realm inside a development process). Encryption at rest has the rest.

pwdHistory and pwdChangedTime are maintained by the service and refused on an LDAP write. Product refuses a pre-hashed $scrypt$ userPassword.

In product mode, what a bound identity may read and write is decided per identity, and only a person may bind: see LDAP → What a bound identity may read.

Keeping this page current

This page is a copy of tables that live in code, so it can drift. The sources:

• ldap/ldap_server.js: STANDARD_NAMES, OWN_NAMES, SECRET_ATTRIBUTES, and seed() for the containers
• common/applications.js: the application field table
• federation/federation.js, spiffe/spiffe_registry.ts, xacml/xacml_store.ts, xacml/xacml_pep_registry.ts, common/roles.js, common/password_policy.ts, common/devices.ts

A running service describes its own containers: /admin/ldap/directory shows any entry, and /admin/ldap/federations shows the federation schema.

Related

• LDAP: the protocol, the sockets, the five rules and the settings.
• PostgreSQL schema: where these entries are stored.
• SCIM 2.0: how SCIM attributes map onto these.