docs: add OEP - Multi tenant mobile support

[RawanMatar89]

This PR proposes OEP-68: Multi-Tenant Support in Open edX Mobile Apps.

The OEP 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, enables a white-labeling model, and lowers long-term maintenance costs compared to maintaining separate app builds.

Key highlights:
• Tenant selector at login if multiple tenants exist.
• Tenant metadata stored in a JSON config (branding, URLs, auth).
• Separate database per tenant for isolation.
• Push notification manager updated to handle tenant context.
• Backwards compatible: single-tenant configs behave like current app.

Future enhancements may include fetching tenants dynamically from an API and supporting runtime tenant switching.

[openedx-webhooks]

Thanks for the pull request, @RawanMatar89!

This repository is currently maintained by @sarina.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

• If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
  • This process (including the steps you'll need to take) is documented here.
• If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

• Dependencies

  This PR must be merged before / after / at the same time as ...

• Blockers

  This PR is waiting for OEP-1234 to be accepted.

• Timeline information

  This PR must be merged by XX date because ...

• Partner information

  This is for a course on edx.org.

• Supporting documentation
• Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

🔘 Update the status of your PR

Your PR is currently marked as a draft. After completing the steps above, update its status by clicking "Ready for Review", or removing "WIP" from the title, as appropriate.

---

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

• The size and impact of the changes that it introduces
• The need for product review
• Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

[OmarIthawi]

@RawanMatar89 Thanks for opening this OEP draft.

@volodymyr-chekyrta @IvanStepanok @edschema I would love your support to help Rawan get this OEP moving forward.

We have a lot of work that's out of my expertise in mobile. I will be contributing to the work in regards to its server-related and SAML related issues.

[e0d]

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.

[OmarIthawi]

Do we have a sense of how complex this is?

@e0d it's probably less complex than it looks like.

t would potentially introduce some bigger questions like "do we need a registry of academies?" However, the technical piece doesn't feel too complicated.

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.

[e0d]

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.

[Kelketek]

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.

[OmarIthawi]

@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.

[edschema]

Hi @RawanMatar89 and @IvanStepanok. Really excited to see this!
I think it will be helpful to enumerate the tradeoffs of this approach vs others (remote configuration or build time configuration) in more detail to give visibility into the benefits of each. This relates to conversations that were held around implications on push notifications, theming, and offline modes.

Would like to have all the thinking laid out so those in the community can understand the impact of this approach and why the team working on this believes it's still preferable to others.

[edschema]

Another question: what impact will this shift have on instances that only require a single tenant solution?

[IvanStepanok]

Two concerns that may block Multi-Tenant adoption

1. Third-party authentication (Google/Microsoft/Facebook, SAML/OIDC).
   Today the mobile apps ship with a single OAuth client per LMS installation, which makes third-party sign-in effectively app-scoped at build time. In a multi-tenant runtime, this constrains us to the basic username/password flow unless we add a per-tenant web-based login. Pragmatically: drive login via a WebView/deep link to each tenant’s LMS auth (OIDC/SAML) and return to the app via the standard OAuth redirect, so every tenant controls its own IdPs without baking them into the app. 
2. Theming/branding.
   If we intend to adopt Paragon’s design-token theming, we should land that first and then enable multi-tenant branding. Otherwise we risk building a bespoke theme manager now and re-implementing it to align with Paragon tokens later. I have an MVP that switches themes at runtime by loading CSS from the LMS for web content. Native surfaces can read the same tokens to keep parity. 

https://stepanok.com/test-themes/theme1_light.css

Simulator.Screen.Recording.-.iPhone.17.Pro.-.2025-09-29.at.15.52.31.yafw.balanced.mp4

[edschema]

Thanks @IvanStepanok and @RawanMatar89
To me a WebAuth is totally acceptable; it's common with many apps at the moment.

@IvanStepanok Design tokens seem very logical. Is there an interim solution to allow us to get this off the ground without design token theming that also allows us to avoid too much re-work? Would creating the config files/ adding multi-tenancy without design tokens add significantly more work than current builds necessitate?

[IvanStepanok]

@IvanStepanok Design tokens seem very logical. Is there an interim solution to allow us to get this off the ground without design token theming that also allows us to avoid too much re-work? Would creating the config files/ adding multi-tenancy without design tokens add significantly more work than current builds necessitate?

@edschema Sure, we can change only accent color by using our current Theme implementation. We already have an update function to change any colors. That’s really enough for the first implementation. Also, we can get the tenant logo from the web and save the URL for an PNG image in the config file.

[OmarIthawi]

@IvanStepanok Design tokens seem very logical. Is there an interim solution to allow us to get this off the ground without design token theming that also allows us to avoid too much re-work? Would creating the config files/ adding multi-tenancy without design tokens add significantly more work than current builds necessitate?

@edschema Sure, we can change only accent color by using our current Theme implementation. We already have an update function to change any colors. That’s really enough for the first implementation. Also, we can get the tenant logo from the web and save the URL for an PNG image in the config file.

Even if we go with design tokens, if we limit the options down to low number e.g. 7 customized colors or even lower it would be a really good start.

I recommend getting the smallest amount of work as a corner stone to kickstart this effort. We need to set major goals and a roadmap with minor steps that eventually reach those goals.

[andrey-canon]

Hi @RawanMatar89
Thanks a lot for putting this proposal together — I really see the value in it.
For many providers, maintaining a separate app per tenant has become unsustainable, so having a single multi-tenant app is a really meaningful step forward.

That said, I’m not a big fan of the idea of having tenants pre-configured inside the app. That would put us right back in the position of needing a new release every time a tenant is added, which kind of goes against the whole goal of this proposal.

I really like the idea of letting users select their tenant at runtime. There’s already an existing endpoint in the MFEs that provides branding information, and I think we could implement something similar for the mobile app. This would allow tenants to expose a basic configuration that the app can use — things like logos, primary colors, and any other required settings — and also signal whether they should be discoverable and supported by the app.

On the authentication side, I fully agree with @IvanStepanok ’s suggestion. I’ve had to support SAML login in a mobile app before, and it was a nightmare. In the end, we ended up building something kind of similar to what’s being proposed now, but with a lot more limitations. So I’m really happy to see this direction.

My main concern is push notifications. While the approach makes sense technically, I’m imagining this as a general Open edX mobile app that anyone can use by default if their LMS is Open edX. That brings up the question of who would actually maintain and operate the notification service behind it.

Maybe we’ll need to think about more complex options, like letting each tenant handle their own notification service — but I’m not sure how viable that is technically. And honestly, we might also want to consider whether push notifications should even be part of the first version of a multi-tenant app. That might simplify things a lot.

[itsjeyd]

Hey @RawanMatar89, just checking in to see if you're still planning to continue working on this PR?

[itsjeyd]

Hi @RawanMatar89! Just a quick update that I'm closing this PR now because it is stale. You're welcome to reopen this pull request, or open a new one, when you have time to come back to this work.

[OmarIthawi]

Thanks @itsjeyd. We might revive it in few months from now.

[itsjeyd]

Sounds good, thanks for the update @OmarIthawi!

[juancamilom]

Hi all — picking this back up now that the momentum around this is high.

I want to make the connection explicit for anyone following both: the direction OEP-68 laid out — runtime tenant/instance selection, JSON-based per-instance config, backward-compatible single-instance behavior — is the same direction we've continued developing through the Mobile Product Working Group, under [Multi-instance configuration for the Mobile Apps].

That conversation moved into a new thread rather than continuing here, but it's a continuation of this work, not a separate one — @RawanMatar89 , @IvanStepanok , @edschema and others have been part of it alongside @kdmccormick .

Where things stand now: we've landed on a curated-mode-first v1, deferring the fully open/no-registry model discussed here. Schema is close to what's sketched in this OEP.
We are aligning on the additional enablers for things like Concurrent multi-tenant sessions, alternative login workflows (login before site selections and / or site selection before login).
As per @OmarIthawi 's suggestion, we are likely going to split the product/UI/infrastructure layers into separate, more reviewable PRs

For process: we're aligning on this through the product proposal first — once that reaches consensus, we'll move to formalize it back into this OEP, rather than running both in parallel indefinitely.

[OmarIthawi]

@marcotuts