From 6e3728ddc86cce95b2041513564b087463f5b2d3 Mon Sep 17 00:00:00 2001 From: Elias Schneider Date: Wed, 15 Jan 2025 14:05:44 +0100 Subject: [PATCH] docs: add guide to setup Pocket ID with Caddy --- README.md | 6 +-- docs/proxy-services.md | 103 +++++++++++++++++++++++++++++++++++++++-- 2 files changed, 103 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 6eed3d0..f59ead5 100644 --- a/README.md +++ b/README.md @@ -22,8 +22,8 @@ Additionally, what makes Pocket ID special is that it only supports [passkey](ht - [Nginx Reverse Proxy](#nginx-reverse-proxy) - [Proxy Services with Pocket ID](#proxy-services-with-pocket-id) - [Update](#update) - - [Docker](#docker) - - [Stand-alone](#stand-alone) + - [Docker](#docker) + - [Stand-alone](#stand-alone) - [Environment variables](#environment-variables) - [Account recovery](#account-recovery) - [Contribute](#contribute) @@ -113,7 +113,7 @@ proxy_buffer_size 256k; ## Proxy Services with Pocket ID -As the goal of Pocket ID is to stay simple, it doesn't have a built-in proxy provider. However, you can use [OAuth2 Proxy](https://oauth2-proxy.github.io/oauth2-proxy) to add authentication to your services that don't support OIDC. +The goal of Pocket ID is to function exclusively as an OIDC provider. As such, we don't have a built-in proxy provider. However, you can use other tools that act as a middleware to protect your services and support OIDC as an authentication provider. See the [guide](docs/proxy-services.md) for more information. diff --git a/docs/proxy-services.md b/docs/proxy-services.md index cefce88..56af5d9 100644 --- a/docs/proxy-services.md +++ b/docs/proxy-services.md @@ -1,8 +1,105 @@ # Proxy Services through Pocket ID -The goal of Pocket ID is to stay simple. Because of that we don't have a built-in proxy provider. However, you can use [OAuth2 Proxy](https://oauth2-proxy.github.io/oauth2-proxy/) to add authentication to your services that don't support OIDC. This guide will show you how to set up OAuth2 Proxy with Pocket ID. +The goal of Pocket ID is to function exclusively as an OIDC provider. As such, we don't have a built-in proxy provider. However, you can use other tools that act as a middleware to protect your services and support OIDC as an authentication provider. -## Docker Setup +There are two ways to do this: + +- Implement OIDC into your reverse proxy +- Use [OAuth2 Proxy](https://oauth2-proxy.github.io/oauth2-proxy/) + +## Reverse Proxy + +Almost every reverse proxy somehow supports protecting your services with OIDC. Currently only Caddy is documented but you can search on Google for your reverse proxy and OIDC. + +We would really appreciate if you contribute to this documentation by adding your reverse proxy and how to configure it with Pocket ID. + +### Caddy + +With [caddy-security](https://github.com/greenpau/caddy-security) you can easily protect your services with Pocket ID. + +#### 1. Create a new OIDC client in Pocket ID. + +Create a new OIDC client in Pocket ID by navigating to `https:///settings/admin/oidc-clients`. Now enter `https:///auth/oauth2/generic/authorization-code-callback` as the callback URL. After adding the client, you will obtain the client ID and client secret, which you will need in the next step. + +#### 2. Install caddy-security + +Run the following command to install caddy-security: + +```bash +caddy add-package github.com/greenpau/caddy-security +``` + +#### 3. Create your Caddyfile + +```bash +{ + # Port to listen on + http_port 443 + + # Configure caddy-security. + order authenticate before respond + security { + oauth identity provider generic { + realm generic + driver generic + client_id client-id-from-pocket-id # Replace with your own client ID + client_secret client-secret-from-pocket-id # Replace with your own client secret + scopes openid email profile + base_auth_url http://localhost + metadata_url http://localhost/.well-known/openid-configuration + } + + authentication portal myportal { + crypto default token lifetime 3600 # Seconds until you have to re-authenticate + enable identity provider generic + cookie insecure off # Set to "on" if you're not using HTTPS + + transform user { + match realm generic + action add role user + } + } + + authorization policy mypolicy { + set auth url /auth/oauth2/generic + allow roles user + inject headers with claims + } + } +} + +https:// { + @auth { + path /auth/oauth2/generic + path /auth/oauth2/generic/authorization-code-callback + } + + route @auth { + authenticate with myportal + } + + route /* { + authorize with mypolicy + reverse_proxy http://: # Replace with your own service + } +} +``` + +For additional configuration options, refer to the official [caddy-security documentation](https://docs.authcrunch.com/docs/intro). + +#### 4. Start Caddy + +```bash +caddy run --config Caddyfile +``` + +#### 5. Access the service + +Your service should now be protected by Pocket ID. + +## OAuth2 Proxy + +### Docker Installation #### 1. Add OAuth2 proxy to the service that should be proxied. @@ -74,7 +171,7 @@ docker compose up -d You can now access the service through OAuth2 Proxy by visiting `http://localhost:4180`. -## Standalone Installation +### Standalone Installation Setting up OAuth2 Proxy with Pocket ID without Docker is similar to the Docker setup. As the setup depends on your environment, you have to adjust the steps accordingly but is should be similar to the Docker setup.