Development edition · 16 November 2026. Commands using repository paths, Make targets or sample projects require access to the Quinzee source checkout. No public installer is available. Examples use disposable local environments.
6. Operate the shared Entra and LDAP directory
The identity authority stores applications, service principals, managed identities, users, groups and assignments. Entra's HTTPS APIs and LDAP read the same authoritative records. There is no password synchronization job. LDAP is a protocol view, not the underlying database and not a second source of users.
Step 1: decide when to use PostgreSQL
Without a PostgreSQL configuration, existing installations retain private JSON directory storage. Actual LDAP service requires the PostgreSQL backend. Use a dedicated database owned by the directory service user. Do not place it inside an application resource group whose deletion could remove your management identity store. The ordinary PostgreSQL module provisions application databases; it does not automatically create or own the directory database.
For a local directory service, prepare a TLS server certificate valid for
localhost, its key and CA. The standard native cloud development certificate
contains localhost and can be used for this isolated lab:
python3 infrastructure/directory/postgres.py start \
--directory "$PWD/.local/directory-postgres" \
--certificate "$PWD/.local/certificates/quinzee.cloud/server.crt" \
--key "$PWD/.local/certificates/quinzee.cloud/server.key" \
--ca "$PWD/.local/certificates/ca/quinzee-dev-root-ca.crt"
The helper uses the repository's pinned PostgreSQL image and writes a mode-0600
postgres.json inside its mode-0700 directory. It publishes localhost port 15432.
Use --port for a different port; 0 requests an automatically assigned host
port and the generated configuration records it. start of an existing owned
container preserves its established configuration; editing the launch arguments
does not reconfigure that container. stop --directory <same-path> stops it and
preserves data. Its folder path is part of the ownership identity; do not rename
it casually.
This loopback connection file is for a native cloud process on the same host. Inside a cloud container, localhost names that container. For that deployment, provide a reachable database hostname, a matching certificate and mounted trust paths; do not copy the native loopback configuration unchanged.
Step 2: migrate deliberately
- Stop directory changes and take a consistent backup of existing cloud data.
- Check the generated PostgreSQL connection file and trust path.
- Start the cloud with
--directory-postgres-config <absolute-file-path>. - Verify the existing tenant, application IDs, principals and users in QHQ.
- Restart and verify them again before allowing new changes.
For a separately supplied PostgreSQL service, the private JSON file accepts
only string-valued host, port, dbname, user, password and sslrootcert.
TCP uses verify-full; the host must match the database certificate. An absolute
Unix socket directory in host selects local socket transport. Arbitrary libpq
URIs, environment service files and connection-string expansion are not accepted.
The file must be a regular private file, not a public configuration snippet.
The first configured start imports the existing directory with IDs and credentials preserved and records a destination marker. PostgreSQL then becomes authoritative. Removing its configuration, changing its destination or losing its tenant row fails startup instead of falling back to the old JSON. Do not delete the marker to bypass that protection. Back up both the database and cloud data directory.
Internally, one row in public.quinzee_directory holds a bounded JSONB snapshot
per tenant. One PostgreSQL session owns an advisory writer lock. A second writer
fails startup. Every committed mutation publishes a consistent new snapshot.
Database connection loss denies directory access; recover PostgreSQL and restart
Quinzee to reacquire ownership. There is no automatic reconnect using stale
permission data, and direct SQL edits are unsupported.
Step 3: enable the LDAP frontend
Build the optional server with make directory-deps and note the reported
OpenLDAP installation prefix. Create a private socket parent:
install -d -m 700 .local/directory-run
Start the native cloud with its normal TLS/data settings plus
--directory-postgres-config <private-postgres.json> and
--ldap-socket <absolute-path>/.local/directory-run/directory.sock. Ensure
windows_ldap is loaded. In another terminal, as the same OS user:
python3 infrastructure/directory/ldap.py \
--prefix /absolute/path/to/installed-openldap \
--socket "$PWD/.local/directory-run/directory.sock" \
--certificate "$PWD/.local/certificates/quinzee.cloud/server.crt" \
--key "$PWD/.local/certificates/quinzee.cloud/server.key" \
--ca "$PWD/.local/certificates/ca/quinzee-dev-root-ca.crt" \
--runtime "$PWD/.local/ldap-runtime" \
--address 127.0.0.1 --port 11636
All six path options shown are required except address/port, whose defaults are 127.0.0.1/11636. OpenLDAP terminates TLS and forwards bind/search/compare to the private mode-0600 socket. Run it with the cloud's UID. The socket parent must remain 0700. The cloud refuses to replace an existing socket; after an unclean exit, verify there is no live owner before removing a stale socket. Ctrl+C stops the LDAP frontend without deleting directory records.
Step 4: administer users and groups
In Azure / Entra ID → Users, create a username such as alice@example.test,
display name and 12–1,024-byte password. Account enabled controls sign-in. Select
a user and use Save selected to rename, disable or reset its password. Forced
change at next sign-in is not implemented. Password hashes and salts stay in
the shared authority. Disabling affects LDAP and OAuth authentication.
In Groups, create a security group with a stable account name, select it, and
use Members to add users or groups. Cycles are rejected. IDs remain stable;
display names can change. POSIX numeric IDs start at 200000, are monotonically
allocated and are not reused. Metadata such as /home/<username> does not
create home directories or local OS accounts on the server.
The POSIX LDAP view uses ou=users and ou=groups below
dc=quinzee,dc=cloud. It exposes direct user memberships in memberUid.
The Windows-oriented view is below ou=windows,dc=quinzee,dc=cloud, with user
and group subtrees. It exposes direct member/memberOf, nested group DNs,
binary Microsoft-order objectGUID, userPrincipalName, stable generated
sAMAccountName, and enabled/disabled userAccountControl. It has no SIDs,
security descriptors, KDC, Kerberos, domain join or AD replication.
Verify using the real LDAP client, supplying the password interactively:
LDAPTLS_CACERT="$PWD/.local/certificates/ca/quinzee-dev-root-ca.crt" \
ldapsearch -LLL -x -H ldaps://127.0.0.1:11636 \
-D 'uid=alice@example.test,ou=users,dc=quinzee,dc=cloud' -W \
-b 'dc=quinzee,dc=cloud' '(objectClass=posixAccount)'
Use a certificate containing the selected IP SAN or a matching DNS hostname. OpenLDAP's localhost handling can resolve to the machine hostname; do not work around a mismatch by disabling verification. Anonymous enumeration and LDAP writes are refused. Provision SSSD/PAM/NSS on Linux clients separately; Quinzee never changes the host's primary login configuration.
Step 5: manage application and resource permissions
Create App registrations, then create their Enterprise applications (service principals). Keep client ID, registration object ID and principal ID distinct. Credentials → Add secret returns the secret once; remove its key ID to revoke it. At most four client secrets are retained. Public clients use exact registered redirect URIs and no client secret. The local application enabled property is an emulator policy, not a claim that every Graph property is implemented.
Define App roles on the registration, then assign them to users, groups or
service principals through App role assignments. A group app-role grant applies
to direct user members only. Define User or Application allowed member types
appropriately. Disable a role, remove its assignments, then delete the definition.
Assignment required blocks unassigned access to that Enterprise application.
Expose an API at api://<client-id>; tokens for its .default scope carry its
role values and client-ID audience. Existing external API tokens can remain
usable until expiry; applications must validate their own required roles.
Azure / Resource access → Role assignments uses subscription/group/resource scopes. Supported roles are Owner, Contributor, Reader and Service Bus Data Owner/Sender/Receiver. Group-based resource RBAC includes nested user membership. User-assigned identities are separate ARM resources and survive app deletion; system identities are owned by their app. Managed identities cannot password-bind to LDAP. Attach them to supported hosted workloads to obtain tokens.
Directory management remains bootstrap-admin-only. ARM Owner and application roles do not grant that privilege. MFA, federation, Conditional Access, delegated consent and full Graph/directory emulation are outside this implementation.