Epic Issue:

​
OAuth 2 is a large specification, and there are many use cases and goals that we are attempting to address by implementing OAuth 2 into Synapse. We can separate this development into incremental components that can be built separately and sequentially to elevate different use cases. We can define each development phase by the features implemented, and organize use cases around these phases.

Developers are encouraged to reanalyze requirements before each phase, because this document offers only example suggestions for which components of OAuth to implement for each use case. Better solutions may be available.

Use Cases

We will separate use cases into selected use cases (those which we are actively trying to enable), other use cases (those use cases that have been conceptualized, but are not yet committed to/being enabled) and implied use cases (use cases that are driven by goals, which are listed later, rather than user needs). Priority/necessity of other use cases is unclear, but due to the general nature of OAuth, we can track them to identify if their requirements are met when we achieve other use cases.

Selected Use Cases

Other Use Cases

These require work to be done by maintainers of one or more tools not maintained by the Platform team. Because OAuth is such a general spec, we track these only to understand if they are enabled by work done for other use cases.

Goals

• Enable selected use cases that require OAuth 2.0

• Simplify authentication mechanisms in Synapse

  • Deprecate session tokens and API keys, making the only two supported authentication mechanisms in Synapse username/password, and OAuth 2 access tokens.

  • Remove/discourage password use where it is not absolutely necessary

  • Consideration: authorization with username/password may at one point require MFA – this is incompatible with certain OAuth flows

    ​
    
    

     

Implied Use Cases based on Goals

OAuth 2.0 to authorize a first-party Synapse command line app

• One consideration is which flow the command line app is supposed to follow, and how it uses it

  • Authorization code flow

    • Requires a browser

      • Option 1: Show a link to authenticate, display the authorization code in the browser, user is required to copy and paste it

        • Works in browserless environments

        • See GSUtil

      • Option 2: Auto-open a browser, user authenticates, redirect to the terminal

        • Least friction

        • Additional complexity/vector for attack if not using PKCE

        • Impossible in browserless scenarios and requires a fallback

OAuth 2.0 to authorize the GWT Web Client

• Assumed to use Authorization Code flow

• GWT uses a client-server model, so we should consider the possibility of storing an OAuth client secret on the server, if possible

  • If implemented client-side (i.e. public client credentials), PKCE should be required

• Would require shifting all authentication activities to one centralized source (e.g. signin.synapse.org)

• Strongly consider creating exceptions for certain OAuth clients that should have implied consent (lots of friction and confusion if a user has to consent to the web client accessing their data every time they sign in)

  • Implications of this?

Phases and Requirements

Each phase will be complete when all of its requirements (as well as all requirements in previous phases) are complete.

Phase 1: Short lived access tokens to confidential clients to access OAuth 2/OIDC resources

Use Cases

• Synapse as an identity provider

• Short lived access to Synapse resources

Requirements

• Register OAuth 2.0 clients in Synapse

• Use the authorization code flow to generate scoped access tokens for a client to act on behalf of a user

• Issue user identity information compliant with OIDC 1.0 via OAuth 2

Notes

At the time of writing, this phase has already been completed. For the sake of simplicity, all components are consolidated into one phase, and not all requirements may be captured here.

Phase 2: Long-lived confidential client authorization using authorization code flow

Use cases

• Workflows

Requirements

• Issue refresh tokens to confidential clients using the authorization code flow

  • PLFM-5753 - Getting issue details... STATUS

• Provide mechanisms to resource owners and clients to revoke refresh tokens

  • PLFM-6120 - Getting issue details... STATUS

Notes

Since the use case dictates that OAuth clients in this use case will necessarily

• Be confidential clients

• use the authorization code flow

we do not need PKCE at this time.

For more information, see the design document, OAuth 2.0 Refresh Tokens and Revocation

Phase 3: OAuth2 public client access via authorization code flow or generated refresh tokens

Use cases

• Synapse command line clients

• Cron jobs

Requirements

• Implement optional PKCE in authorization code flow

  • Consider identifying public and confidential status of clients, and handling them differently (e.g. public clients must use PKCE)

• Allow users to manually issue scoped refresh tokens for particular clients

• Consider supporting authorization code flow in the Python client

  • Not strictly necessary if users can manually issue a token.

Notes

Phase 4: “Frictionless” authorization for OAuth via first party apps

Use cases

• OAuth in the GWT client

• Deprecating session tokens

Requirements

• Consent skipping for specific clients, including the GWT client.

• Determiniation that session tokens are not used elsewhere

What Shouldn’t Be Built

This section includes a sample of proposed solutions that have been rejected, along with reasoning for the rejection