mirror of
https://github.com/vrtmrz/obsidian-livesync.git
synced 2025-12-12 17:25:56 +00:00
82 lines
5.5 KiB
Markdown
82 lines
5.5 KiB
Markdown
---
|
|
title: "JWT Authentication on CouchDB"
|
|
livesync-version: 0.25.24
|
|
tags:
|
|
- tips
|
|
- CouchDB
|
|
- JWT
|
|
authors:
|
|
- vorotamoroz
|
|
---
|
|
|
|
# JWT Authentication on CouchDB
|
|
|
|
When using CouchDB as a backend for Self-hosted LiveSync, it is possible to enhance security by employing JWT (JSON Web Token) Authentication. In particular, using asymmetric keys (ES256 and ES512) provides greater security against token interception.
|
|
|
|
## Setting up JWT Authentication (Asymmetrical Key Example)
|
|
|
|
### 1. Generate a key pair
|
|
|
|
We can use `openssl` to generate an EC key pair as follows:
|
|
|
|
```bash
|
|
# Generate private key
|
|
# ES512 for secp521r1 curve, we can also use ES256 for prime256v1 curve
|
|
openssl ecparam -name secp521r1 -genkey -noout | openssl pkcs8 -topk8 -inform PEM -nocrypt -out private_key.pem
|
|
# openssl ecparam -name prime256v1 -genkey -noout | openssl pkcs8 -topk8 -inform PEM -nocrypt -out private_key.pem
|
|
# Generate public key in SPKI format
|
|
openssl ec -in private_key.pem -pubout -outform PEM -out public_key.pem
|
|
```
|
|
|
|
> [!TIP]
|
|
> A key generator will be provided again in a future version of the user interface.
|
|
|
|
### 2. Configure CouchDB to accept JWT tokens
|
|
|
|
The following configuration is required:
|
|
|
|
| Key | Value | Note |
|
|
| ------------------------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| chttpd/authentication_handlers | {chttpd_auth, jwt_authentication_handler} | In total, it may be `{chttpd_auth, jwt_authentication_handler}, {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, default_authentication_handler}`, or something similar. |
|
|
| jwt_auth/required_claims | "exp" | |
|
|
| jwt_keys/ec:your_key_id | Your public key in PEM (SPKI) format | Replace `your_key_id` with your actual key ID. You can decide as you like. Note that you can add multiple keys if needed. If you want to use HSxxx, you should set `jwt_keys/hmac:your_key_id` with your HMAC secret. |
|
|
|
|
|
|
Note: When configuring CouchDB via web interface (Fauxton), new-lines on the public key should be replaced with `\n` for header and footer lines (So wired, but true I have tested). as follows:
|
|
```
|
|
-----BEGIN PUBLIC KEY-----
|
|
\nMIGbMBAGByqGSM49AgEGBSuBBAAjA4GGAAQBq0irb/+K0Qzo7ayIHj0Xtthcntjz
|
|
r665J5UYdEQMiTtku5rnp95RuN97uA2pPOJOacMBAoiVUnZ1pqEBz9xH9yoAixji
|
|
Ju...........................................................gTt
|
|
/xtqrJRwrEy986oRZRQ=
|
|
\n-----END PUBLIC KEY-----
|
|
```
|
|
|
|
For detailed information, please refer to the [CouchDB JWT Authentication Documentation](https://docs.couchdb.org/en/stable/api/server/authn.html#jwt-authentication).
|
|
|
|
### 3. Configure Self-hosted LiveSync to use JWT Authentication
|
|
|
|
| Setting | Description |
|
|
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| Use JWT Authentication | Enable this option to use JWT Authentication. |
|
|
| JWT Algorithm | Select the JWT signing algorithm (e.g., ES256, ES512) that matches your key pair. |
|
|
| JWT Key | Paste your private key in PEM (pkcs8) format. |
|
|
| JWT Expiration Duration | Set the token expiration time in minutes. Locally cached tokens are also invalidated after this duration. |
|
|
| JWT Key ID (kid) | Enter the key ID that you used when configuring CouchDB, i.e., the one that replaced `your_key_id`. |
|
|
| JWT Subject (sub) | Set your user ID; this overrides the original `Username` setting. If you have detected access with `Username`, you have failed to authorise with JWT. |
|
|
|
|
> [!IMPORTANT]
|
|
> Self-hosted LiveSync requests to CouchDB treat the user as `_admin`. If you want to restrict access, configure `jwt_auth/roles_claim_name` to a custom claim name. (Self-hosted LiveSync always sets `_couchdb.roles` with the value `["_admin"]`).
|
|
|
|
### 4. Test the configuration
|
|
|
|
Just try to `Test Settings and Continue` in the remote setup dialogue. If you have successfully authenticated, you are all set.
|
|
|
|
## Additional Notes
|
|
|
|
This feature is still experimental. Please ensure to test thoroughly in your environment before deploying to production.
|
|
|
|
However, we think that this is a great step towards enhancing security when using CouchDB with Self-hosted LiveSync. We shall enable this setting by default in future releases.
|
|
|
|
We would love to hear your feedback and any issues you encounter.
|