From 35fe26fc15ee11a7332486af9df73ebdbc43966f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 3 May 2026 19:23:04 +0000 Subject: [PATCH 1/4] feat: add Pocket ID + Appwrite OIDC passkey authentication blog post Agent-Logs-Url: https://github.com/appwrite/website/sessions/a68657a8-5f20-4a9f-8e7c-4875086ab04a Co-authored-by: Meldiron <19310830+Meldiron@users.noreply.github.com> --- .../pocket-id-appwrite-oidc/+page.markdoc | 248 ++++++++++++++++++ 1 file changed, 248 insertions(+) create mode 100644 src/routes/blog/post/pocket-id-appwrite-oidc/+page.markdoc diff --git a/src/routes/blog/post/pocket-id-appwrite-oidc/+page.markdoc b/src/routes/blog/post/pocket-id-appwrite-oidc/+page.markdoc new file mode 100644 index 00000000000..5980e6aa4f7 --- /dev/null +++ b/src/routes/blog/post/pocket-id-appwrite-oidc/+page.markdoc @@ -0,0 +1,248 @@ +--- +layout: post +title: Add passkey authentication to your app with Pocket ID and Appwrite OIDC +description: Learn how to integrate Pocket ID, a self-hosted passkey authentication server, with Appwrite using the universal OIDC adapter. +date: 2025-05-03 +cover: /images/blog/pocket-id-appwrite-oidc/cover.png +timeToRead: 10 +author: matej-baco +category: tutorial +--- + +Authentication is one of the most critical parts of any application. Get it wrong, and you risk exposing user data. Get it right, and users feel safe and trust your product. Appwrite provides a full suite of backend services — databases, storage, functions, messaging, and more — but authentication is where many projects have unique and sensitive requirements. + +While Appwrite supports email/password, magic links, phone OTPs, and over 30 OAuth2 providers out of the box, some projects demand even more control. That's where the universal **OIDC adapter** comes in. If your identity provider speaks [OpenID Connect](https://openid.net/connect/), Appwrite can connect to it — no matter who built it or where it runs. + +Today, we'll integrate Appwrite with [Pocket ID](https://pocket-id.org/), a lightweight, self-hosted authentication server built around **passkeys**. Passkeys replace traditional passwords with cryptographic credentials tied to your device (a fingerprint, face ID, or hardware key). They're phishing-resistant, simpler to use, and increasingly considered the gold standard for modern authentication. Pocket ID ([GitHub](https://github.com/pocket-id/pocket-id)) makes it trivially easy to run your own passkey auth server and expose it as an OIDC provider — which means Appwrite can use it as a first-class login option. + +By the end of this tutorial, you'll have: + +- A self-hosted Pocket ID instance running on Railway +- Appwrite connected to it via the OIDC adapter +- A small Astro web app where users can sign in with a passkey + +# Prepare your Appwrite project + +Head to [Appwrite Cloud](https://cloud.appwrite.io/) and sign in (or create a free account if you haven't already). Create a new project, or open an existing one. + +In the left sidebar, click **Auth**, then switch to the **Settings** tab. Scroll down to the OAuth2 providers list and click **OIDC** to open the configuration modal. + +Leave this modal open — you'll need to paste a few values into it shortly. But first, copy the **Redirect URI** shown at the bottom of the modal. You'll need it when registering your app inside Pocket ID. + +# Set up Pocket ID + +Pocket ID supports [several installation methods](https://pocket-id.org/docs/setup/installation), including Docker Compose and bare-metal setups. For this tutorial, we'll take the fastest route: a one-click Railway template. + +> We prepared a simple Railway template to get you started quickly. Alternatively, follow the [official Pocket ID installation docs](https://pocket-id.org/docs/setup/installation) for other deployment options. + +## Deploy Pocket ID on Railway + +1. **Sign up** for a free account at [Railway](https://railway.com/). +2. Click **[Deploy on Railway](https://railway.com/deploy/u-A3IE)** to open the Pocket ID template. *(Referral link: [railway.com/deploy/u-A3IE?referralCode=Y3OU6o](https://railway.com/deploy/u-A3IE?referralCode=Y3OU6o))* +3. Click **Configure** and enter a random value for `ENCRYPTION_KEY`. You can generate one by running the following command in your terminal: + +```bash +openssl rand -hex 16 +``` + +> **Note:** `ENCRYPTION_KEY` must be at least 16 bytes (32 hex characters) long. + +4. Click **Save Config**, then **Deploy**. +5. Wait for the deployment to finish (it should turn green and show an **Active** status), then open the URL assigned by Railway — something like `https://pocket-id-production-4c96.up.railway.app/`. + +## Configure Pocket ID as an OIDC provider + +With Pocket ID running, complete the one-time admin setup: + +1. Visit your Pocket ID URL and navigate to `/setup` (e.g., `https://pocket-id-production-4c96.up.railway.app/setup`). +2. Register your **admin account** by entering a username and email. +3. Add a **passkey** to your admin account immediately — this is how you'll log back in. Follow the browser prompt to register your device's biometric or hardware key. +4. In the side menu, under the **Administration** section, click **OIDC Clients**. +5. Click **Add OIDC Client** and fill in the form: + - **Name**: Use the same name as your Appwrite project for clarity. + - **Callback URLs**: Paste the Redirect URI you copied from the Appwrite OIDC modal. + - Leave the remaining fields at their defaults, or customize the logo, theme, and re-authentication behavior as you like. +6. Click **Save** and then open the newly created client. You may need to click **Show more details** to see the full credentials table. Copy the following three values: + - **Client ID** (e.g., `4509e422-3797-40aa-9806-7f66e46d9712`) + - **Client Secret** (e.g., `kSWAJet5oUhjlRdXBjujcBzQT5kQpx4k`) + - **OIDC Discovery URL** (e.g., `https://pocket-id-production-8cb7.up.railway.app/.well-known/openid-configuration`) +7. **Recommended:** Scroll down to **Allowed User Groups**, expand the card, and click **Unrestrict**. Group restrictions are only useful when you share one Pocket ID instance across multiple tenants — for a single project, unrestricting keeps things simple. + +## Connect Pocket ID to Appwrite + +Return to the Appwrite Console and open the OIDC provider modal (**Project → Auth → Settings → OIDC**). Fill in the fields: + +1. **Enable** the OIDC toggle. +2. **Client ID**: paste the Client ID from Pocket ID. +3. **Well-known URL**: paste the OIDC Discovery URL from Pocket ID. +4. **Client Secret**: paste the Client Secret from Pocket ID. +5. Click **Update** to save. + +OIDC should now appear as **Enabled** and show at the top of your OAuth2 provider list in the Appwrite Console. + +# Build a demo web app + +Now let's wire everything together in a small frontend. We'll use [Astro](https://astro.build) because it's minimal and ships zero JavaScript by default — making it easy to reason about what's actually happening. The full source code is available at [github.com/Meldiron/pocket-id-demo](https://github.com/Meldiron/pocket-id-demo). + +## Create an Astro project + +```bash +npm create astro@latest +``` + +When prompted: + +- **Directory**: `./pocket-id-demo` +- **Template**: Minimal (empty) +- **Install dependencies**: Yes +- **Initialize a Git repository**: Yes + +Then enter the directory and install the Appwrite Web SDK: + +```bash +cd ./pocket-id-demo +npm install appwrite +``` + +Start the development server: + +```bash +npm run dev +``` + +## Build the sign-in page + +Open `src/pages/index.astro`. We'll add [Launch CSS](https://get.foundation/sites/docs/) for minimal, readable styling — add the following `` inside the ``: + +```html + +``` + +Now replace the contents of `` with a simple layout and a sign-in button: + +```html +
+ +
+
+
+ +
+
+``` + +Finally, add the Appwrite SDK script just before the closing `` tag. Replace `` and `` with the values from your Appwrite project's API keys page: + +```html + +``` + +When a user clicks **Sign in with Pocket ID**, they'll be redirected to your Pocket ID instance to authenticate with their passkey. After a successful login, Pocket ID redirects back to Appwrite, which creates a session and forwards the user to `/dashboard`. + +## Build the dashboard page + +Create a new file at `src/pages/dashboard.astro`. Copy the same layout from `index.astro`, replacing the `