-
Notifications
You must be signed in to change notification settings - Fork 43
docs: add OEP - Multi tenant mobile support #734
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Draft
RawanMatar89
wants to merge
2
commits into
openedx:master
Choose a base branch
from
RawanMatar89:oep-multitenant-mobile
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Draft
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
201 changes: 201 additions & 0 deletions
201
oeps/architectural-decisions/oep-0068-multi-tenant-mobile-support.rst
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,201 @@ | ||
| OEP-68: Multi-Tenant Support in Open edX Mobile Apps | ||
| #################################################### | ||
|
|
||
| .. list-table:: | ||
| :widths: 25 75 | ||
|
|
||
| * - OEP | ||
| - :ref:`OEP-68 Multi-Tenant Mobile Support` | ||
| * - Title | ||
| - Multi-Tenant Support in Open edX Mobile Apps | ||
| * - Last Modified | ||
| - 2025-03-18 | ||
| * - Authors | ||
| - | ||
| * Rawan Matar <[email protected]> | ||
| * Ivan Stepanok <[email protected]> | ||
|
|
||
| * - Arbiter | ||
| - TBD | ||
| * - Status | ||
| - Draft | ||
| * - Type | ||
| - Architecture Decision | ||
| * - Created | ||
| - 2025-03-18 | ||
| * - Review Period | ||
| - TBD | ||
| * - References | ||
| - | ||
| * `Multi-tenant PR <https://github.com/zeit-labs/openedx-app-ios-contrib/pull/10>`_ | ||
|
|
||
| .. contents:: | ||
| :local: | ||
| :depth: 1 | ||
|
|
||
| Abstract | ||
| ******** | ||
| This OEP proposes adding **multi-tenant support** to the Open edX mobile applications. | ||
| Currently, the apps support only a single institution per build. | ||
| This proposal introduces a mechanism for users to select their institution (tenant) at runtime, | ||
| with each tenant providing its own branding, configuration, and API endpoints. | ||
| This reduces duplication and enables a white-labeling approach | ||
| within a single mobile app module. | ||
|
|
||
| Motivation | ||
| ********** | ||
| The Open edX mobile app is increasingly used by multiple institutions. | ||
| Releasing separate app builds for each tenant creates duplication, higher maintenance burden, | ||
| and inconsistent user experience. Multi-tenancy enables: | ||
|
|
||
| * A single app build for multiple institutions. | ||
| * Dynamic branding (logo, color scheme, names). | ||
| * Institution-specific API and authentication endpoints. | ||
| * Future extensibility to fetch tenant definitions dynamically. | ||
|
|
||
| Current State | ||
| ============= | ||
| - Mobile apps support only one tenant per build (YAML-based config). | ||
| - Persistence layer uses a single Core Data/SQLite DB, risking data leakage across tenants. | ||
| - Push notification manager doesn’t account for tenant context. | ||
| - Branding and login flows are static per build. | ||
|
|
||
| Decision | ||
| ******** | ||
| We propose supporting **multi-tenancy** in one app build by: | ||
|
|
||
| * Providing a tenant selector screen at login. | ||
| * Defining tenant metadata (branding, API URLs, auth URLs, etc.) in a JSON configuration file. | ||
| * Allowing runtime tenant switching without reinstallation. | ||
| * Maintaining isolated databases per tenant. | ||
| * Enhancing push notifications with tenant context. | ||
|
|
||
| Specification | ||
| ************* | ||
|
|
||
| Tenant Selection | ||
| ================ | ||
| - On launch, show a tenant selector if multiple tenants are configured. | ||
| - If only one tenant exists, preserve the current flow. | ||
|
|
||
| Tenant Configuration | ||
| ==================== | ||
| Tenant metadata will be stored in a JSON config file, including: | ||
|
|
||
| * ``name`` (tenant_id) | ||
| * ``display_name`` | ||
| * ``logo_url`` | ||
| * ``primary_color`` | ||
| * ``api_base_url`` | ||
| * ``auth_url`` | ||
|
|
||
| Example:: | ||
|
|
||
| { | ||
| "tenants": [ | ||
| { | ||
| "name": "tenant_a", | ||
| "display_name": "University A", | ||
| "logo_url": "https://example.com/logo.png", | ||
| "primary_color": "#FF5733", | ||
| "api_base_url": "https://tenant_a.example.com/api", | ||
| "auth_url": "https://tenant_a.example.com/auth" | ||
| } | ||
| ] | ||
| } | ||
|
|
||
| Database Management | ||
| =================== | ||
| - Each tenant has its own Core Data/SQLite store. | ||
| - Database name pattern: ``opendx_{tenant_id}_db``. | ||
| - A `DatabaseManagerProvider` maintains tenant-specific DB managers. | ||
| - Switching tenants reloads the persistence stack. | ||
|
|
||
| Push Notifications | ||
| ================== | ||
| - One device token is maintained. | ||
| - Token registered with all tenants. | ||
| - Payloads include ``tenant_id``. | ||
| - Notifications routed to the correct tenant listener. | ||
|
|
||
|
|
||
| Tradeoffs | ||
| ========= | ||
| We considered three approaches: | ||
|
|
||
| **1. Single App + Bundled Config (proposed)** | ||
|
|
||
| - **Pros**: | ||
| - Single codebase and release process, reducing duplication. | ||
| - Works offline immediately since tenant definitions are bundled. | ||
| - Reliable theming and branding without network dependency. | ||
| - **Cons**: | ||
| - Updating tenant metadata requires an app update (until remote fetch is added). | ||
| - Larger app size if many assets are included. | ||
| - **Implications**: | ||
| - **Push notifications**: One device token registered with all tenants, routed by ``tenant_id``. | ||
| - **Theming**: Strong, since assets/colors are local. | ||
| - **Offline**: Strong support — tenants always available. | ||
|
|
||
| **2. Remote Configuration** | ||
|
|
||
| - **Pros**: | ||
| - Tenant metadata can change without an app update. | ||
| - Centralized management of tenant definitions. | ||
| - **Cons**: | ||
| - Requires robust caching and fallbacks to work offline. | ||
| - Higher runtime complexity and security considerations. | ||
| - **Implications**: | ||
| - **Push notifications**: Requires re-registration if tenant config changes. | ||
| - **Theming**: More flexible, but must be cached to avoid broken UI offline. | ||
| - **Offline**: Dependent on last successful fetch. | ||
|
|
||
| **3. Separate Builds (current state)** | ||
|
|
||
| - **Pros**: | ||
| - Full isolation per tenant (bundle IDs, push notifications, store presence). | ||
| - Simple runtime logic. | ||
| - **Cons**: | ||
| - High maintenance and CI/CD overhead. | ||
| - Risk of divergence across builds. | ||
| - **Implications**: | ||
| - **Push notifications**: Simplest — separate certs per build. | ||
| - **Theming**: Static and guaranteed. | ||
| - **Offline**: Guaranteed, but at the cost of scalability. | ||
|
|
||
| Impact on Single-Tenant Deployments | ||
| =================================== | ||
| For single-tenant deployments, this proposal introduces minimal change: | ||
|
|
||
| - If only one tenant is defined in the configuration, the tenant selector is skipped and the app behaves exactly as today. | ||
| - Branding, theming, and login flows remain static to that single tenant. | ||
| - No additional runtime overhead is introduced for single-tenant cases. | ||
|
|
||
| Alternatives | ||
| ************ | ||
| - Separate app per tenant (high maintenance). | ||
| - Remote configuration (scalable but adds backend dependency). | ||
| - Custom login screen only (limited branding flexibility). | ||
|
|
||
| Impact | ||
| ****** | ||
| - **Users**: Access multiple institutions in one app. | ||
| - **Institutions**: Branded experiences without custom builds. | ||
| - **Developers**: Reduced duplication and simpler long-term maintenance. | ||
| - **Backend**: No changes required, except for including ``tenant_id`` in notification payloads. | ||
|
|
||
| Future Work | ||
| *********** | ||
| - Fetch tenant metadata dynamically from an API. | ||
| - Allow tenant switching post-login via settings/profile. | ||
| - Adopt design tokens for consistent theming across platforms. | ||
|
|
||
| Change History | ||
| ************** | ||
| 2025-03-18 | ||
| ========== | ||
| * Initial draft created based on ADR. | ||
|
|
||
| 2025-09-23 | ||
| ========== | ||
| * Added Tradeoffs and Single-Tenant Impact sections. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do we have a sense of how complex this is? Dynamic addition of tenants feels like the feature that really unlocks the value of a centralized app. It would potentially introduce some bigger questions like "do we need a registry of academies?" However, the technical piece doesn't feel too complicated.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@e0d it's probably less complex than it looks like.
I would suggest that we don't have a centralized registry.
I recommend considering the following login flow for the centralized app:
Enter the URL:
Email:
Password:
This is Moodle app workflow and I think it's a good one.
Having a directory in Firebase or any other REST API backend is nice to show an auto-complete on the URL field, but the app should be generic for everyone to include installations of institutions who many not know how to apply i.e. someone who barely speaks English and just wants to try the app on their institute.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does the Moodle flow authenticate on the part of the learner? If that's how it works, I would recommend a different approach using OAuth. One would get the URL of the backend, maybe via a QR for ease, and then be directed via the OAuth flow to authorize the mobile app to access the appropriate scopes.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I also like the idea of using a QR code for setup. QR codes can include a protocol specifier for mobile apps that can allow the appropriate app to launch, fetch the configuration from the remote system, and add it to the phone. This one-time setup can be cached and I don't think it's asking too much for initial setup to have an internet connection.
The proposal as given allows a single operator to allow multiple tenants that they manage to go together in one app. However, I think having a single app that any instance with a relatively recent version can use is more useful. The one difficulty here is possible issues with API versioning that we'd need to be more careful about (some instances may update at different rates-- we'd need to decide how big of a window the app would support in terms of instance versions), but as long as we're deliberate about that, it should be doable.
If we require each provider to make their own copy of the app it's redundant work. It might increase adoption somewhat because apps would be per provider setting up their apps rather than doing it per client. But then you'd have to name them-- the OpenCraft Open edX Mobile app, the Edly Open edX Mobile App-- really that would be the only thread linking the various institutions that use a particular provider. There would also be multitenant instances, but from that perspective, it's still maintaining one app per organization that runs one of these multitenant instances.
No, the real value comes from having a central app any instance can use. Requiring pre-baked configurations means maintaining a central registry, which is going to mean setting one up and administrating it. Requiring a remote tenant listing ALSO requires making this registry, but just changes how we push it through.
It's better if there's no registry at all-- perhaps the app opens and lets you either manually input an LMS domain name, or alternatively scan a QR code you can get from your account page.
The data which has to be accessed and cached for tenant setup on the phone is minimal and is not expected to change much. How often do universities change their logos and colors? Perhaps occasionally, but even if your phone's colors and icon are out of date, it's not a usability issue, and it can be corrected whenever you get a better connection. Not a big deal.
Single-tenant builds of the app can just skip half of the work by asking the user to log in immediately, since they already know what endpoint is needed. But if we want to increase adoption, the instance operators shouldn't have to do anything special to take advantage of the mobile app. No custom builds, no submitting to the app store. Just using the prebuilt thing which already exists.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@Kelketek I agree 100% with what you've said. The less work we require, the more adoption we'll have.
QR code feature is a brilliant one.
And yes, I oppose the idea of having each provider maintains their own generic multi-tenant apps. A non-generic multi-tenant apps makes sense in very narrow cases. But the default case should be "just use the generic app" for 90% of the learners.