MSC2858: Multiple SSO Identity Providers

Matrix already has generic SSO support, but it does not yield the best user experience especially for instances which wish to offer multiple identity providers (IdPs). This MSC provides a simple and fully backwards compatible way to extend the current spec which would allow clients to give users options like Continue with Google and Continue with Github side-by-side.

Currently, Matrix supports m.login.sso, m.login.token and /login/sso/redirect for clients to pass their user to the configured Identity provider and for them to come back with something which is exchangeable for a Matrix access token. This flow offers no insight to the user as to what Identity providers are available: clients can offer only a very generic Sign in with SSO button. With the currently possible solutions and workarounds the experience is far from great and user's have to blindly click Sign in with SSO without any clue as to what's hiding on the other side of the door. Some users will definitely not be familiar with SSO but will be with the concept of "Continue with Google" or similar.

Proposal

We extend the login flow to allow clients to choose an SSO Identity provider before control is handed over to the server.

The response to GET /_matrix/client/r0/login is extended to optionally include an identity_providers property for flows whose type m.login.sso. This would look like this:

{
    "flows": [
        {
            "type": "m.login.sso",
            "identity_providers": [
                {
                    "id": "google",
                    "name": "Google",
                    "icon": "mxc://..."
                },
                {
                    "id": "github",
                    "name": "Github",
                    "icon": "mxc://..."
                }
            ]
        },
        {
            "type": "m.login.token"
        }
    ]
}

The value of the identity_providers property is a list, each entry consisting of an object with the following fields:

The id field is required. It should be a string using the common identifier grammar as defined in https://github.com/matrix-org/matrix-doc/pull/2758.
The name field is required. It should be the human readable string intended for printing by the client.
The icon field is optional. It should point to an icon representing the IdP. If present then it must be an MXC URI to an image resource.

Extend the `/login/sso/redirect` endpoint

A new endpoint is added to support redirecting directly to one of the IdPs:

GET /_matrix/client/r0/login/sso/redirect/{idp_id}

This would behave identically to the existing endpoint without the last argument except would allow the server to forward the user directly to the correct IdP.

For the case of backwards compatibility the existing endpoint is to remain, and if the server supports multiple SSO IdPs it should offer the user a page which lets them choose between the available IdP options as a fallback.

Notes on user-interactive auth

For the case of User Interactive Auth the server would just give the standard SSO flow option without any identity_providers as there is no method for a client to choose an IdP within that flow at this time nor is it as essential.

Potential issues

None discovered at this time

Alternatives

An alternative to the whole approach would be to allow m.login.sso.$idp but this forces treating an opaque identifier as hierarchical and offers worse backwards compatibility.

An alternative to the proposed backwards compatibility plan where the server offers a fallback page which fills the gap and lets the user choose which SSO IdP they need is for the server to deterministically always pick one, maybe the first option and let old clients only auth via that one but that means potentially locking users out of their accounts.

Security considerations

This could potentially aid phishing attacks by bad homeservers, where if the app says Continue with Google and then they are taken to a page which is styled to look like the Google login page they might be a tiny bit more susceptible to being phished as opposed as to when they click a more generic Sign in with SSO button, but this attack was possible anyhow using a different vector of a controlled Element/client instance which modifies the text.

Unstable prefix

Whilst in development use org.matrix.msc2858.identity_providers for the flow discovery and /_matrix/client/unstable/org.matrix.msc2858/login/sso/redirect/{idp_id} for the new endpoints.

4.7 KiB Raw Blame History