This page is starting as a collection of notes, design decisions, etc. related to implementing OAuth2 into Synapse. Part of the process has included considerations about developing our own library, or using an off-the-shelf solution like ORY Hydra. The information on this page may change as the project evolves.

See also: @Bruce Hoff's presentation on his preliminary research into OAuth2 and how it relates to Synapse.

More reading for historical purposes: Synapse as OAuth 2.0 Provider

And a Jira Epic: 

Good summary of OIDC: https://github.com/dexidp/dex/blob/master/Documentation/openid-connect.md

Use cases

High level use-cases, per @Bruce Hoff's presentation:

1. Let third party (web) applications securely access a user’s data in Synapse.  Today such applications must either

2.  

   1. predownload/embed data,

   2. use the application author’s Synapse credentials, or

   3. prompt the user for their Synapse credentials

3. Let a headless batch job (e.g.,a “workflow”) securely access a user’s data in Synapse.  Today such a process must either

4.  

   1. Use predownloaded data

   2. Use the job runner’s Synapse credentials

Brief Overview of OAuth2

This document presupposes a basic (not necessarily thorough) level of understanding of OAuth2. There are four authorization grant flows in the OAuth spec. They can be summarized:

• Authorization Code grant (most secure, client secret confidentiality must be guaranteed)

  1. Upon user consent, an OAuth client (3rd party) is granted an authorization code

  2. The authorization code can be used with a client secret to obtain a scoped access token.

  3. The access token can be used to access resources until it expires or is revoked

  4. The access token can be refreshed by the client with a refresh token and the client secret.

• Implicit code grant (client secret confidentiality cannot be guaranteed)
  
  

  1. Upon user consent, an OAuth client (3rd party) is granted a scoped access token.

  2. The token can be used to access resources until it is expired or revoked, but it cannot be refreshed. The time that the token is active is typically very short (minutes).

• Resource owner password credentials (not secure, especially with an untrusted client)

  1. The user provides their username and password to the OAuth client

  2. The OAuth client uses the credentials to obtain a scoped access token

• Client credentials (used for cases where clients manage their own resources, i.e. not really authorization delegation)

  1. The OAuth client can request an access token with their client ID and client secret

OAuth2 in Synapse - API Design

The current proposal is to introduce OAuth2 authorization code flow into Synapse. OAuth clients would be instructed to use authorization codes only.

Backend

We can separate the endpoints required on the backend based on task.

Client Management

Basic CRUD for OAuth2.0 clients.

Authorization/Consent Requests

These endpoints are necessary for users to approve/reject OAuth2.0 access requests

Token Requests

These endpoints would be used by OAuth2.0 clients to retrieve tokens with an access code

OpenID Connect services

Web Layer Interfaces (Portal)

The portal needs to implement interfaces for handling the components of OAuth2 that are best accomplished through user interfaces.

Diagrams to show where these API endpoints would be used and what objects/params are needed:

Open

Open

How do we know if we're up-to-spec when we are done?

If we implement OIDC, there is a process to become OIDC-certified here: https://openid.net/certification/

I think that to have OIDC configured properly, you must have OAuth2 configured properly, so this would cover both cases. (I would like to investigate this further if we do decide to implement OIDC)

If we do not implement OIDC (just OAuth2) there doesn't seem to be any certification process that I can find. We may have to read the spec ourselves and hope we don't miss anything with thorough tests, future security audits, etc.

What is "scope"?

JIRA: 

In short: scopes are clearly defined permissions that a user may grant to an OAuth client.

In ORY Hydra, OAuth clients may be limited in the scope they can request (e.g. a photo printing service (OAuth client) may be restricted to only acquire read-photo permission, even if they attempt to request edit-photo permission). This is not a requirement of our implementation, but it is worth consideration.

From RFC-6749

The authorization and token endpoints allow the client to specify the scope of the access request using the "scope" request parameter. In turn, the authorization server uses the "scope" response parameter to inform the client of the scope of the access token issued.

The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings. The strings are defined by the authorization server. If the value contains multiple space-delimited strings, their order does not matter, and each string adds an additional access range to the requested scope. scope = scope-token *( SP scope-token ) scope-token = 1*( %x21 / %x23-5B / %x5D-7E )
The authorization server MAY fully or partially ignore the scope requested by the client, based on the authorization server policy or the resource owner's instructions. If the issued access token scope is different from the one requested by the client, the authorization server MUST include the "scope" response parameter to inform the client of the actual scope granted. If the client omits the scope parameter when requesting authorization, the authorization server MUST either process the request using a pre-defined default value or fail the request indicating an invalid scope. The authorization server SHOULD document its scope requirements and default value (if defined).

The actual encoding and representation of scope is not necessarily within the scope of this document (ha ha), but it is something that will likely strongly guide our implementation of OAuth. Naturally, how we design scope should be informed by use cases. We should methodically determine what access we wish to grant OAuth2 clients, as well as how much granularity (both breadth of permissions and Synapse object access) we can/should reasonably encode. Additionally, this should be informed by how we have designed and use ACLs, since this paradigm of authorizing access to content in Synapse is likely to be the driver of OAuth-based content authorization.

An OAuth2 client developer must be able to determine the scope that they need when designing their OAuth2 client service, so it is also critical that we document 

Examples of OAuth2 scope documentation in the wild:

• Slack

• Facebook

• Google

If we choose to be ultra-granular with scope (e.g. only granting read access to one particular file, with a permission structure like read:syn123), we will likely have to store these scopes in a database. One implementation option is to make scope a UUID and store the actual scope information in a database; the downside: client developers may have to generate scope UUIDs on-the-fly. This also seems to conflict with the design decisions of other OAuth providers (see external documentation samples above).

Worth looking into: UMA

Stack overflow that led me towards UMA: https://softwareengineering.stackexchange.com/questions/372526/how-to-handle-per-resource-fine-grained-permissions-in-oauth

The spec: https://docs.kantarainitiative.org/uma/ed/uma-core-2.0-01.html

Possibly of interest is the HEART Working group: https://openid.net/wg/heart/

HEART WG aims to standardize data sharing in healthcare using HFIR, OAuth, OIDC, UMA. They seem to be more aimed at patients having control over data they share, but some of their specs may be appropriate for some of our use cases

ORY Hydra

This is a good place to collect information and research relevant to using ORY Hydra to implement OAuth2 and OIDC in Synapse. This portion of the document is not complete, and may not be completed if we choose not to use ORY Hydra to implement OAuth2.

Why ORY Hydra:

Per @Bruce Hoff's preliminary research, ORY Hydra is one of very few (and perhaps the only) established, off-the-shelf OAuth2 + OIDC solution that delegates authorization provider and resource provider roles to external services. Since Synapse already has this infrastructure in place (excepting interfaces for OAuth2 authorization flow), we can use Hydra to handle some of the more complicated parts of implementing OAuth2 and OIDC, and create our own authorization/resource provider services that use existing Synapse infrastructure.

Why NOT ORY Hydra:

To be expanded upon later, and points may be focused upon later in this document.

• Possible future maintenance costs, incompatibilities with our infrastructure, and other tech-debt related concerns

• Overkill for our use case?

Does Hydra work with our use cases?

For example, can we implement our proposed scope pattern into Hydra? What other constraints exist in Hydra that may be major roadblocks? 

ORY Hydra in the wild

Can we find cases of other engineers using Hydra?

What problems have they run into?

What benefits have they seen that Hydra provides?

What other potentially crucial information about Hydra can we find on the internet?

ORY Hydra authentication + consent flow

See the user guide

Hydra stores its own authentication sessions (this would be a redundancy in Synapse). Additionally, the Hydra documentation instructs implementers to not utilize session in the authentication provider (I think we probably could if we wanted to, but we would want to be thorough in our understanding of how Hydra handles sessions in these cases).

1. An OAuth client will redirect a user to a page controlled by the Hydra server to authenticate the user.

   1. If the user has an existing Hydra authentication session go to #,

2. With no existing authentication session, the user is redirected to an authentication provider (i.e. Synapse login) to enter and credentials.

3. The authentication provider will authenticate the user and communicate info about the user directly to Hydra

4. The user is redirected to Hydra for authorization, which will redirect the user to the consent provider (i.e. Synapse).

5. The consent provider will ask the user for permission to grant access to the requested resources and will directly tell Hydra if the user accepts or rejects the request.

6. The user is redirected to the OAuth client. Hydra handles access code and token generation.

Decisions and requirements to deploy via Cloudformation

See:

Internal configuration

We should tailor ORY Hydra's configuration to meet our needs

Database