Enterprise directory authentication

Orbis Studio can authenticate users through Microsoft Active Directory, OpenLDAP, or a compatible LDAP server. Directory credentials are verified by an LDAP bind and are never stored as local credentials.

Choose an authentication profile

• Keycloak federation is recommended when Studio and OrbisBox must share the same SSO session. Configure LDAP/AD User Federation in Keycloak and let both applications consume OIDC tokens.
• Direct LDAP is intended for standalone or on-premises Studio installations. Studio performs the LDAP bind and maintains a linked local application account for RBAC, ownership, and preferences.

Enabling direct LDAP does not modify Keycloak. A password accepted by LDAP is never copied to Keycloak.

Direct LDAP configuration

All settings use the ORBISAGENTS_ environment variable prefix. Inject bind passwords from your deployment secret store instead of committing them to an environment file.

OpenLDAP example

_16

ORBISAGENTS_AUTO_LOGIN=false

_16

ORBISAGENTS_AD_ENABLED=true

_16

ORBISAGENTS_AD_PROVIDER_ID=corporate-directory

_16

ORBISAGENTS_AD_PROVIDER_TYPE=openldap

_16

ORBISAGENTS_AD_AUTH_MODE=direct_ldap

_16

ORBISAGENTS_AD_SERVER_URI=ldaps://ldap.example.internal:636

_16

ORBISAGENTS_AD_VERIFY_SSL=true

_16

ORBISAGENTS_AD_CA_CERT_PATH=/run/secrets/corporate-directory-ca.pem

_16

ORBISAGENTS_AD_SEARCH_BASE=ou=people,dc=example,dc=internal

_16

ORBISAGENTS_AD_USER_FILTER=(uid={username})

_16

ORBISAGENTS_AD_USERNAME_ATTRIBUTE=uid

_16

ORBISAGENTS_AD_EMAIL_ATTRIBUTE=mail

_16

ORBISAGENTS_AD_STABLE_ID_ATTRIBUTE=entryUUID

_16

ORBISAGENTS_AD_BIND_DN=cn=studio-reader,ou=service-accounts,dc=example,dc=internal

_16

ORBISAGENTS_AD_BIND_PASSWORD=<injected-secret>

_16

ORBISAGENTS_AD_AUTO_CREATE_MISSING_USER=true

Active Directory example

_16

ORBISAGENTS_AUTO_LOGIN=false

_16

ORBISAGENTS_AD_ENABLED=true

_16

ORBISAGENTS_AD_PROVIDER_ID=corporate-ad

_16

ORBISAGENTS_AD_PROVIDER_TYPE=active_directory

_16

ORBISAGENTS_AD_AUTH_MODE=direct_ldap

_16

ORBISAGENTS_AD_SERVER_URIS=ldaps://dc-01.example.internal:636,ldaps://dc-02.example.internal:636

_16

ORBISAGENTS_AD_VERIFY_SSL=true

_16

ORBISAGENTS_AD_CA_CERT_PATH=/run/secrets/corporate-ad-ca.pem

_16

ORBISAGENTS_AD_SEARCH_BASE=dc=example,dc=internal

_16

ORBISAGENTS_AD_USER_FILTER=(sAMAccountName={username})

_16

ORBISAGENTS_AD_USERNAME_ATTRIBUTE=sAMAccountName

_16

ORBISAGENTS_AD_EMAIL_ATTRIBUTE=mail

_16

ORBISAGENTS_AD_STABLE_ID_ATTRIBUTE=objectGUID

_16

ORBISAGENTS_AD_BIND_DN=CN=Studio Reader,OU=Service Accounts,DC=example,DC=internal

_16

ORBISAGENTS_AD_BIND_PASSWORD=<injected-secret>

_16

ORBISAGENTS_AD_AUTO_CREATE_MISSING_USER=true

Use ORBISAGENTS_AD_START_TLS=true with an ldap:// URI when the directory requires StartTLS. Do not combine StartTLS with an ldaps:// URI.

Local-account policy

ORBISAGENTS_AD_AUTH_MODE controls local fallback:

• direct_ldap permits directory users and the explicitly configured local break-glass superuser.
• local_and_direct_ldap also permits existing local users that are not linked to the directory.

local_and_direct_ldap requires a read-only service bind account. Without a service search, an LDAP bind cannot safely distinguish an unknown local-only username from a known directory user with a wrong password.

A directory-linked user never falls back to its local placeholder password after invalid credentials or a directory outage.

Keep ORBISAGENTS_AD_LINK_EXISTING_USER=false unless existing local accounts have been reviewed for safe linking. Username or email collisions are rejected instead of silently merging identities.

Tenant and group mapping

Set ORBISAGENTS_AD_TENANT_ID to an existing tenant UUID. Directory users receive member by default:

_10

ORBISAGENTS_AD_TENANT_ID=00000000-0000-0000-0000-000000000000

_10

ORBISAGENTS_AD_TENANT_ROLE=member

Group mappings accept only member and guest; directory configuration cannot grant tenant administrator or platform superuser:

_10

ORBISAGENTS_AD_GROUP_ROLE_MAPPINGS={"CN=Studio Members,OU=Groups,DC=example,DC=internal":"member","CN=Studio Guests,OU=Groups,DC=example,DC=internal":"guest"}

_10

ORBISAGENTS_AD_UNMATCHED_GROUP_POLICY=deny

For a single admission group, use ORBISAGENTS_AD_REQUIRE_GROUP_DN.

Account status

Active Directory's userAccountControl disabled bit is enforced automatically. Generic LDAP and OpenLDAP deployments can configure an account status attribute:

_10

ORBISAGENTS_AD_DISABLED_ATTRIBUTE=accountStatus

_10

ORBISAGENTS_AD_DISABLED_VALUES=true,1,disabled,locked

An unavailable or unreadable directory is not treated as proof that a user was removed.

Reconciliation

Background reconciliation is optional and starts in dry-run mode:

_10

ORBISAGENTS_AD_SYNC_ENABLED=true

_10

ORBISAGENTS_AD_SYNC_INTERVAL_HOURS=24

_10

ORBISAGENTS_AD_SYNC_GRACE_HOURS=24

_10

ORBISAGENTS_AD_SYNC_DRY_RUN=true

Reconciliation checks only users linked to the configured provider. Any bind, TLS, timeout, paging, or schema failure aborts the run without deactivating users. Review dry-run results before setting ORBISAGENTS_AD_SYNC_DRY_RUN=false.

Validate connectivity

A platform superuser can call:

_10

POST /api/v1/directory/test-connection

_10

Content-Type: application/json

_10

_10

{"username": "optional-user-to-search"}

The response reports sanitized network, TLS, service-bind, and search stages. It never returns the bind secret, DN, user attributes, or LDAP exception text.

Production requirements

• Verify LDAPS or StartTLS certificates and mount the corporate CA bundle.
• Use a read-only directory service account scoped to the required search base and attributes.
• Set connection and receive timeouts appropriate for the network.
• Keep the local break-glass account in a secret manager and audit its use.
• Do not log credentials, email addresses, DNs, or raw directory errors.
• Use a stable identity attribute such as AD objectGUID or OpenLDAP entryUUID; usernames and email addresses can change.