commit db82d31a94b933c69d72de3c1bc9c1c2722c6d45
parent 0e8110c607c9ff5c66dfab0d629a43d899b42b3a
Author: Florian Dold <florian@dold.me>
Date: Thu, 14 Sep 2023 19:32:00 +0200
simplify DD49
Diffstat:
1 file changed, 28 insertions(+), 41 deletions(-)
diff --git a/design-documents/049-auth.rst b/design-documents/049-auth.rst
@@ -39,7 +39,7 @@ other forms of authentication, typically HTTP Basic auth.
Token Endpoint
--------------
-.. http:post:: /${RESOURCE...}/auth-token
+.. http:post:: /${RESOURCE...}/token
**Request Body**
@@ -54,14 +54,11 @@ Token Endpoint
// on the token validity duration
duration?: RelativeTime;
- // - "session": Token with short expiration.
- // When one session token is revoked,
- // other session tokens might be revoked
- // as well.
- // - "durable": Token with longer allowed expiration.
- // Durable tokens are explicitly and individually revoked.
- // Defaults to "session" when the server supports session tokens.
- kind?: "session" | "durable";
+ // Is the token refreshable into a new token during its
+ // validity?
+ // Refreshable tokens effectively provide indefinite
+ // access if they are refreshed in time.
+ refreshable?: boolean;
}
**Response:**
@@ -92,26 +89,38 @@ Token Revocation
Clients using session tokens log by forgetting the session token.
-.. http:post:: /${SERVICE}/auth-revoke-sessions
+.. http:post:: /${SERVICE}/logout
- Revoke all session tokens.
+ Invalidate the access token that is being used to make the request.
**Authentication:** The client must authenticate
with a valid access token.
-.. http:post:: /${SERVICE}/auth-revoke-tokens
- Revoke all access tokens (durable and session tokens).
+Performance Considerations
+--------------------------
- **Authentication:** The client must authenticate
- with a valid access token.
+.. note::
+
+ This section is purely informal and discusses
+ possible future extensions to improve performance.
+
+For performance reasons, OAuth 2.0 uses two types of tokens: Short-lived access
+tokens and long-lived refresh tokens. The access tokens can be implemented via
+signatures and the long-lived refresh tokens via server-stored tokens. This
+allows to cheaply validate access tokens, while still allowing longer expiration times
+for refresh tokens.
+We could do something similar by introducing login and session tokens. A login
+token is a server-stored token. In addition to being used directly as an
+access token, a login token can also be converted to a short-lived session
+token.
-Implementation Considerations
------------------------------
+Unlike durable access tokens, the short-lived session tokens can be
+implemented with signatures and don't need to be stored server-side.
-Session Tokens
-^^^^^^^^^^^^^^
+Extension: Session Tokens
+^^^^^^^^^^^^^^^^^^^^^^^^^
Session access tokens should be implemented as "self-encoded tokens", i.e.
as tokens signed by the server without requiring server-side token storage.
@@ -124,28 +133,6 @@ revocation and only accept tokens with a ``creation_timestamp`` larger than the
last revocation timestamp. Individual session tokens cannot be revoked, only
all issued session tokens can be revoked at once.
-Session tokens *may* also be implemented as server-stored tokens instead.
-
-Durable Tokens
-^^^^^^^^^^^^^^
-
-Durable tokens should be stored in a server-side database.
-
-
-Performance Considerations
---------------------------
-
-For performance reasons, OAuth 2.0 uses two types of tokens: Short-lived access
-tokens and long-lived refresh tokens. The access tokens can be implemented via
-signatures and the long-lived refresh tokens via server-stored tokens. This
-allows to cheaply validate access tokens, while still allowing longer expiration times
-for refresh tokens.
-
-We could do something similar by introducing ``kind=login`` tokens. A login
-token is a server-stored token. In addition to being used directly as an
-access token, a login token can also be converted to a short-lived session
-token.
-
Definition of Done
==================
