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.
...
And a Jira Epic:
| Jira Legacy | ||||||||
|---|---|---|---|---|---|---|---|---|
|
...
Use cases
High level use-cases, per Bruce Hoff's presentation:
- Let third party (web) app’s securely access a user’s data in Synapse. Today such app’s must either
- predownload/embed data,
- use the app’ author’s Synapse credentials, or
- prompt the user for their Synapse credentials
- Let a headless batch job (e.g.,a “workflow”) securely access a user’s data in Synapse. Today such a process must either
- Use predownloaded data
- Use the job runner’s Synapse credentials
These use cases must guide how we encode scope.
Some questions:
- How granular do we expect scope must be?
- Do Read/Edit/Write permissions cover all use cases?
- Can
Basic OAuth or OAuth-like flow (authorization grant only, no external tools)
To implement the bare minimum to address use cases with an OAuth-like flow, we need
- Endpoints to create, read, list, delete (and optionally, update) clients
- Authentication code generation
| Verb | Endpoint | Purpose | Input Object/Params | Return Object/Params | Notes |
|---|---|---|---|---|---|
| GET | /oauth2/clients | Get a list of all clients | Client API access can be restricted based on our needs.
| ||
| GET | /oauth2/clients/{id} | Get details about one client | id: a client ID | ||
| POST | /oauth2/clients | Create a client | what information do we need from a client? client object | client object + secret key (do not store the secret key) | |
| DELETE | /oauth2/clients/{id} | Delete a client | client ID | - | |
| Can Synapse authenticate users with existing endpoints and services? Do we need new ones? | |||||
| GET | /oauth2/authorize |
scope
Prompt user for request when they call this. Show as much relevant information as possible (X app wants Y permission on Z resource) | client (ID) | Web interface for Synapse authorization | Verify here if the user can actually grant the scope they request? If we support granting scope to particular entities, when should we make sure the user has access to the entity? Upon authorization token request? Upon attempt to access the entity with the token? | |
| POST | /oauth2/authorize |
scope
| User must accept or decline request | client (ID) LoginRequest | Redirect URL containing authentication code tied to the input client ID and the scope |
LoginResponse? | How to handle with various Synapse IdPs? (E.g. Synapse users who sign in with Google accounts) |
| GET | /oauth2/token | Called by a client to get a token with an authorization code | authorizationCode | authentication token |
refresh token |
clientSecret(and may not be correct)
| POST | /oauth2/token/refresh | Called by a client to refresh an authentication token | refresh_token |
| authentication_token | |||||
| Many Existing APIS must now support Authorization tokens? | |||||
| GET | /oauth2/token/introspect | Clients can determine if an authentication token is valid | This may not be necessary (but could provide a lot of utility to clients) | ||
Diagram from the above presentation, edited to show where these API endpoints would be used:
What is "scope"?
JIRAs(?):
| Jira Legacy | ||||||||
|---|---|---|---|---|---|---|---|---|
|
...
We should tailor ORY Hydra's configuration to meet our needs
Database
Per the ORY Hydra docs:
The SQL adapter supports two DBMS: PostgreSQL 9.6+ and MySQL 5.7+. Please note that older MySQL versions have issues with ORY Hydra's database schema. For more information go here.
If my understanding is correct, the DB that Hydra uses is entirely separate from other services, so it should not be a concern here that Synapse currently uses MySQL 5.6
...
The administrative port should not be exposed to public internet traffic. If you want to expose certain endpoints, such as the
/clientsendpoint for OpenID Connect Dynamic Client Registry, you can do so but you need to properly secure these endpoints with an API Gateway or Authorization Proxy.
Do we need this?
Spring Security
...