This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.

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=attributePolicies                stsAttributePolicy          (#396)
├── ou=attributeDefinitions             stsAttributeDefinition      (#396)
├── 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=signerTrustAnchors               stsSignerTrustAnchor        (#1360)
└── 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

Attribute Source Notes
entryUUID RFC 4530 assigned at creation and kept through a rename. A person’s sub is urn:uuid:<entryUUID>, and a SCIM id is the bare value. Returned only when asked for by name. No client can write it (STS-LDAP-0076)
createTimestamp, modifyTimestamp RFC 4512 generalized time. Read-only in product mode
entryDN RFC 5020 computed at search time; read-only in product mode
stsEntryUuidAlias this service the losing entryUUID of a two-process create race, resolved to the same entry. Protected like entryUUID
memberOf computed a person’s groups, derived from member values, never stored

People: ou=users

objectClass: top, person, organizationalPerson, inetOrgPerson. The RDN is uid=<username>. One person is one entry, however they arrive by a protocol that folds names together. An identity that names nobody by itself (a DID, a SPIFFE ID) gets an entry named by a digest of its identifier. A person a federated sign-in creates is a different entry from a local person who shares the part before @: the uid is <relationship>~<subject> (Federation).

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:

Attribute Use
uid, cn, sn, givenName, displayName, mail the person. In development mode an auto-created entry gets invented values; product mode invents none
userPassword scrypt hash ($scrypt$N$r$p$salt$hash), hashed on every write including an LDAP modify. Withheld from reads in product mode
userCertificate RFC 4523, stored as userCertificate;binary (base64 DER). A certificate from an outside certificate authority is an identity only as the one entry storing it here, byte for byte (TLS). Written by Stored certificates on a person’s console page, POST /admin-api/users/add-certificate and remove-certificate, or an LDAP modify. Looked up by the SHA-256 of the DER, which the store indexes
title, employeeType, telephoneNumber, mobile, street, l, st, postalCode, c, postalAddress, o, ou, departmentNumber, employeeNumber, preferredLanguage, labeledURI, manager released as claims (oid4vc/vc_claims.ts) and mapped by SCIM (scim/scim_map.ts)
schacDateOfBirth, schacCountryOfCitizenship, schacPersonalTitle SCHAC names, released as birthdate, nationalities, title
salutation, birthFamilyName, birthGivenName, birthMiddleName, alsoKnownAs, placeOfBirthCountry, placeOfBirthRegion, placeOfBirthLocality this service’s own, for Identity Assurance claims
schacGender, middleName, timeZone, pictureUrl, profileUrl the profile scope’s gender (SCHAC, ISO/IEC 5218 codes, answered male, female, not known or not applicable), middle_name, zoneinfo, picture and profile (#1292); all but schacGender are this service’s own
stsProfilePhoto a person’s profile photo: which image is theirs and whose it was, as one JSON value. Withheld from every read, and written only by the portal and a federated sign-in. The image is not on the entry, and while a person has one pictureUrl holds its address. jpegPhoto is a separate attribute this service neither reads nor writes
scimExternalId SCIM externalId, on people and groups
userPrincipalName read by certificate enrollment’s smartcard-logon profile. Nothing in the service writes it; a client supplies it
pwdChangedTime, pwdHistory draft-behera password policy: when the password last changed, and earlier hashes for the history rule
pwdReset draft-behera: the password must be changed at the next sign-in
pwdAccountLockedTime draft-behera. The account is disabled while this is set (000001010000Z means an administrator disabled it), and every door refuses the person. common/account_state.ts is the only writer

Credentials

Attribute What it holds Protection
stsWebauthnCredential registered WebAuthn public keys public by design
stsTotpCredential the RFC 6238 shared secret sealed under the key-encryption key in product mode. Withheld from reads
stsBackupCodes JSON: each code’s scrypt hash and usedAt, plus counts hashed per code (older sealed sets are still read). The comment in OWN_NAMES saying “encrypted” is out of date
stsAppPassword JSON per app password: name, the doors it is scoped to, scrypt hash, last use (#101) withheld
stsActivationToken, stsActivationExpires an activation link’s hash and expiry hashed
stsPasswordResetToken, stsPasswordResetExpires a reset link’s hash and expiry withheld
stsKrb5Keys, stsKrb5KeyInfo Kerberos long-term keys for every enctype, derived from the password, and their public half (kvno, enctypes, when) keys sealed and withheld, including the ciphertext
hobaPublicKey RFC 7486 HOBA keys, <kid> <base64 DER> public
stsSelfIssuedSubject SIOPv2 subjects the person enrolled (a DID or a JWK thumbprint URI), as JSON (#129) withheld
stsPublishedDid Each did:web this realm publishes for the person, as JSON: its random id, the DID, who holds its key, every version of its keys and what authorized each, its deactivation, and in realm custody the private key, sealed (#1291). See Published DIDs withheld
stsCibaUserCode the CIBA user code the person set on /portal/ciba (#131) scrypt-hashed, withheld
stsAudSub the account id a client knows the person by, <client_id> <aud_sub> per value, sent as that client’s ID Token aud_sub (#148) plain
stsClaimSourceTokens the person’s access and refresh tokens at each Claims Provider they linked on /portal/claim-sources, one JSON value (#147) sealed where keys persist, withheld

Assertion key pairs (RFC 7523 and RFC 7522)

A person may hold key pairs to sign assertions about themselves only — several per profile since #1290, up to pki.personSigningKeyMax valid ones. The two sets share no names.

JWT (RFC 7523) SAML (RFC 7522)
stsAssertionIssuer stsSamlAssertionIssuer
stsAssertionKeyPair (one JSON record per key pair) stsSamlAssertionKeyPair (one JSON record per key pair)
stsAssertionPrivateKey (one value per key pair issued here; sealed, withheld) stsSamlAssertionPrivateKey (sealed, withheld)

A record carries the handle (kid, or the certificate thumbprint), the certificate and its chain (and for JWT the public JWK with x5c), the serial and the authority that signed it, the label, source (issued here or a certificate uploaded instead), the validity, and — when it was revoked here — withdrawnAt and withdrawnReason.

Certificates issued by enrollment (ACME, EST, SCEP)

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

Attribute Notes
stsEnrolledCertificate public
stsEnrolledPrivateKey present only when this service generated the key (EST /serverkeygen). Withheld
stsAcmeEabKey the ACME External Account Binding key. Withheld
stsScepChallenge a single-use SCEP challenge password. Withheld
stsCertificateHostName host names an administrator registered for this entry

What this service learned about the person

Attribute Meaning
authnMethod, mfaAuthenticated, mfaLastAuthTime how they last authenticated, where the protocol said. mfaLastAuthTime is never cleared
x509subject, x509issuer, x509serialNumber, x509notBefore, x509notAfter, x509fingerprint256 a verified client certificate this service issued, or an issued X509-SVID. Entries made from an outside certificate’s subject before #1061 keep theirs; none is made now
x509svidsIssued, x509firstIssued, x509lastIssued X509-SVIDs only: how many have been issued, and since when
didSubject, didMethod the DID this entry is. The entry is found by didSubject
spiffeSubject, spiffePath, spiffeTrustDomain the SPIFFE ID that authenticated. These are not the same as spiffeId on a registration entry
spiffeCredentialStatus, spiffeCredentialStatusReason, spiffeRevokedAt whether this identity may still be issued an SVID. This is not a certificate status
federationRelationship, federationIssuer, federationLastSeen where a federated person came from. federationLastSeen is what fedProvisionIdleMinutes reads
federationLink <relationship> <issuer> <subject>: the one that decides anything, linking a partner’s subject to this person (#109)
federationAttribute which of the entry’s other attributes came from a partner’s assertion
stsProvisionedBy federation:<relationship>, written once, by the federated sign-in that CREATED the entry (an enterprise partner or a consumer provider). A sign-in that links or reaches somebody already here writes nothing. No door may write or remove it (constraintViolation over LDAP), and it travels with the entry. An entry without it is native, and only native people are found by /portal/delegate’s search
oauthConsent <time> <scope> <client_id>, one value per (application, scope)
oauthConsentWithdrawn <time> <scope> <client_id> (#172). It stops a re-consent from reviving an older refresh token
stsIdaVerification OpenID Connect for Identity Assurance verifications as JSON (#127). Withheld, because evidence carries document numbers

Flags an administrator or a flow sets

Attribute Meaning
stsMfaRequired a second factor is required of this person
stsBootstrapAdministrator, stsConsoleClaimedAt the bootstrap admin, and when it first claimed the console
stsNotDelegated sensitive and cannot be delegated (Kerberos’s NOT_DELEGATED) (#108)
stsMayAct the one party this person named as a delegate. It becomes may_act in their access tokens
stsAuthzenApplication the applications this person or service account may ask the AuthZEN API about, one per value; set by an administrator only (#563)
stsAuthzenCallbackUri the https URLs this person or service account, as an AuthZEN PEP, may name as an access request’s callback, one per value; set by an administrator only (#1180)
stsServiceAccountPolicy the named service-account policy a service account is governed by, or default; single-valued, held only by a service account and cleared with stsServiceAccount. Set on the person’s Policies tab, with POST /admin-api/users/set-attribute, or by an LDAP modify, each checked against the realm’s policies (#1240)
stsMailVerified the address they proved they receive mail at (#63)
stsMailVerifyToken, stsMailVerifyExpires, stsMailVerifyAddress a pending verification link. The token is withheld
stsPseudonym another name this person can sign in with, in place of their uid (#644). At most eight. A live value is in the username index. An email an administrator sets is live; one the person adds waits for its link. People
stsPseudonymVerifyToken, stsPseudonymVerifyExpires, stsPseudonymVerifyAddress a pending sign-in name. The token is withheld. The address is absent from the username index

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:

Group Grants
cn=admin-read the console and /admin-api read role
cn=admin-write the console and /admin-api write role
cn=remote-peps REMOTE_PEPS: /xacml/pep/* and POST /xacml/pip
cn=xacml-users XACML_USER: the XACML PDP and policy surfaces

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.

A group may name the policy its members are held to, one attribute per kind of policy: stsPasskeyPolicy, a named passkey policy or default, stsLocalePolicy, a named locale policy or default, stsPasswordPolicy, a named password policy or default, stsAuthnPolicy, a named authentication policy or default, stsPostLoginPolicy, a named post-login profile or default, and stsAttributePolicy, a named attribute policy (below). It is set on the group’s page or with POST /admin-api/groups/set-policy, which accepts only a policy the realm holds. The holder names the policy; the policy lists nobody. See Policies.

A group fedProvisionGroups creates also carries federationRelationship, the relationship id that created it. A later sign-in through that relationship may add people only to groups carrying that mark. A token that names admin-write, or any other group the relationship did not create, does not add the person to it.

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.

Group Attributes
Identity and observation appIdentifier, cn, appName, description, appHomePageUrl, appKind, appProtocol, appAllowedProtocol, appAuthorizationServer, appCorsOrigin, appRegistered, appRegisteredBy, appFirstSeen, appLastSeen, appAuthentications, appSessions, appUsers, appLastSession, appLastUser, appRedirectUriObserved, oauthGrantTypeObserved, oauthResponseTypeObserved, appReturnAddressObserved, appRegistrationJson, appRegistrationAccessToken
OAuth client oauthClientId, oauthConfidential, oauthClientSecret (withheld; one JSON record per secret, each with its own expiry, sealed at rest where keys persist), oauthTokenEndpointAuthMethod, oauthTokenEndpointAuthSigningAlg, oauthJwks, oauthJwksUri, oauthRedirectUri, oauthGrantType, oauthResponseType, oauthScope, oauthAllowedScope, oauthAudience, oauthSubjectType, oauthSectorIdentifierUri
Logout oauthPostLogoutRedirectUri, oauthFrontchannelLogoutUri, oauthFrontchannelLogoutSessionRequired, oauthBackchannelLogoutUri, oauthBackchannelLogoutSessionRequired, oauthRevokeRefreshOnLogout
Requests and responses oauthRequestUri, oauthRequestObjectSigningAlg, oauthRequestObjectEncryptionAlg, oauthRequestObjectEncryptionEnc, oauthRequireSignedRequestObject, oauthRequirePushedAuthorizationRequests, oauthHttpSignedRequests, oauthIntrospectionSignedResponseAlg, oauthIntrospectionEncryptedResponseAlg, oauthIntrospectionEncryptedResponseEnc, oauthIdTokenSignedResponseAlg, oauthIdTokenEncryptedResponseAlg, oauthIdTokenEncryptedResponseEnc, oauthUserinfoSignedResponseAlg, oauthUserinfoEncryptedResponseAlg, oauthUserinfoEncryptedResponseEnc, oauthAuthorizationSignedResponseAlg, oauthAuthorizationEncryptedResponseAlg, oauthAuthorizationEncryptedResponseEnc, oauthDefaultAcrValues, oauthDefaultMaxAge, oauthAuthorizationDetailsType, oauthAuthorizationDetailsTypes, oauthStepUpAcrValues, oauthStepUpMaxAge
AuthZEN (#563) authzenAttribute (a catalogue row, on sts-authzen-api), appAuthzenApplication (an application caller’s scope), appAuthzenCallbackUri (an application caller’s access request callback URLs, #1180)
Fine-grained authorization (#564) appFgaPolicy (the entry name of the policy it owns in ou=policies), appFgaEnforced (TRUE when that policy is enforced)
Resource server and consent oauthPermissionBaseUri, oauthPermission, oauthDelegatedPermission, oauthResourceMetadata, oauthResourceMetadataUrl, oauthGlobalConsent, oauthGlobalConsentWithdrawn
Token lifetimes oauthAccessTokenTtlS, oauthIdTokenTtlS, oauthRefreshTokenTtlS, oauthRefreshIdleSeconds, oauthTokenExchangeRefreshToken
Mutual TLS (RFC 8705) oauthTlsClientAuthSubjectDn, oauthTlsClientAuthSanDns, oauthTlsClientAuthSanUri, oauthTlsClientAuthSanIp, oauthTlsClientAuthSanEmail, oauthTlsClientCertificateBoundAccessTokens, oauthTlsClientCertificateThumbprint
JWT assertion key pair (RFC 7523) oauthAssertionIssuer, oauthAssertionJwks, oauthAssertionKid, oauthAssertionCertificate, oauthAssertionCertificateChain, oauthAssertionPrivateKey (withheld), oauthAssertionExpiresAt, oauthAssertionKeySource
SAML assertion key pair (RFC 7522) oauthSamlAssertionIssuer, oauthSamlAssertionSigningCertificate, oauthSamlAssertionCertificate, oauthSamlAssertionCertificateChain, oauthSamlAssertionPrivateKey, oauthSamlAssertionThumbprint, oauthSamlAssertionExpiresAt, oauthSamlAssertionKeySource
Software statements (RFC 7591) oauthSoftwareStatementIssuer, oauthIssuedSoftwareStatement, appSoftwareStatementIssuer, appSoftwareStatementTrusted, appSoftwareStatementPublisher
OpenID Provider Commands (#151) oauthCommandEndpoint (https, no fragment: where a Command Token is POSTed)
CIBA (#131) oauthBackchannelTokenDeliveryMode (poll, ping or push), oauthBackchannelClientNotificationEndpoint (https, for ping and push), oauthBackchannelAuthenticationRequestSigningAlg (an asymmetric alg: every request signed), oauthBackchannelUserCodeParameter (TRUE: every request carries the person’s user code)
Native SSO (#130) oauthNativeSso (TRUE lets the client ask for device_sso), oauthNativeSsoGroup (the apps that may share one device session). Settable by a registration only through a trusted software statement
The did claim (#693) oauthDidClaimWithPairwise (TRUE: a pairwise or ephemeral client may still be told the person’s preferred DID, the did claim; anything else, never). Not settable by a registration
SAML service provider samlEntityId, samlAssertionConsumerService, samlSingleLogoutService, samlNameIdFormat, samlResponseBinding, samlSigningCertificate, samlObservedSigningCertificate, samlEncryptionCertificate, samlAuthnRequestVerification, samlAuthnRequestSigned, and from consumed metadata: samlSpMetadataUrl, samlSpMetadata, samlAcsEndpoint, samlSloEndpoint, samlSpNameIdFormat, samlSpAuthnRequestsSigned, samlSpWantAssertionsSigned, samlSpWantAssertionsEncrypted, samlSpMetadataValidUntil, samlSpMetadataCacheDuration, samlSpMetadataConsumedAt, samlSpMetadataSignature, samlSpMetadataSigningCertificate
SAML per-profile saml2AssertionLifetimeMin, saml2SignAssertion, saml2SignResponse, saml2NameIdFormat, saml2ArtifactTtlS, saml2EncryptAssertion, saml2EncryptionAlgorithm, saml2KeyTransportAlgorithm, saml2EncryptLogoutNameId, saml11AssertionLifetimeMin, saml11SignAssertion, saml11SignResponse, saml11NameIdFormat, saml11ArtifactTtlS
WS-* wsfedRealm, wsfedReplyUrl, wsfedSignOutUri, wsfedAssertionLifetimeMin, wstrustAppliesTo, wstrustJwtScope
Who may start a sign-in (#426; Identity-provider-initiated sign-in) saml2IdpInitiatedSso, saml2SpInitiatedSso, saml11IdpInitiatedSso, saml11SpInitiatedSso, wsfedIdpInitiatedSso, wsfedSpInitiatedSso, oauthThirdPartyInitiatedLogin, oauthSpInitiatedSso (each TRUE or FALSE, overriding the realm setting of the same name; identity-provider-initiated is off by default), oauthInitiateLoginUri (OpenID Connect Core section 4’s initiate_login_uri; https, no fragment), appLaunchProtocol (saml2, saml11, wsfed or oidc: what /launch/{app} starts when the link names none)
What the sign-in and consent screens show (#1300; Dynamic Client Registration) oauthLogoUri, oauthPolicyUri, oauthTosUri (OpenID Connect Registration section 2’s logo_uri, policy_uri and tos_uri; absolute https; the browser loads the logo, this service never fetches it)
Kerberos service krb5ServicePrincipalName, krb5ServiceKeys (sealed), krb5ServiceKeyInfo
Delegation (#108, #186; Delegation and impersonation) appAllowedToDelegateTo, appAllowedToActOnBehalfOf, appDelegationSemantics, appDefaultDelegationSemantics, appDelegationSubjectGroup, appNotDelegated, appMayAct, and for a Kerberos service krb5TrustedForDelegation
Roles and claims appRequiredRole, appGroupsClaim, appGroupsClaimName, appGroupsClaimValue, appGroupsClaimFromMemberOf, appAuthnPolicy (the named authentication policy it signs in under; it replaced appAuthnMechanism and appMfaMechanism), appPasskeyPolicy (the named passkey policy a sign-in to it is held to), appLocalePolicy (the named locale policy its pages and the people it creates fall back to), appPasswordPolicy (the named password policy a password set while signing in to it is held to), appPostLoginPolicy (the named post-login profile a sign-in to it follows)
Certificate enrollment appEnrolledCertificate, appEnrolledPrivateKey, appAcmeEabKey, appScepChallenge, appCertificateHostName
GNAP gnapInstanceId, gnapClassId, gnapKey, gnapKeyIdentity, gnapKeyReference, gnapKeyProof, gnapMtlsTrust, gnapSymmetricKey (withheld), gnapSymmetricAlg, gnapDisplayUri, gnapLogoUri, gnapFinishUri, gnapInteractionStartModes, gnapAllowedAccess, gnapBearerTokens, gnapSkipInteraction, gnapAccessTokenFormat, gnapAccessTokenLifetimeS, gnapResourceServerUri, gnapOwnerLookupUri, gnapJweKey, gnapMacaroonKey, gnapScopedSignals
Links to other registries oid4vpClientId, federationPartnerId, appFederationRelationship, appFederationAutoRedirect, ldapBindDn, scimClientId, ssfReceiverId, ssfDeliveryEndpoint, ssfAllowedEvents, spiffeWorkloadId

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.

Group Attributes
Identity fedId, fedName, fedEnabled, fedProtocol, fedRole, fedPeer, fedLocalEntityId, fedApplication, fedApplicationUse
Endpoints fedSsoUrl, fedSloUrl, fedSloBinding, fedBinding, fedTokenUrl, fedUserinfoUrl, fedEndSessionUrl, fedJwksUri
Keys fedSigningCertificate (decides whose assertions are believed), fedJwks, fedEncryptionKey (withheld), fedEncryptionKeyType, fedKeyManagementAlgorithm, fedContentEncryptionAlgorithm, fedSignRequest
OIDC as client fedClientId, fedClientSecret (withheld), fedScope, fedResponseType
Policy fedAllowUnsolicited, fedAllowUnencrypted, fedAcceptSignout, fedRequireSignedLogout, fedMayAssertAdministrators, fedAuthnMechanism, fedAuthnRelationship
Subjects and provisioning fedSubjectPolicy, fedSubjectPattern, fedSubjectDomain, fedSubjectGroup, fedHomeRealmDomain (#148, the domains whose domain_hint goes to this partner), fedUsernameSource, fedAutocreateUsers, fedUpdateUserAttributes, fedProvisionGroups, fedProvisionCap, fedProvisionIdleMinutes, fedAttributeMap, fedRelease
Observation fedFirstSeen, fedLastSeen, fedLastUser, fedUsers, fedAuthentications, fedLastError, fedLastErrorAt

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, roleConferredBy: the clients that confer the role on every person who signs in through them, on that client’s token alone (#454), 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-api-client 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). A fourth, ADMIN_CONSOLE, authorizes admin:console and has no members either: it is conferred by the console’s client, sts-admin-console, on everybody who signs in to the console (#454). Two more, SSF_READ and SSF_MANAGE, authorize ssf.read and ssf.manage. They are ordinary native roles, not the console roster: the groups ssf-read and ssf-manage are stored on roleMemberGroup, created empty when missing and never overwritten. A person is issued the scope only while they belong to the role’s group and the application is a member; an application’s own token needs the application to be a member. SSF_MANAGE does not authorize ssf.read. Two more, REPORT_USE and REPORT_ADMIN (#1030), authorize report:use and report:admin through the groups report-users and report-admins, stored and seeded the same way; a person is issued the scope while they are in the group or a direct member, and an application while it is a member, with no condition on the application the person signs in to. None of the eight can be deleted, and their permissions are fixed. A role only applications may hold, and the two console roles, cannot be conferred. 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. A policy an application owns also carries xacmlApplication (the application’s identifier) and, once that application is deleted, xacmlOrphanedAt; see fine-grained authorization.

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. A named policy is cn=<name> beside it, with the same attributes and stsPasswordPrecedence (1 to 1000); a group names one in stsPasswordPolicy and an application in appPasswordPolicy. See common/password_policy.ts.

Attribute policies and custom attributes: ou=attributePolicies, ou=attributeDefinitions

cn=default,ou=attributePolicies is objectClass: top, stsAttributePolicy with stsAttributeRequired (one value per attribute every person must hold, besides uid, cn and sn) and an optional description. Absent, the default realm’s applies, then the built-in default (givenName, sn, mail).

A realm’s named attribute policies (#1241) are cn=<name> beside it, with the same attributes and stsAttributePolicyPrecedence (1 to 1000). They belong to the realm and are never inherited. A person names one with stsAttributePolicy on their own entry under ou=users, and a group names one with the same attribute on its own entry. The value is default or the policy’s name, and only one value is allowed. Of the policies the person and their groups name, the one with the lowest precedence applies.

cn=<name>,ou=attributeDefinitions is one of the realm’s custom attributes: objectClass: top, stsAttributeDefinition, stsAttributeLabel, stsAttributeSyntax (string, integer, boolean, date, email, uri, dn), stsAttributeSingleValued (TRUE or FALSE), an optional description, and since #700 stsAttributePortalVisible and stsAttributePortalEditable (TRUE or FALSE; absent is FALSE): whether the person sees their own values on the user portal, and whether they may change them there. Editable implies visible. Its values are stored on a person under that name, like any other attribute. See common/attribute_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.

Attribute Meaning
objectClass top, device (RFC 4519 §3.4), stsDevice
cn the device id, a UUID this service assigned
owner the DN of its one owner: a person or an application (RFC 4519)
stsDeviceOwnerKind person or application
description what to call it on a page
stsDeviceApplication the DN of every application that has used it
stsDeviceKey one JSON value per key it is recognised by: id, kind (x509, jwk, webauthn), thumbprint, label, added, addedBy, proof, attestation (level, format, summary, verifiedAt) and the public material. Never a secret
stsDeviceKeyThumbprint <kind>:<thumbprint> per key, derived from stsDeviceKey so a filter can find a device by its key. A thumbprint is base64url SHA-256: RFC 7638 for a JWK (DPoP’s jkt) and a WebAuthn credential’s key, the SubjectPublicKeyInfo for a certificate
stsDeviceAttestation attested when any key’s attestation was verified, otherwise self-asserted. Derived
stsDeviceCompliance compliant or not-compliant; absent is unknown
stsDeviceComplianceChange JSON: the last change — status, previous, at, source (admin, mdm, test-control, caep), actor, reason
stsDeviceStatus compromised; absent is active
stsDeviceStatusChange JSON: the last status change
stsDevicePlatform ios, ipados, android, macos, windows, linux, chromeos or other
stsDeviceModel, stsDeviceOs descriptive text
stsDeviceEnrolment JSON: method (native-sso, admin, portal, est, scep), at, actor
stsDeviceSecretHash SHA-256 of its Native SSO device_secret. Withheld from every read
stsDeviceSession the sign-on session the secret is good for. The secret is accepted only while that session is live
stsDeviceLastUsed ISO 8601

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.

Attribute Meaning
objectClass top, stsOidfedEntry
stsOidfedKind keys, subordinate (sub-), anchor (ta-), mark-type (mt-), issued-mark (im-), held-mark (hm-), mark-policy (mp-), events (ev-, #137), suspension (su-, #137) or collection (the one cn=collection entry, #136)
stsOidfedEntityId the Entity Identifier the entry is about
stsOidfedData the record, as one JSON value: a subordinate’s keys, metadata, metadata policy and constraints; an anchor’s pinned keys; a mark and its status; a suspension’s time, reason and page; the last Entity Collection crawl. An events or suspension entry about a realm of this service is keyed realm:<id> rather than by identifier
stsOidfedEvent on an events entry: one subordinate’s history, one JSON event per value (iat, event, and event_description and information_uri where given). Appended and never rewritten, and merged by value when two nodes write at once. The entry outlives the subordinate
stsOidfedKeys on the one cn=keys entry: the realm’s Federation Entity Key table, one JSON row per value, each private key sealed where keys persist. Withheld from every read, and each row’s private key is replaced by a placeholder in searches and in the directory dump

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.

Attribute Meaning
objectClass top, stsClaimProvider
stsClaimProviderData the provider, as one JSON value: its id and name, issuer, authorization, token, claims and JWKS endpoints, this realm’s client id and authentication method there, the scope asked for, the claims it supplies, and aggregated or distributed
stsClaimProviderSecret this realm’s client secret at the provider. Sealed where keys persist, and withheld from every read

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=signerTrustAnchors exists in every realm, with one objectClass: top, stsSignerTrustAnchor entry per certificate of that realm’s signer truststore: stsTrustAnchorCertificate, stsTrustAnchorFingerprint, stsTrustAnchorAddedBy, stsSignerTrustAnchorKind (anchor or intermediate) and, where it is restricted, stsSignerTrustAnchorPurpose (multi-valued). An entry here decides whose signature the realm believes.

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, stsPublishedDid, 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 the model, so it can drift. The sources:

  • models/directory/names.tsp: the standard and own spellings, and the attributes withheld from every reader
  • ldap/ldap_server.js: seed() for the containers
  • models/directory/application.tsp: the application field table
  • models/directory/: the role, device, service account, SPIFFE, XACML, federation and policy tables

models/directory/ holds these names as TypeSpec. Directory models is that inventory in reading form, rewritten when the model is written. This page stays the explanation. The directory still enforces nothing.

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

  • Abstract data model: the directory, API, and persistence namespaces, and where each generated file lives.
  • 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.