Path param:

id: an existing OAuth2 Client ID

OAuth2Client

name: String

redirect_uri: String

client_id: Unique

created_by/on

modified_by/on

Supplemental params

OAuth2Client

name: String

redirect_uri: String

Supplemental params

OAuth2Client

name: String

redirect_uri: String

client_id: Unique

client_secret: String

created_by/on

modified_by/on

Supplemental params

Supplemental params could include the URL to a logo, link to a website for the app, terms of service, etc.

Typically the secret key is used to perform these actions, but if we give Synapse users a claim over an OAuth2 client, we could use their credentials.

Path param:

id: an existing OAuth2 Client ID

Display the login/consent info to the user and prompt for an accept/reject

URL Parameters:

response_type: String (always "code")

client_id: Unique

redirect_uri: String (points to OAuth client)

scope: String

state: String

Web interface for Synapse authorization

The form should permit login and we must be able to include the request parameters in a new request

This endpoint should point to a web layer that can show a UI with a login form and display the access that the user can consent to, along with a prompt for the user to accept/reject.

We should think about using login cookies here to simplify the UX if a user is already logged into Synapse

URL Parameters:

response_type: String (always "code")

client_id: Unique

redirect_uri: String (points to OAuth client)

scope: String

state: String

Body:

LoginRequest (already exists)

If login is successful:

Redirect URL:

redirect_uri (provided in request)

Parameters:

code: the authorization code

state: the same value in the request

Should we include a LoginResponse body?

(Probably not, if the body is kept in the redirect then we may be exposing a session token to the 3rd party client)

Who should execute this? The User Agent or the Web Layer on behalf of the user agent?

Question: how to handle with various Synapse IdPs? (E.g. Synapse users who sign in with Google accounts).

The "state" parameter is designed to avoid CSRF attacks. More info.

Body:

OAuth2AuthorizationCodeTokenRequest

grant_type: String (always "authorization_code" for this call)

code: String (the authorization code)

redirect_uri: String (should be the same as previous redirect uri)

client_id: Unique

client_secret: String

Body:

OAuth2AccessToken

access_token: String

token_type: String ("Bearer")

expires_in: Integer (seconds)

refresh_token: String

(optionally, scope)

The redirect URI should be validated here before granting a token, along with the credentials in the request. More info.

The token type in almost all OAuth2 cases is "Bearer". We can use a different token type (or make our own) if we want to, but there is probably no need. More info.

/oauth2/token

or

/oauth2/token/refresh

Body:

OAuth2AuthorizationCodeRefreshTokenRequest

grant_type: String (always "refresh_token" for this call)

refresh_token: String

client_id: Unique

client_secret: String

Body:

OAuth2AccessToken

access_token: String

token_type: String ("Bearer")

expires_in: Integer (seconds)

refresh_token: String

/oauth2/token/introspect

or

/oauth2/token/info

Body:

OAuth2TokenIntrospectionRequest

token: String

client_id: Unique

client_secret: String

Body:

OAuth2TokenIntrospectionResponse

active: Boolean

client_id: Unique

username: String (principal of user who authorized)

exp: Date (seconds until expiration)

scope: String

A logged in user can revoke OAuth2 client access using this method.

OAuth2RevokeRequest

client_id: unique

Is there a need for more granularity?

Revoking access not in the OAuth2 spec but allowing users to revoke client access may be important.