As a service provider I want to provide a default integration manager for users with accounts on a homeserver instance I manage

[lampholder]

My choice of default integration manager is presented to all Riot users using my homeserver

• CLARIFICATION: What does it mean to be the 'default integration manager'? It means that if the user makes no other choices about integration managers, when they go to use the integration manager or sticker picker they will be prompted to accept the terms of service of this integration manager (and will use it from that point on)
• CAVEAT: For now the default integration manager will be communicated via .well-known - ultimately this might be better located in the homeserver's /info endpoint or similar
• CAVEAT: Smooth transition for users if I change the default integration manager is not supported - I may need to ask users to delete all of their existing widgets
• KNOWN BUG: Jitsi will not work! Riot finds its jitsi instance either by deriving it from the integration manager URL (in a scalar-specific way that will result in an infinite spinner for Dimension users), or clients might override the jitsi instance manually by setting the integrations_jitsi_widget_url configuration option (in which case the client will use that jitsi instance regardless of what the service provider wishes)
• KNOWN BUG: Scalar widgets will all render as FORBIDDEN (until Scalar implements MSC1960
• KNOWN BUG: Sticker pickers will sometimes break on Riot Web. If a user has a pre-existing scalar sticker picker configured against their account (if they used riot.im/app before the .well-known lookup for integration managers was implemented), they will see FORBIDDEN when opening their sticker picker. This can be fixed manually using /devtools, and Dimension tries to fix it automatically too, but falls foul of an incidental Riot web bug in which sticker pickers don't remount
• KNOWN BUG: Sticker pickers might not work on mobile. Even if mobile implements the domain-based "whitelisting" and sends the sticker picker widget an auth. token, we're not certain that Dimension will actually pay attention to the auth token (seeing as Dimension expects to be able to use the OpenID exchange API as it does in Riot Web).
• KNOWN BUG: Dimension tokens might get leaked to Scalar. If a user tries to render a Scalar widget, Scalar will (we think) be sent the Dimension access token (@turt2live is considering whether this can be resolved trivially)

[turt2live]

This issue probably solves our whitelist concerns. Widgets could use MSC1960 to get tokens instead of a whitelist.

Maybe we need an MSC for ToS exchange (so clients can render prompts natively rather than expect widgets to match up UI/UX)

[lampholder]

Today, we have 'whitelists' in the Riot apps. These whitelists decide whether the client is happy to send a scalar token (== poorly-named integration manager authentication token) to a given widget.

In Riot Web, this whitelist is configured manually, in config.json.

In Riots Mobile, this whitelist is provided in the build configuration (so effectively hard-coded in the apps as downloaded from the app/play store). The mobile apps also 'whitelist' requests to the domain on which the integration manager is hosted (so if you have an auth token for the integration manager at integrations.acme.com, your client will send that auth token to widgets hosted on integrations.acme.com/whatever).

Dimension and Scalar react to the absence of authentication tokens differently. Scalar shows FORBIDDEN, because it wants you to auth before it will load any of the widget code (regardless of whether the widget requires auth). Dimension just loads the widget. If the Dimension widget needed an authentication token, it would get itself using the OpenID exchange API (MSC1960).

So I think we have five possible options ahead of us:

1. Copy the mobile behaviour into Riot Web ('whitelisting' the domain which serves the integration manager), understanding that this is not a step towards our envisioned glorious integration management utopia. This approach means that an integration manager cannot choose to host its widgets on a different domain, something that Dimension technically supports (though is thought to be very rarely used in practice).
2. Figure out some other way to get whitelists that support a given integration manager (such as also including them in the same .well-known that tells the client where the integration manager is hosted)
3. Fix up Scalar so that it doesn't require authentication tokens to be passed into it (and can, where necessary, get an authentication token itself through the OpenID exchange API (MSC1960)
4. Do nothing and know that in most cases everything will seem to be fine: service providers who want to run their own integration manager will use Dimension, not Scalar, and so:
   • if Riots web and mobile get their integration manager details from .well-known then service providers can use this to dictate a choice of integration manager
   • the fact that whitelists-for-custom-integration-managers are working incompletely on mobile and not at all on generic riot web won't actually be visible to users, though opening widgets might be a little slow*
     I think this will work, but my fear would people would quickly lose track of why it works
5. Roll back support for this feature

• possible slowness on generic riot webs deriving from the Dimension-hosted widget being forced to fetch its own authentication token every time since it won't be on an effective whitelist.

[lampholder]

Implementation Details

• On Riot Web: nothing to do
• On Riot Android: probably nothing to do
• On Riot X: no integration managers yet so nothing to do
• On Riot iOS: we still need to check .well-known for the integration manager, at least at login

The end result of the above changes is:

• Riot Web:

  • .well-known:
    • Riot Web will check .well-known at startup and every 8 hours for an integration manager
    • Riot Web will use whatever value it finds as an integration manager
  • Whitelists:
    • Widgets provided by non-Scalar integration manager won't be on a whitelist, so Riot won't send them an authentication token, but this integration manager is going to be Dimension which can still work without being passed an authentication token
    • Riot Web won't leak the Dimension authentication token to scalar (despite the scalar whitelists still being configured) because @turt2live fixed this
  • Experience for users using non-Scalar integration managers:
    • Scalar widgets will not open (they will render as FORBIDDEN)
    • Jitsi won't work unless you're using a Riot Web instance with custom configuration of integrations_jitsi_widget_url
    • The sticker picker might work, if you haven't already used a scalar sticker picker. If you have already used a scalar sticker picker, there's a way to fix things but it's a bit glitchy

• Riots Mobile:

  • .well-known:
    • Riots Mobile will check .well-known at login only
    • Riots Mobile will use whatever value they find as the integration manager
  • Whitelists:
    • Riots Mobile will use the integration manager domain as a "whitelist", so will send authentication tokens to non-Scalar widgets
  • Experience for users using non-Scalar integration managers:
    • Scalar widgets will not open (they will render as FORBIDDEN)
    • Jitsi won't work full stop
    • The sticker picker almost certainly won't work, with no way to remedy this (because even though riot mobile is using the .well-known provided integration manager domain as a "whitelist" meaning it will send an authentication token to the sticker picker (something Riot Web won't do), we don't think the Dimension sticker picker is actually configured to listen to authentication tokens being passed in this way

At the same time as making no changes to support this in Riot, we will be pushing for the resolution of the /info msc - once there is a better place from which a homeserver admin can push a chosen integration manager we will switch to that. The target schedule for this is getting /info MSC agreed by November (2019) and implemented across Riots web and mobile by Christmas (2019)