sessionToken: String

scope: String

scopedLoginResponse:

scopedSessionToken: String

acceptsTermsOfUse: Boolean

scope: String

exp: Integer (seconds until expiry)

This is a more secure alternative to the current session token as limits what can be done with the session token.

These can (should?) expire quickly (minutes-hours).

This could be done by passing in username and password rather than sessionToken, but we'd have to handle the case where the user has no password and logs in via Google (or other OAuth provider).

Parameters

clientId: Unique (the ID of an existing OAuth2 client requesting access)

scope: String

OAuth2Client

scopes: Array<string> 

e.g. [("read", "syn123"), ("create","syn456")]

(actual representation TBD)

URL Parameters:

response_type: String (always "code")

client_id: Unique

redirect_uri: String (points to OAuth client)

scope: String

state: String

If scopedAccessToken is valid:

Body:

OAuthClientUrl: String

redirect_uri?code={code}&state={state} (all provided in request)

Parameters:

code: the authorization code

state: the same value in the request

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 and the client must utilize it per RFC-6749 § 10.12. More info.

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.  Revocation should be at the token level not at the client level.

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)

As per OIDC the response should include both an access token and an ID Token, https://openid.net/specs/openid-connect-core-1_0.html#TokenResponse

Authorization codes must be single-use and short-lived. If an authorization code is used more than once, we should revoke the active access token retrieved with the code. More info @ RFC-6749 § 10.5

The redirect URI should be validated here before granting a token, along with the credentials in the request. More info @ RFC-6749 § 10.6.

The token should be opaque/unguessable. More info @ RFC-6749 § 10.3.  Update:  token could be JWT, https://www.oauth.com/oauth2-servers/access-tokens/self-encoded-access-tokens/.  Advantage is that permissions are 'built in' to the token.  Downside is that it becomes irrevocable.  So let's not use JWT.  

The token type in almost all OAuth2 cases is "Bearer". We can use a different token type (e.g. HMAC, or make our own) if we want to. See RFC-6749 § 7.1. Additional info.

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

Client authentication must be done here. This must be done over TLS. More info @ RFC-6749 § 10.4

/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 the token)

exp: Date (seconds until expiration)

scope: Array<String> (human-interpretable scope)

This endpoint is not strictly necessary, but we should strongly consider including this if we decide to not include scope with the access token.

See RFC-7662.