Versions Compared

Old Version 12

changes.mady.by.user Nick Grosenbacher

Saved on

compared with

New Version Current

changes.mady.by.user Nick Grosenbacher

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Note

The initial purpose of the document was to identify OAuth 2 as a solution for replacing API keys in the command line clients. We determined that OAuth 2 is not a good fit for the command line clients, so design work for that issue has been moved to Personal Access Tokens. OAuth 2 public client implementation has not begun, as of the time of writing.

This document still outlines requirements for OAuth 2 public clients, which may be worth implementing in the future.

Summary

Using OAuth 2 to authenticate with Synapse has many benefits over using older authentication mechanisms. We can try to consolidate authentication services to using OAuth flows wherever possible. This document focuses on enabling the creation of OAuth 2 public clients, which would allow OAuth 2 based authentication in Synapse command line apps and third-party browser-based SPAs. Additionally, this will hasten the deprecation of API keys.

...

Endpoint

Request Body

Response Body

Notes/Modifications

New Service?

POST /oauth2/client/

OAuthClient

OAuthClient

OAuthClient extended to require a new field clientType (enum with values PUBLIC,CONFIDENTIAL)

❌

POST /oauth2/client/secret/{id}

None

OAuthClientIdAndSecret

Do not generate client secrets for public clients.

❌

POST /oauth2/consent

OIDCAuthorizationRequest

OAuthAuthorizationResponse

OIDCAuthorizationRequest extended to include code_challenge, code_challenge_method. The fieldcode_challenge is required for clients of type PUBLIC.

❌

POST /oauth2/token

Multiple parameters

OIDCTokenResponse

Additional request parameter code_verifier, required if the corresponding authorization code is associated with a code_challenge.

❌

POST /oauth2/token

Multiple parameters

OIDCTokenResponse

Client secret not required if the client ID is a public client.

❌

POST /oauth2/token

Multiple parameters

OIDCTokenResponse

If a public client uses an expired/rotated refresh token, revoke the current ‘version’ of the refresh token

(e.g. refresh token is abcd with ID: 7, when it is used, the new refresh token is efgh with ID: 7. if someone attempts to use abcd again, revoke efgh.

❌

POST /oauth2/consent

POST /oauth2/token

-

-

Restrict client 0 from using these endpoints (this is already the case, but it is unclear if it is explicit).

❌

Support for first-party command line public clients

Command line apps (like the Synapse Python client) cannot always support the authorization code flow because some environments do not have a browser. To enable this, we must do at least one of the two:

  • Support another OAuth grant type (e.g. device_code)

  • Add a user-authenticated service to generate an OAuth refresh token

A user-authenticated service is similar to the OAuth token generation service in GitHub, and is similiar to how users retrieve API keys today, so we will move forward with that.

Endpoint

Request Body

Response Body

Notes

New Service?

N/A

N/A

N/A

Add a bootstrapped ‘Synapse Command Line’ OAuth client.

We use a new client and not client 0 for two reasons

  • If we add OAuth flows to command line apps, a user should see a prompt for authorizing ‘Synapse Command Line’, which they wouldn’t see for client 0

  • There is a limit on active refresh tokens per user-client combination. If we decide to use client 0 to issue refresh tokens elsewhere (e.g. for browser sessions), then they could interfere/invalidate command line sessions.

❌

POST /oauth2/userGeneratedToken

OIDCTokenGenerationRequest {

name: string (a unique-to-the-user, human-readable name. if unspecified, this will be a UUID)

clientId: string (the client that can use the OAuth token)

scope: Array<OAuthScope> (scopes granted by the tokens)

claims: OIDCClaimsRequest (claims granted by the tokens)

}

OIDCTokenResponse

Generates a token response that users can copy and paste into the command line client. Effectively replaces API keys.

In most cases, the clientId will be set to the ID used for the bootstrapped command line client (SWC could even hard-code it, since users likely only need to generate tokens for this client).

✅

...

References

[1] OAuth 2.0 (RFC 6749)

...