Add OAuth 2.0/2.1 documentation page

Author: ujibang

_includes/docs-sidebar.html

@@ -110,6 +110,7 @@ <h3 class="mt-2">Security</h3>
       <li><a href="/docs/security/user-management">User Management</a></li>
       <li><a href="/docs/security/permissions">Permissions</a></li>
       <li><a href="/docs/security/how-clients-authenticate">Client Authentication</a></li>
+      <li><a href="/docs/security/oauth">OAuth 2.0 / 2.1</a></li>
       <li><a href="/docs/security/tls">TLS Configuration</a></li>
       <li><a href="/docs/security/security-hardening">Security Hardening</a></li>
       <li><a href="/docs/security/secure-connection-to-mongodb">Secure MongoDB Connection</a></li>

docs/security/how-clients-authenticate.adoc

@@ -19,9 +19,7 @@ In this guide, you'll learn how to:
 
 . Authenticate using Basic Authentication with username and password
 . Understand how the Authorization header works
-. Use authentication tokens for subsequent requests (password and client_credentials grant types)
-. Auto-discover server metadata via the RFC 8414 discovery endpoint
-. Manage authentication tokens (retrieve and invalidate)
+. Obtain and use OAuth 2.0 access tokens
 . Check user credentials and roles
 . Avoid browser authentication popups
 
@@ -105,371 +103,18 @@ In other words:
 
 === Authentication Token
 
-==== Modern OAuth 2.0 Token Endpoint (Recommended)
+RESTHeart v9 provides a standards-compliant OAuth 2.0/2.1 token endpoint.
+See the link:/docs/security/oauth[OAuth 2.0 / 2.1] page for full documentation on:
 
-RESTHeart v9 introduces dedicated OAuth 2.0-compatible token endpoints for secure and standards-compliant authentication. This is the recommended approach for new applications.
-
-**Available Endpoints:**
-
-* `POST /token` - Returns JWT token in response body (supports `password` and `client_credentials` grant types)
-* `POST /token/cookie` - Sets JWT token as HttpOnly cookie (enhanced security for browser-based apps)
-* `GET /.well-known/oauth-authorization-server` - Returns server metadata for client auto-discovery (RFC 8414)
-
-**Benefits:**
-
-* 85% performance improvement over the legacy token injection approach
-* Standards-compliant OAuth 2.0 implementation
-* Reduced attack surface with dedicated endpoints
-* Centralized authentication audit trails
-* No overhead on every authenticated request
-
-===== Basic Authentication Method
-
-Send credentials using HTTP Basic Authentication:
-
-==== cURL
-[source,bash]
-----
-curl -i -X POST [RESTHEART-URL]/token \
-  -u [BASIC-AUTH]
-----
-
-==== HTTPie
-[source,bash]
-----
-http POST [RESTHEART-URL]/token \
-  Authorization:"Basic [BASIC-AUTH]"
-----
-
-==== JavaScript
-[source,javascript]
-----
-const username = 'your-username';
-const password = 'your-password';
-const credentials = btoa(`${username}:${password}`);
-
-fetch('[RESTHEART-URL]/token', {
-    method: 'POST',
-    headers: {
-        'Authorization': `Basic ${credentials}`
-    }
-})
-.then(response => response.json())
-.then(data => {
-    console.log('Access token:', data.access_token);
-    console.log('Expires in:', data.expires_in, 'seconds');
-    // Store the token for future requests
-    sessionStorage.setItem('auth_token', data.access_token);
-})
-.catch(error => console.error('Error:', error));
-----
-
-**Response:**
-
-[source,json]
-----
-{
-  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-  "token_type": "Bearer",
-  "expires_in": 900
-}
-----
-
-===== OAuth 2.0 Form Data Method (Resource Owner Password Credentials)
-
-Send credentials using OAuth 2.0 form data (application/x-www-form-urlencoded) with `grant_type=password` (RFC 6749 §4.3):
-
-==== cURL
-[source,bash]
-----
-curl -i -X POST [RESTHEART-URL]/token \
-  -H "Content-Type: application/x-www-form-urlencoded" \
-  -d "grant_type=password&username=admin&password=secret"
-----
-
-==== HTTPie
-[source,bash]
-----
-http -f POST [RESTHEART-URL]/token \
-  grant_type=password \
-  username=admin \
-  password=secret
-----
-
-==== JavaScript
-[source,javascript]
-----
-const formData = new URLSearchParams({
-    grant_type: 'password',
-    username: 'your-username',
-    password: 'your-password'
-});
-
-fetch('[RESTHEART-URL]/token', {
-    method: 'POST',
-    headers: {
-        'Content-Type': 'application/x-www-form-urlencoded'
-    },
-    body: formData
-})
-.then(response => response.json())
-.then(data => {
-    console.log('Access token:', data.access_token);
-    sessionStorage.setItem('auth_token', data.access_token);
-})
-.catch(error => console.error('Error:', error));
-----
-
-===== Client Credentials Grant
-
-NOTE: `client_credentials` grant type support is available from RESTHeart v9.2.0.
-
-For machine-to-machine or service-account authentication, use `grant_type=client_credentials` (RFC 6749 §4.4).
-Pass `client_id` and `client_secret` in the request body instead of `username` and `password`.
-This is the recommended approach for API gateways, CLI tools, and MCP clients.
-
-==== cURL
-[source,bash]
-----
-curl -i -X POST [RESTHEART-URL]/token \
-  -H "Content-Type: application/x-www-form-urlencoded" \
-  -d "grant_type=client_credentials&client_id=myapp&client_secret=s3cret"
-----
-
-==== HTTPie
-[source,bash]
-----
-http -f POST [RESTHEART-URL]/token \
-  grant_type=client_credentials \
-  client_id=myapp \
-  client_secret=s3cret
-----
-
-==== JavaScript
-[source,javascript]
-----
-const formData = new URLSearchParams({
-    grant_type: 'client_credentials',
-    client_id: 'your-client-id',
-    client_secret: 'your-client-secret'
-});
-
-fetch('[RESTHEART-URL]/token', {
-    method: 'POST',
-    headers: {
-        'Content-Type': 'application/x-www-form-urlencoded'
-    },
-    body: formData
-})
-.then(response => response.json())
-.then(data => {
-    console.log('Access token:', data.access_token);
-    console.log('Expires in:', data.expires_in, 'seconds');
-})
-.catch(error => console.error('Error:', error));
-----
-
-The response format is identical to the password grant:
-
-[source,json]
-----
-{
-  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-  "token_type": "Bearer",
-  "expires_in": 900,
-  "username": "myapp",
-  "roles": ["service"]
-}
-----
-
-NOTE: `client_id` and `client_secret` are mapped to the user credentials in the configured authenticator (e.g., `mongoRealmAuthenticator`). The client account must exist in the user store just like a regular user account.
-
-===== Using the Token
-
-Once you have the token, use it as a Bearer token in the Authorization header:
-
-==== cURL
-[source,bash]
-----
-curl -i -X GET [RESTHEART-URL]/mycollection \
-  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
-----
-
-==== HTTPie
-[source,bash]
-----
-http GET [RESTHEART-URL]/mycollection \
-  "Authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
-----
-
-==== JavaScript
-[source,javascript]
-----
-const token = sessionStorage.getItem('auth_token');
-
-fetch('[RESTHEART-URL]/mycollection', {
-    method: 'GET',
-    headers: {
-        'Authorization': `Bearer ${token}`
-    }
-})
-.then(response => response.json())
-.then(data => console.log('Data:', data))
-.catch(error => console.error('Error:', error));
-----
-
-===== Token Renewal
-
-To renew an authentication token before it expires, add the `?renew` query parameter to `GET /token` or `GET /token/cookie` requests:
-
-==== cURL
-[source,bash]
-----
-curl -i -X GET [RESTHEART-URL]/token?renew \
-  -u [BASIC-AUTH]
-----
-
-==== HTTPie
-[source,bash]
-----
-http GET [RESTHEART-URL]/token?renew \
-  Authorization:"Basic [BASIC-AUTH]"
-----
-
-==== JavaScript
-[source,javascript]
-----
-const username = 'your-username';
-const password = 'your-password';
-const credentials = btoa(`${username}:${password}`);
-
-fetch('[RESTHEART-URL]/token?renew', {
-    method: 'GET',
-    headers: {
-        'Authorization': `Basic ${credentials}`
-    }
-})
-.then(response => response.json())
-.then(data => {
-    console.log('New access token:', data.access_token);
-    sessionStorage.setItem('auth_token', data.access_token);
-})
-.catch(error => console.error('Error:', error));
-----
-
-NOTE: Generating a new token is a cryptographic operation and can have significant performance overhead. It is the responsibility of the client to renew the token using this query parameter when it is going to expire soon.
-
-===== Cookie-Based Authentication
-
-For browser-based applications, use the `/token/cookie` endpoint to set an HttpOnly cookie (more secure as the token isn't exposed to JavaScript):
-
-==== cURL
-[source,bash]
-----
-curl -i -X POST [RESTHEART-URL]/token/cookie \
-  -u [BASIC-AUTH] \
-  -c cookies.txt
-----
-
-==== HTTPie
-[source,bash]
-----
-http --session=./session.json POST [RESTHEART-URL]/token/cookie \
-  Authorization:"Basic [BASIC-AUTH]"
-----
-
-==== JavaScript
-[source,javascript]
-----
-const username = 'your-username';
-const password = 'your-password';
-const credentials = btoa(`${username}:${password}`);
-
-fetch('[RESTHEART-URL]/token/cookie', {
-    method: 'POST',
-    headers: {
-        'Authorization': `Basic ${credentials}`
-    },
-    credentials: 'include'  // Important: include cookies
-})
-.then(response => {
-    if (response.ok) {
-        console.log('Authenticated! Cookie set.');
-        // Subsequent requests will automatically include the cookie
-    }
-})
-.catch(error => console.error('Error:', error));
-
-// Subsequent requests automatically include the cookie
-fetch('[RESTHEART-URL]/mycollection', {
-    method: 'GET',
-    credentials: 'include'  // Important: include cookies
-})
-.then(response => response.json())
-.then(data => console.log('Data:', data))
-.catch(error => console.error('Error:', error));
-----
-
-**Configuration:**
-
-The JWT Token Manager is enabled by default in RESTHeart v9:
-
-[source,yml]
-----
-jwtTokenManager:
-    key: secret  # Change this in production!
-    enabled: true
-    ttl: 15  # Token time-to-live in minutes
-    srv-uri: /tokens
-    issuer: restheart.com
-----
-
-IMPORTANT: Always change the `key` value in production to a strong, random secret.
-
-===== OAuth 2.0 Authorization Server Metadata Discovery (RFC 8414)
-
-NOTE: The authorization server metadata discovery endpoint is available from RESTHeart v9.2.0.
-
-RESTHeart exposes a standards-compliant metadata discovery endpoint at `GET /.well-known/oauth-authorization-server` (RFC 8414).
-This allows OAuth 2.0 clients to auto-configure themselves without hardcoded URLs.
-
-==== cURL
-[source,bash]
-----
-curl -i [RESTHEART-URL]/.well-known/oauth-authorization-server
-----
-
-==== HTTPie
-[source,bash]
-----
-http GET [RESTHEART-URL]/.well-known/oauth-authorization-server
-----
-
-**Response:**
-
-[source,json]
-----
-{
-  "issuer": "http://localhost:8080",
-  "token_endpoint": "http://localhost:8080/token",
-  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"],
-  "grant_types_supported": ["password", "client_credentials"],
-  "response_types_supported": ["token"]
-}
-----
-
-The endpoint is publicly accessible (no authentication required) and the base URL is derived from the request `Host` header by default.
-You can override it with the `base-url` configuration option:
-
-[source,yml]
-----
-oauthAuthorizationServerMetadataService:
-  base-url: https://api.example.com  # optional, falls back to request Host header
-----
+* `POST /token` — password, client_credentials, and authorization_code grants
+* `POST /token/cookie` — HttpOnly cookie for browser applications
+* Authorization Code + PKCE flow (OAuth 2.1, RFC 7636)
+* Authorization Server Metadata discovery (RFC 8414)
+* Protected Resource Metadata (RFC 9728)
 
 ==== Legacy Token Management (Automatic Injection)
 
-NOTE: This is the legacy token management approach. For new applications, use the OAuth 2.0 `/token` endpoint described above.
+NOTE: This is the legacy token management approach. For new applications, use the link:/docs/security/oauth[OAuth 2.0 `/token` endpoint].
 
 RESTHeart can also automatically inject auth tokens into response headers. The default configuration includes the **tokenBasicAuthMechanism** and the **rndTokenManager**.