Integrating existing systems
How apps with their own accounts, sign-in, and permissions turn an OpenMax identity into a usable signed-in user in their own system: the full chain, a pre-integration checklist, the integration policy table, and the first-visit handling order.
Integrating existing systems
This page is for systems that already have a user table, a sign-in page, and a permission model (such as Leantime and various self-hosted tools). Sign-in gets you a trusted OpenMax identity (org_id, member_id) and stops there; this page covers how that identity becomes a usable signed-in user in your system.
How the two relate:
- Relation to sign-in: the session rules in Sign-in (single-use flows, sessions no longer than token expiry, re-authorize on expiry) also apply to your system's native session. You sign the user in with your own session mechanism, but its lifetime follows the OpenMax authorization.
- Relation to SSO in "Out of scope": the platform does not provide unified single sign-on / single sign-out (no sign-in state sync, no sign-out notification, no account creation on your behalf, no integration with your system's own IdP). An app using OpenMax authorization to map an OpenMax identity to a local account is the app's own implementation; it is allowed and recommended, and does not conflict with that item.
Full chain
| # | Step | Owner | Done when | Common pitfalls |
|---|---|---|---|---|
| 1 | OpenMax identity | Shell + authorization page | The member is signed in to Workspace, the installation is active, entry roles are visible; the shell opens {url}{sub-path} |
Assuming the shell passes identity parameters (it does not; see "Parameters on the entry URL" in Open modes and URLs) |
| 2 | App authorization | App (Sign-in) | The callback checked iss / state, tokens exchanged, id_token verified, org_id in the allowed range |
Wrong cookie attributes in the iframe, so the callback cannot find the flow; redirect sign-in inside the iframe when embedded on iPhone / Safari (always breaks; use Sign-in ("Sign-in when embedded")) |
| 3 | App account | App | Binding found by (issuer, org_id, member_id), or created / rejected per policy (see "Integration policy table" below) |
Automatically merging into an existing account by email (account takeover risk) |
| 4 | Native sign-in state | App | This account is signed in with your system's own session mechanism; session lifetime ≤ token expiry (see "Session lifetime" in Sign-in) | Native sessions default to several days or even "remember me", outliving the authorization |
| 5 | First-visit behavior | App | The new user gets a default role, joins the agreed project / workspace, and lands on a page that is guaranteed to open | An onboarding wizard auto-creates projects; the landing page is a project the user cannot access |
| 6 | Business pages usable | App | Core pages open, data is visible, actions do not return 403 | The account exists but belongs to no project, so everything is 403 / blank |
Account created ≠ user can use it. Success at step 3 only means "this person exists"; integration is complete only when steps 5 and 6 also hold. The shell's "Integration details" only confirms its own two steps (validation, opening the URL); it cannot see the app-side steps and will never mark them complete. Verify it yourself with the cases in "Real first-use acceptance" in the launch checklist.
Pre-integration checklist
- ☐ You can configure the external URL / base path (when mounted under a prefix like
/leantime, generated links, redirects, static assets, and cookiePathall include the prefix; see "URL composition examples" in Open modes and URLs) - ☐ You can add a sign-in entry without changing core code (plugin / middleware / auth extension point), for
/auth/openmax/loginand the callback in Sign-in - ☐ The user table can store the external binding
(issuer, org_id, member_id)(a separate binding table is better), with a unique constraint - ☐ You can programmatically "sign in as an account" (create a native session) and set the session lifetime to no longer than token expiry
- ☐ For embed: you can change
X-Frame-Options/ CSPframe-ancestors; session cookies can be set toSameSite=None; Secure; Partitioned - ☐ Routing tolerates
theme/openmax_langon the entry URL, and trailing-slash handling is known - ☐ How to handle the native sign-in entry: keep password sign-in (admin fallback) or hide it; turn off self sign-up to avoid creating accounts that bypass OpenMax
- ☐ The permission model is understood: which roles exist, how project / workspace membership is granted, and what pages look like when a new user belongs to no project
- ☐ What first sign-in triggers: onboarding wizards, auto-created sample projects, welcome emails. List them and decide whether to turn them off or keep them
- ☐ In-app "Sign out" can redirect to a URL with
?signed_out=1(no automatic re-authorization; see "Error handling" in Sign-in) - ☐ Whether one deployment serves one organization or several: decide the
org_idallow rule (see the organization check in "Callback handling" in Sign-in) - ☐ The integration policy table below is filled in and confirmed by an organization admin
Integration policy table (required, decide before integrating)
Every item needs a clear answer, written into your configuration / docs. "Launch with defaults and sort it out later" is not allowed.
| Decision | Options | Recommendation |
|---|---|---|
| Account provisioning | A. Auto-create on first visit B. Admin pre-binds manually ( (org_id, member_id) → local account set up in advance; unbound people who come in only see "Please contact an admin to get access") |
Everyone should use it and there is no per-seat billing → A; seats / licenses / sensitive data → B |
| Linking existing local accounts | Admin pre-binds; or the user first signs in with their existing account, then manually confirms the link once | Do not auto-link existing accounts by email alone (the same email does not mean the same person, nor that this person may take over that account). Use email only for display and admin verification |
| Default role | System role for new accounts | The lowest "usable" role (such as regular member / editor), not admin. org_role is for reference only (see "Token endpoint and tokens" in Sign-in); if you really need to map OpenMax owner / admin to app admin, write down the rule and how it is revoked |
| Which project / workspace to land in | Specify a default project; or join no project and land on a guide page | Specify a clear default project (such as "OpenMax team"). Do not open / join all historical projects by default: historical projects may contain data new members should not see |
| Auto-join or not | Auto-join the default project; or only create the account and let project admins invite | When auto-joining, state which projects and roles; when not, the first-visit page must tell users "who to ask for access" |
| How to revoke | Remove from project / disable account in the app; on the OpenMax side, the member leaves or the installation is disabled / uninstalled | Both sides need a path: removal in the app should not be undone by the next auto-join (auto-join happens only once, at first creation); after revocation on the OpenMax side, the next authorization fails (access_denied) or the token gets 401, and the app ends the session and shows no-permission; the local account is disabled, not deleted |
| First landing page | Personal dashboard / welcome page / default project home | Pick a page that is guaranteed to open for the default role; the first visit does not trigger "create project" style wizards |
First-visit handling order
- The authorization callback gets the identity and checks the organization (see "Callback handling" in Sign-in) → look up the binding.
- Bound: if the account is disabled → show a no-permission page, do not retry; otherwise sign in.
- Not bound: policy B → show "Please contact an admin to get access" (include member_id so the admin can bind it), do not create an account; policy A → in one transaction create account + binding + default role + (if agreed) default project membership, using a unique constraint so two tabs visiting for the first time at once do not create two accounts.
- Create the native session (lifetime ≤ token expiry) and redirect to returnTo. If returnTo is
/or a page the user cannot access, go to the agreed first landing page instead.
