openDesk SSO and identity federation

The Nubus Directory Importer is the route the openDesk documentation recommends for provisioning users from LDAP or Active Directory, and it runs one way only, from the directory into openDesk. Changes made in openDesk accounts do not flow back to AD or LDAP, so the directory remains the system of record for identities. Before you configure anything, decide which OUs and groups are in scope. A search base that is too broad pulls in service accounts, shared mailboxes and retired staff, while one that is too narrow leaves out people who need access. Write the scope down as a list of base DNs and group filters, and have your directory team sign off on it before the first run.

Attribute mapping is the second decision. Each directory attribute must map to a field on the openDesk account, and the matching attribute determines whether a directory user lines up with an existing openDesk account. The federation documentation gives mailPrimaryAddress as one example of a matching attribute, so check which attribute your organization keeps accurate and unique. Agree the mapping with the team that owns the directory and the team that owns openDesk, and record which source attribute is authoritative for name, email address and group membership. Ask ZenDiS or your implementation partner for the supported attribute list for your release, because the list can change between versions.

Lifecycle handling is the third decision, and it is the one that most often surprises operations teams. You need a documented answer for users who are disabled in AD or LDAP, users removed from an in-scope group, and users who leave the organization entirely. Confirm in the current documentation for your release whether disabled accounts are deactivated or deleted, how often the import runs, and what happens to content owned by a removed user. These behaviors decide whether a departure appears in openDesk on the same day or later, and they set the data retention procedure you need to write. Do not rely on assumptions about defaults. Test each case in a lab and record the result.

The importer authenticates to the directory with a bind account, so the bind account needs a named owner. Ask the directory team to create a dedicated account with read-only rights limited to the in-scope OUs, and to assign ownership of its password to one role in the directory team. Set a rotation schedule and a documented procedure for updating the secret in the openDesk deployment configuration. A missed rotation or an expired password can cause sync failures that are easy to overlook, so alert on failed imports. Microsoft Entra ID does not expose LDAP, so tenants on Entra ID need Azure AD Domain Services before this route applies.

Run the importer first in a non-production environment that uses a copy of the in-scope directory structure, and do not point a first test at production users. Compare user counts for each in-scope group against the directory, then sample accounts across roles, including one disabled user and one user moved out of scope. Check that attributes such as name, email address and group membership match the agreed mapping. Repeat the run until counts and sampled attributes agree, and keep the reconciliation output as evidence for the rollout and for later audits.

The first weeks after federation goes live show whether the identity layer behaves as designed, so monitoring should start on day one and cover both sides of the trust. Watch login failures in the Keycloak-based openDesk IdP, paying attention to clusters of errors tied to one external identity provider, which often point to an expired certificate, a changed redirect URI or client configuration drift. Track federation errors on the external provider's side as well, because some failures never reach openDesk logs. Agree who receives these alerts, which log sources feed them and who acts first when federated sign-in fails for many users at once. Confirm with your platform team which log collection stack already runs in the cluster and how long it retains identity events for your incident process.

The Nubus Directory Importer is one-way, so every change it applies originates in your directory, which makes its runs worth reviewing. After each scheduled run, check for failed records and for unexpected changes, such as large numbers of accounts disabled, renamed or added to groups they should not hold. Compare account counts with the directory before and after a run during the pilot so you know what normal looks like. Treat the bind account that reads the directory as a privileged credential: it should have read access only to the search base the importer needs, and its password should follow a rotation schedule your directory team owns. Rotate the client secret used by the federation on the same governance cycle. Confirm the exact rotation steps and any expected downtime against the documentation for your release before you schedule them.

Back up the Keycloak realm configuration, including identity provider definitions, client settings, attribute mappers and group configuration, and store it with the Helm values and secrets that deployed it. A realm export without the matching chart values is hard to use for a clean rebuild, and values without the export leave the federation settings to be recreated by hand. Keep both under the same change control, store copies outside the cluster and test a restore in a non-production namespace before you rely on it. Ask your implementation partner or the deployment documentation which realm artifacts are covered by the backup, how secrets are handled and whether the backup includes the database holding local accounts and sessions. Set the backup frequency from your operations policy, and record it in the runbook.

openDesk plans minor releases monthly and supports only the latest minor version, so federation is not a one-time configuration. A minor upgrade can change the Keycloak-based IdP, the chart or the Nubus components that carry your federation settings. Plan a re-test of federation after every minor upgrade and before the change reaches production users. The checklist should cover signing in through the external identity provider, confirming that the matching attribute, such as username or mailPrimaryAddress, still links to the right account, checking group membership on a pilot account and running one Directory Importer cycle against a test directory. If your environment falls several minor versions behind, the release documentation may require intermediate steps, so confirm that upgrade path before you start.

The final item is documentation that another engineer can act on during an incident. Keep the attribute mapping that links directory fields to openDesk user attributes, the matching rule that decides whether a federated login maps to an existing account and the group mapping that grants roles and workspace access. Add the offboarding procedure, which should state how a leaver's directory account is disabled, how the importer reflects that change, how active sessions and external sign-ins are ended and who confirms that access to files and chat has been removed. Version these documents alongside the Helm values and the re-test checklist, review them after each minor upgrade and ask your partner to list them as handover deliverables in the written scope.

Test the federation before any pilot user depends on it, and design each test so that a failure leaves the organization able to log in and recover. The core plan has two parts: confirm that the external identity provider (IdP) and the Keycloak-based openDesk IdP agree on who each user is and what they may do, and confirm that a broken federation does not lock out the people who must repair it. Run these checks in a non-production environment first, then repeat the critical ones in the pilot environment with real pilot accounts. Record the expected result for every test in writing before you run it, so the outcome is not argued after the fact.

Start with login and identity matching. Choose pilot users from each directory group that will receive a different role, and have each one sign in through the external IdP over OIDC. For every test user, confirm that the attribute chosen for matching (the username or another attribute such as mailPrimaryAddress) resolves to exactly one openDesk account. Duplicate or zero matches are the most common federation fault, and they are easy to miss when only one administrator account is tested. Next, check that group membership in the directory produces the expected roles inside openDesk, and that a user outside the pilot groups receives no more access than intended. Ask your IdP administrator to confirm which claims and attributes are sent, because the test is only as good as the attribute mapping it exercises.

Then test the lifecycle. Disable a pilot account in the directory and confirm that the user can no longer sign in through the federated path. If users are provisioned from Active Directory or LDAP with the Nubus Directory Importer, check that the import reflects the disablement and that the openDesk account is handled as your policy requires. Test logout from openDesk and from the external IdP, and observe what happens to a session that is still open after a logout or after a change in the directory. Measure session expiry against the values your security owner has approved, not against defaults you assume. Do not treat any timeout as a fact until you have read it from your own configuration. If you cannot confirm a value, put that question to the vendor and to your own team as an open item.

The fail-safe checks decide whether the rollout is acceptable. Deliberately take the external IdP offline in the test environment and record which users and which administrators can still reach openDesk. Confirm that at least one named administrator can sign in through a recovery path that does not depend on the external IdP, and rehearse that path before pilot launch, not during an incident. Also record what happens to sessions that exist at the moment of the outage: whether they continue, end, or require re-authentication. For the import, induce a failed or partial directory import and confirm that your monitoring or log review detects it, that the operator can identify the affected accounts, and that the rollback procedure restores the previous state. A rollback you have not rehearsed is not a rollback.

Document the results as evidence for the rollout decision and for any compliance assessment. Each test should have an owner, the expected result, the observed result, and a sign-off by the business and security owners. Failures should block pilot access for the affected group until they are fixed and retested. If you engage a partner, ask for the test plan, the test accounts used, the recovery procedure and the rollback steps as written deliverables, and confirm in the scope which environment the tests run in and who holds the administrator credentials at the end of the engagement.