Skip to content

Latest commit

 

History

History
115 lines (71 loc) · 6.74 KB

3824-oidc-aware-clients.md

File metadata and controls

115 lines (71 loc) · 6.74 KB
Raw

MSC3824: OIDC aware clients

This proposal is part of the broader MSC3861: Matrix architecture change to delegate authentication via OIDC.

In the context of MSC2964 we can define four types of client:

  1. OIDC native client - This is a client that, where the homeserver supports it, talks to the specified OpenID Provider in order to complete login and registration. e.g. Element X (WIP), Hydrogen (WIP)
  2. OIDC aware client - This is a client that is aware of OIDC but will still use existing auth types (e.g. m.login.sso) to auth with an OIDC enabled homeserver.
  3. Legacy client with SSO support - This is a client that is not aware of OIDC but does support m.login.sso flow. e.g. Element Web, iOS, Android, Fluffy, Nheko, Cinny
  4. Legacy client without SSO support - This is a client that is not aware of OIDC at all and nor does it support m.login.sso flow. Typically auth is done via m.login.password only. e.g. Fractal

The purpose of differentiating #2 and #3 is that, for a Legacy client with SSO support, the user journey can be optimised with minimal modifications when talking to an OIDC enabled homeserver.

This proposal outlines changes to facilitate clients in becoming OIDC aware.

Proposal

Firstly, a client can specify which action the user is wanting to achieve at the point of SSO redirection. This allows the homeserver to display the most relevant UI to the user.

Secondly, the homeserver can optionally specify which auth type is delegated_oidc_compatibility are supported for an authentication type.

Homeserver indicates that an m.login.sso flow is for compatibility

Add an optional delegated_oidc_compatibility field to the response of GET /_matrix/client/v3/login:

"delegated_oidc_compatibility"?: boolean

For example, if a homeserver is advertising password login for legacy clients only then it could return the following:

{
  "flows": [{
    "type": "m.login.password"
  }, {
    "type": "m.login.sso",
    "delegated_oidc_compatibility": true
  }]
}

If the client finds delegated_oidc_compatibility to be true then, assuming it supports that auth type, it should present this as the only login/registration method available to the user.

Client indicates action on SSO redirect

Add an optional query parameter action to GET /_matrix/client/v3/login/sso/redirect and GET /_matrix/client/v3/login/sso/redirect/{idpId} with meaning:

  • login - the SSO redirect is for the purposes of signing an existing user in
  • register - the SSO redirect is for the purpose of registering a new user account

e.g. https://matrix-client.matrix.org/_matrix/client/v3/login/sso/redirect?action=register

n.b. we don't need to add this to the Login Fallback as that isn't used for registration.

Definition of OIDC aware

For a client to be considered fully OIDC aware it must:

  • support the m.login.sso auth flow
  • where a delegated_oidc_compatibility value of true is present on an m.login.sso then only offer that auth flow to the user
  • append action=login and action=register parameters to the SSO redirect URLs
  • link users to manage their account at the OpenID Provider web UI given by MSC2965 instead of native UI
  • check and honour the m.3pid_changes capability so that the user is not offered the ability to add or remove 3PIDs when OIDC is used
  • if the user wishes to sign out a device session other than it's own then the client must:
    • link the user to the OpenID Provider web UI given by MSC2965 if provided
    • append the action and device_id to the web UI link parameters described by MSC2965 so that the web UI knows that the user wishes to sign out a device and which one it is. e.g. ?action=session_end&device_id=<device_id>

Optionally, an OIDC aware client could:

For an OIDC enabled homeserver to provide support for OIDC aware clients it must:

  • support OIDC delegation as per MSC2964 and others
  • provide a compatibility layer for m.login.password and m.login.sso that wraps on to OIDC
  • indicate that the m.login.sso is preferred by setting delegated_oidc_compatibility to true
  • make use of the action param on the SSO redirect endpoints

Additionally, the homeserver should:

  • advertise the account management UI in accordance with MSC2965

Potential issues

None.

Alternatives

Clients could assume that an m.login.sso is preferred directly from where MSC2965 OpenID Provider discovery indicates OIDC is being used. However, this might hamper some more custom configuration.

The homeserver could only offer m.login.sso as the supported auth type but this would prevent non-SSO capable legacy clients from accessing the homeserver.

Capabilities negotiation could be used to indicate that m.login.sso is preferred.

For the param on redirect: a prompt parameter with values create and login exists in OIDC for use on the authorized endpoint. However, our use case is different and it might cause confusion to overload these terms.

Security considerations

None relevant.

Unstable prefix

While this feature is in development the following unstable prefixes should be used:

  • delegated_oidc_compatibility --> org.matrix.msc3824.delegated_oidc_compatibility
  • action query param --> org.matrix.msc3824.action

Dependencies

This MSC depends on the following MSCs, which at the time of writing have not yet been accepted into the spec:

  • MSC2964: Delegation of auth from homeserver to OIDC Provider
  • MSC2965: OIDC Provider discovery