| Table of Contents | ||
|---|---|---|
|
Review Changes
For those viewing this document after the initial review meeting, here are the core changes made since then:
Added detail to workflow use case
Sequence diagrams
Removed CLI use case and related requirements
Requirements for workflows use case is a subset of the CLI requirements. Let’s tackle workflows first and talk about CLI later.
Renamed endpoints for auditing tokens from
/oauth2/permissionsto/oauth2/grantedClients
Overview and Selected Use
...
Case
This document will outline the design and implementation of OAuth 2.0 refresh tokens and token revocation in Synapse.
...
Field | Type | Description | |
|---|---|---|---|
client | Client information that can be displayed to the end user | ||
scopeauthorizedOnArray<OAuthScope> | date-time | lastUsed | The union of all scopes granted in refresh tokens issued to the client on behalf of the user This way a user can easily see all of the information a third party may have access to, even if it differs from token to token. |
authorizedOn | date-time | The time when access was first granted (i.e. the issue date of the oldest active refresh token) | |
date-timetime when access was first granted (i.e. the issue date of the oldest active refresh token) | |||
lastUsed | date-time | The most recent time a refresh token was used to issue a new access token |
...
Field | Type | Description |
|---|---|---|
token | string | The token to revoke |
token_type_hint | enum | The type of token to revoke (must be |
New API Endpoints
Seven This section outlines new endpoints and an extension of implementation for one existing endpoint are proposedthe behavior of each.
As a note, all new methods that can be accessed on behalf of a user (i.e. with a session token or access token) are organized under /oauth2/audit. All client actions (that require client credentials) are organized under /oauth2/token.
Viewing applications that have OAuth access to a user’s account
Endpoint: GET /oauth2/audit/grantedClients/
Request body: none
Return body: PaginatedList<OAuthClientAuthorization>
Returns a paginated list of the clients and permissions that the user has granted. Allows a user to audit which parties have access to their resources.
Viewing tokens for an application that has OAuth access to a user’s account
Endpoint: GET /oauth2/audit/grantedClients/:client_id/tokens
Path Parameter: client_id: returned tokens will be associated with this OAuth2 client
Request body: none
Return body: PaginatedList<OAuthRefreshTokenInformation>
Returns a paginated list of the clients and permissions that the user has granted. Allows a user to audit which parties have access to their resources.
User revocation of a client’s access
Endpoint: POST /oauth2/audit/grantedClients/:client_id/revoke
Path Parameter: client_id: the OAuth2 client that will no longer have access to the user’s resources and/or identity
Response: On successful revocation, return HTTP 200. No body.
Upon calling this method, the refresh token and access tokens held by the specified client for the authenticated user making the API call will be revoked.
Update metadata for a token
Endpoint: PUT /oauth2/grantedClientsaudit/:client_id/tokens/:token_id/metadata
Request Parameters:
client_id: the OAuth2 client that is associated with the tokentoken_id: the token to update
...
In practice, only the token name can be updated.
User revocation of a particular
...
token
Endpoint: POST /oauth2/grantedClients/:client_idaudit/tokens/:token_id/revoke
Request Parameters:
...
Endpoint: POST /oauth2/revoke
Request Body: OAuthTokenRevocationRequest
Response: By RFC 7009 § 2.2, on successful revocation, HTTP 200. No body.
Upon calling this method, the refresh/access token and associated tokens held by this client and associated with the user are revoked. Note: a specific path for this endpoint is not named by OAuth 2.0/OIDC specifications.
...
Retrieval of token metadata
Endpoint (users): GET /oauth2/audit/tokens/:token_id/metadata
Endpoint (clients): GET /oauth2/token/:token_id/metadata
Request Parameter: token_id - the ID of the token to gather metadata about
Response: OAuthRefreshTokenInformation
The client can call this endpoint to get token metadata name. This metadata can be displayed to the user so that they may more easily identify the token in use when auditing/revoking tokens.
...