alex
df8d1adf15
- Replace all AdventureLog references with Voyage across ~102 files (7 case variants: AdventureLog, adventurelog, Adventurelog, ADVENTURELOG, AdventUrelog, AdventureLOG, adventure-log, adventure_log) - Rename brand, static, and documentation assets to use voyage naming - Rename install_adventurelog.sh → install_voyage.sh - Update README.md and voyage_overview.md to credit AdventureLog as the upstream project and Sean Morley as its original creator
144 lines
4.1 KiB
Markdown
144 lines
4.1 KiB
Markdown
# Pocket ID OIDC Authentication
|
||
|
||
<img src="https://pocket-id.org/logo.png" alt="Pocket ID Logo" width="400" />
|
||
|
||
Pocket ID is a lightweight, self-hosted OpenID Connect (OIDC) identity provider. Voyage can be configured to use Pocket ID for social authentication using its built-in OpenID Connect support.
|
||
|
||
Once Pocket ID is configured by an administrator, users can sign in to Voyage using their Pocket ID account and optionally link it to an existing Voyage account.
|
||
|
||
---
|
||
|
||
# Configuration
|
||
|
||
To enable Pocket ID as an identity provider, both Pocket ID and Voyage must be configured correctly. The most important (and least obvious) part of this setup is the **callback URL**, which must match Voyage’s internal OIDC routing.
|
||
|
||
---
|
||
|
||
## Pocket ID Configuration
|
||
|
||
1. Log in to your Pocket ID admin interface.
|
||
|
||
2. Navigate to **Clients** and create a new client.
|
||
|
||
3. Name the client something like `Voyage`.
|
||
|
||
4. Set the **Redirect / Callback URL** to:
|
||
|
||
```
|
||
https://<voyage-backend.example.com>/accounts/oidc/<CLIENT_ID>/login/callback/
|
||
```
|
||
|
||
- Replace `<voyage-backend.example.com>` with the **backend** URL of your Voyage instance.
|
||
- Replace `<CLIENT_ID>` with the **Pocket ID client ID** exactly as generated.
|
||
- This path is required and currently not auto-documented by Pocket ID or Voyage.
|
||
|
||
5. Ensure the client type is **Confidential**.
|
||
|
||
6. Copy the generated **Client ID** and **Client Secret** — you will need both for Voyage.
|
||
|
||
---
|
||
|
||
## Voyage Configuration
|
||
|
||
This configuration is done in the [Admin Panel](../../guides/admin_panel.md). You can launch it from the `Settings` page or navigate directly to `/admin` on your Voyage server.
|
||
|
||
1. Log in to Voyage as an administrator.
|
||
2. Navigate to **Settings** → **Administration Settings** and launch the admin panel.
|
||
3. Go to **Social Accounts**.
|
||
4. Under **Social applications**, click **Add**.
|
||
5. Fill in the fields as follows:
|
||
|
||
### Social Application Settings
|
||
|
||
- **Provider**: `OpenID Connect`
|
||
- **Provider ID**: Pocket ID Client ID
|
||
- **Name**: `Pocket ID`
|
||
- **Client ID**: Pocket ID Client ID
|
||
- **Secret Key**: Pocket ID Client Secret
|
||
- **Key**: _(leave blank)_
|
||
- **Settings**:
|
||
|
||
```json
|
||
{
|
||
"server_url": "https://<pocketid-url>/.well-known/openid-configuration"
|
||
}
|
||
```
|
||
|
||
- Replace `<pocketid-url>` with the base URL of your Pocket ID instance.
|
||
|
||
::: warning
|
||
Do **not** use `localhost` unless Pocket ID is running on the same machine and is resolvable from inside the Voyage container or service. Use a domain name or LAN IP instead.
|
||
:::
|
||
|
||
- **Sites**: Move the sites you want Pocket ID enabled on (usually `example.com` and `www.example.com`).
|
||
|
||
6. Save the configuration.
|
||
|
||
Ensure Pocket ID is running and reachable by Voyage.
|
||
|
||
---
|
||
|
||
## What It Should Look Like
|
||
|
||
Once configured correctly:
|
||
|
||
- Pocket ID appears as a login option on the Voyage login screen.
|
||
- Logging in redirects to Pocket ID, then back to Voyage without errors.
|
||
|
||
---
|
||
|
||
## Linking to an Existing Account
|
||
|
||
If a user already has an Voyage account:
|
||
|
||
1. Log in to Voyage normally.
|
||
2. Go to **Settings**.
|
||
3. Click **Launch Account Connections**.
|
||
4. Choose **Pocket ID** to link the identity to the existing account.
|
||
|
||
This allows future logins using Pocket ID without creating a duplicate account.
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
### 404 Error After Login
|
||
|
||
Ensure that:
|
||
|
||
- `/accounts` routes are handled by the **backend**, not the frontend.
|
||
- Your reverse proxy (Nginx, Traefik, Caddy, etc.) forwards `/accounts/*` correctly.
|
||
|
||
---
|
||
|
||
### Invalid Redirect URI
|
||
|
||
- Double-check that the callback URL in Pocket ID exactly matches:
|
||
|
||
```
|
||
/accounts/oidc/<CLIENT_ID>/login/callback/
|
||
```
|
||
|
||
- The `<CLIENT_ID>` must match the value used in the Voyage social application.
|
||
|
||
---
|
||
|
||
### Cannot Reach Pocket ID
|
||
|
||
- Verify that the `.well-known/openid-configuration` endpoint is accessible from the Voyage server.
|
||
- Test by opening:
|
||
|
||
```
|
||
https://<pocketid-url>/.well-known/openid-configuration
|
||
```
|
||
|
||
in a browser.
|
||
|
||
---
|
||
|
||
## Notes
|
||
|
||
- Pocket ID configuration is very similar to Authentik.
|
||
- The main difference is the **explicit callback URL requirement** and the use of the `.well-known/openid-configuration` endpoint as the `server_url`.
|
||
- This setup works with Docker, Docker Compose, and bare-metal deployments as long as networking i
|