feat: pocket id guide (#13)

Author: steveiliop56

.vitepress/config.mts

@@ -34,23 +34,27 @@ export default withMermaid(
         {
           text: "Guides",
           items: [
-            { text: "Github OAuth", link: "/docs/guides/github-oauth" },
-            { text: "Google OAuth", link: "/docs/guides/google-oauth" },
-            { text: "Github App OAuth", link: "/docs/guides/github-app-oauth" },
             {
               text: "Using the binary",
               link: "/docs/guides/using-the-binary",
             },
-            { text: "Access controls", link: "/docs/guides/access-controls" },
             {
               text: "Two factor authentication",
               link: "/docs/guides/totp",
             },
+            { text: "Access controls", link: "/docs/guides/access-controls" },
+            { text: "Google OAuth", link: "/docs/guides/google-oauth" },
+            { text: "Github OAuth", link: "/docs/guides/github-oauth" },
+            { text: "Github App OAuth", link: "/docs/guides/github-app-oauth" },
             { text: "Tinyauth with Runtipi", link: "/docs/guides/runtipi" },
+            {
+              text: "Tinyauth with Pocket ID",
+              link: "/docs/guides/pocket-id",
+            },
             {
               text: "Tinyauth with Nginx Proxy Manager",
               link: "/docs/guides/nginx-proxy-manager",
-            },
+            }
           ],
         },
         {

docs/guides/github-app-oauth.md

@@ -61,7 +61,7 @@ tinyauth:
 ```
 
 ::: warning
-OAuth doesn't mean security, with the current setup everybody with a Github account can login to Tinyauth as a normal user. If you would like to limit which users can login with OAuth, you can add the `OAUTH_WHITELIST` environment variable and only allow your email address to login. For more information check the [configuration](/docs/reference/configuration.md) page.
+OAuth doesn't mean security, with the current setup everybody with a Github account can login to tinyauth as a normal user. If you would like to limit which users can login with OAuth, you can add the `OAUTH_WHITELIST` environment variable and only allow your email address to login. For more information check the [configuration](/docs/reference/configuration.md) page.
 :::
 
 ::: tip

docs/guides/github-oauth.md

@@ -57,7 +57,7 @@ tinyauth:
 ```
 
 ::: warning
-OAuth doesn't mean security, with the current setup everybody with a Github account can login to Tinyauth as a normal user. If you would like to limit which users can login with OAuth, you can add the `OAUTH_WHITELIST` environment variable and only allow your email address to login. For more information check the [configuration](/docs/reference/configuration.md) page.
+OAuth doesn't mean security, with the current setup everybody with a Github account can login to tinyauth as a normal user. If you would like to limit which users can login with OAuth, you can add the `OAUTH_WHITELIST` environment variable and only allow your email address to login. For more information check the [configuration](/docs/reference/configuration.md) page.
 :::
 
 ::: tip

docs/guides/google-oauth.md

@@ -77,7 +77,7 @@ tinyauth:
 ```
 
 ::: warning
-OAuth doesn't mean security, with the current setup everybody with a Github account can login to Tinyauth as a normal user. If you would like to limit which users can login with OAuth, you can add the `OAUTH_WHITELIST` environment variable and only allow your email address to login. For more information check the [configuration](/docs/reference/configuration.md) page.
+OAuth doesn't mean security, with the current setup everybody with a Github account can login to tinyauth as a normal user. If you would like to limit which users can login with OAuth, you can add the `OAUTH_WHITELIST` environment variable and only allow your email address to login. For more information check the [configuration](/docs/reference/configuration.md) page.
 :::
 
 ::: tip

docs/guides/pocket-id.md

@@ -0,0 +1,98 @@
+# Tinyauth with Pocket ID
+
+[Pocket ID](https://pocket-id.org) is a really popular OIDC server that allows you to login to your apps with passkeys. Most proxies do not support OIDC/OAuth servers for authentication meaning that Pocket ID cannot be connected with them. With tinyauth you can connect Pocket ID to your favorite proxy and use it to secure your apps.
+
+## Requirements
+
+This guide assumes you have a working Pocket ID installation. If you don't already have one you can checkout [Pocket ID's documentation](https://pocket-id.org/docs/setup/installation) on how to install it.
+
+## Configuring Pocket ID
+
+To begin with you should visit Pocket ID's admin dashboard which should look like this:
+
+![Pocket ID Admin Page](/screenshots/pocket-id-home.png)
+
+There you should go to the _OIDC Clients_ tab and click _Add OIDC Client_. A new menu will appear prompting you to provide some information. We only need to set two of these fields.
+
+**Name** -> Give your client a name. You can use `Tinyauth`
+
+**Callback URLs** -> Here, you will need to fill in your tinyauth app URL followed by `/api/oauth/callback/generic`. For example `https://tinyauth.example.com/api/oauth/callback/generic`.
+
+![Pocket ID Create Client](/screenshots/pocket-id-new-client.png)
+
+You can also upload a logo for your OIDC client. You can download the tinyauth logo from [Github](https://github.com/steveiliop56/tinyauth/blob/main/frontend/public/logo.png).
+
+Finally click _Save_. A new page should be appear containing your OIDC credentials:
+
+![Pocket ID Client Page](/screenshots/pocket-id-client-page.png)
+
+Make sure to note down your client ID and secret as we will need them later.
+
+## Configuring Tinyauth
+
+In order for Pocket ID to work with tinyauth we will need to use the generic provider. An example configuration will look like:
+
+```yaml
+tinyauth:
+  image: ghcr.io/steveiliop56/tinyauth:v3
+  container_name: tinyauth
+  restart: unless-stopped
+  environment:
+    - SECRET=some-random-32-chars-string
+    - APP_URL=https://tinyauth.example.com
+    - GENERIC_CLIENT_ID=your-pocket-id-client-id
+    - GENERIC_CLIENT_SECRET=your-pocket-id-client-secret
+    - GENERIC_AUTH_URL=https://pocket-id.example.com/authorize
+    - GENERIC_TOKEN_URL=https://pocket-id.example.com/api/oidc/token
+    - GENERIC_USER_URL=https://pocket-id.example.com/api/oidc/userinfo
+    - GENERIC_SCOPES=openid email profile groups
+    - GENERIC_NAME=Pocket ID
+  labels:
+    traefik.enable: true
+    traefik.http.routers.tinyauth.rule: Host(`tinyauth.example.com`)
+    traefik.http.middlewares.tinyauth.forwardauth.address: http://tinyauth:3000/api/auth/traefik
+```
+
+::: tip
+You can set the `OAUTH_AUTO_REDIRECT` environment variable to `generic` so every time you try to access a tinyauth app you will be automatically redirected to Pocket ID.
+:::
+
+::: warning
+OAuth doesn't mean security, with the current setup everybody with a Pocket ID account can login to tinyauth as a normal user. If you would like to limit which users can login with OAuth, you can add the `OAUTH_WHITELIST` environment variable and only allow your email address to login. For more information check the [configuration](/docs/reference/configuration.md) page.
+:::
+
+And you are done! After you restart tinyauth and try to login to an app, you should have an additional option to login with Pocket ID.
+
+## Access controls with Pocket ID groups
+
+Pocket ID has support for user groups, this can be useful for managing your access controls entirely through Pocket ID and not through whitelists on tinyauth. To use groups you will firstly need to create one. To do so firstly go to the _User Groups_ tab and click _Add Group_. There you should give it a name and click _Save_.
+
+![Pocket ID New Group](/screenshots/pocket-id-new-group.png)
+
+After you create your group, you will be prompted to select the users included in it. You can select as many users as you like.
+
+![Pocket ID Group Home](/screenshots/pocket-id-group-home.png)
+
+Finally you will need to configure the tinyauth protected apps to require OAuth groups. This can be configured with a simple label:
+
+```yaml
+whoami:
+  container_name: whoami
+  image: traefik/whoami:latest
+  restart: unless-stopped
+  labels:
+    traefik.enable: true
+    traefik.http.routers.nginx.rule: Host(`whoami.example.com`)
+    traefik.http.routers.nginx.middlewares: tinyauth
+    tinyauth.oauth.groups: admins # <-- Added line
+```
+
+In this example, only the Pocket ID users within the `admins` group will be able to access the app. Users not included in the group will be redirected to an unauthorized page.
+
+::: warning
+In order for the access controls to work the app must have the same container name as the subdomain it is exposed at, e.g. container name should be `hello` and the app should be exposed at `hello.example.com`. Using a different subdomain will **_not_** work.
+:::
+
+::: info
+The OAuth and user whitelist can be a regular regex expression if it has the slash (`/`) prefix and suffix.
+:::