docs: changes for v5.1.0

.gitignore

@@ -19,3 +19,6 @@ pnpm-debug.log*
 
 # macOS-specific files
 .DS_Store
+
+# idea
+/.idea/

astro.config.mjs

@@ -116,6 +116,10 @@ export default defineConfig({
               label: "Runtipi",
               slug: "docs/guides/runtipi",
             },
+            {
+              label: "Tailscale",
+              slug: "docs/guides/tailscale",
+            },
             {
               label: "Using the Binary",
               slug: "docs/guides/using-the-binary",
@@ -134,6 +138,10 @@ export default defineConfig({
               label: "Zerobyte",
               slug: "docs/integrations/zerobyte",
             },
+            {
+              label: "Tailscale",
+              slug: "docs/integrations/tailscale",
+            },
             {
               label: "Immich",
               slug: "docs/integrations/immich",

src/content/docs/docs/about.mdx

@@ -15,7 +15,7 @@ Tinyauth was developed as a personal challenge to create a robust application an
 
 ## Suitable Use Cases
 
-Tinyauth is not intended for production environments. Its primary purpose is to add a login screen to applications in homelabs or to facilitate resource sharing with family and friends. For scenarios requiring advanced user management, Authentik is recommended.
+Tinyauth's main purpose is to add a login screen to applications in homelabs or to facilitate resource sharing with family and friends. It is not designed for production environments, which require features like RBAC and more granular permissions. For scenarios requiring advanced user management, Authentik is recommended.
 
 ## Future Direction
 

src/content/docs/docs/guides/access-controls.mdx

@@ -95,6 +95,37 @@ Tinyauth will now use the domain to match the configuration instead of the app I
 Labels are dynamic and can be updated at runtime, environment variables are not and require a restart of Tinyauth to take effect.
 :::
 
+## Access Control Policy
+
+Tinyauth supports both an allow-by-default and a deny-by-default approach in access controls. The policy can be defined
+using the `TINYAUTH_AUTH_ACLS_POLICY` environment variable or the `--auth.acls.policy` CLI flag. The configuration option
+supports either `deny` or `allow`. The default policy is `allow`.
+
+In both examples we have the following ACLs defined as Docker labels.
+
+```yaml
+tinyauth.apps.myapp.config.domain: myapp.example.com
+```
+
+**Allow-by-default example**
+
+In this example we have `TINYAUTH_AUTH_ACLS_POLICY=allow`.
+
+With this config, every user you define in Tinyauth will be allowed unless you set up
+a user allow or block list.
+
+**Deny-by-default example**
+
+In this example we have `TINYAUTH_AUTH_ACLS_POLICY=deny`.
+
+With this config, every user you define in Tinyauth will be denied access to the app
+unless you manually allow them with a whitelist.
+
+:::caution
+Due to the setup-specific nature of the IP and OAuth Group access controls, they are excluded
+from the deny-by-default policy and are only applied if you manually specify a blocklist.
+:::
+
 ## User ACLs
 
 *Going forward, the guide will use the labels format but everything mentioned also applies to environment variables.*

src/content/docs/docs/guides/advanced.mdx

@@ -5,6 +5,19 @@ description: Guides and tips for advanced setups.
 
 Below, you can find some guides for advanced setups.
 
+## Tinyauth API
+
+Tinyauth exposes its API under `/api`. Documentation for the API is not available so you will have to consult
+the controller [sources](https://github.com/tinyauthapp/tinyauth/tree/main/internal/controller). The API endpoint
+is designed to be consumed only by the frontend and **no guarantees** can be made that it will remain stable
+throughout updates. In case you are building an application that utilizes the Tinyauth API, please make sure
+to consult the release notes of each Tinyauth release to ensure that no changes have been made.
+
+:::note
+Even though the API endpoints are not guaranteed to remain stable, user-facing endpoints like the forward-auth,
+OAuth and OpenID Connect endpoints **are guaranteed** to remain stable.
+:::
+
 ## Authenticating to Apps with Basic Auth
 
 Some apps already offer authentication methods like basic auth (e.g. browser pop-ups). This can be inconvenient as it requires logging in to both Tinyauth and the protected app. Tinyauth supports authenticating to apps automatically by adding basic auth labels to the protected app.

src/content/docs/docs/guides/oidc.mdx

@@ -6,7 +6,11 @@ description: Use Tinyauth's OIDC server to authenticate applications.
 import { Tabs, TabItem } from '@astrojs/starlight/components';
 import CreateOidcClientTool from "../../../../components/create-oidc-client-tool.astro";
 
-In Tinyauth v5, a major milestone was the introduction of the OIDC server, which allows Tinyauth not only to use other identity providers but also to act as an identity provider itself. This means that Tinyauth can serve as a central authentication gateway for multiple applications, providing a single sign-on experience for users.
+From v5.1.0 and going forward, Tinyauth is an OpenID Connect™ Certified server. This means that Tinyauth has been tested and verified to comply with the OpenID Connect Core 1.0 specification, ensuring that it meets the standards for secure authentication and identity management.
+
+You can use the OpenID Connect server of Tinyauth to authenticate applications and provide a seamless login experience for users using a centralized authentication system. This allows for better security, easier user management, and a more streamlined user experience across multiple applications.
+
+<img alt="OpenID Certified" width="200" src="https://openid.net/wordpress-content/uploads/2016/05/oid-l-certification-mark-l-cmyk-150dpi-90mm.jpg" />
 
 ## What is OpenID Connect?
 
@@ -36,17 +40,40 @@ Supported scopes:
 - `openid`
 - `profile`
 - `email`
+- `phone`
+- `address`
 - `groups`
 
 Supported claims:
 
 - `sub`
 - `name`
+- `given_name`
+- `family_name`
+- `middle_name`
+- `nickname`
+- `profile`
+- `picture`
+- `website`
+- `gender`
+- `birthdate`
+- `zoneinfo`
+- `locale`
 - `email`
 - `preferred_username`
+- `email_verified`
+- `phone_number`
+- `phone_number_verified`
+- `address`
 - `groups`
 - `updated_at`
-- `email_verified`
+
+These claims align with the OpenID Connect Core 1.0 specification's standard claims.
+
+:::note
+The `groups` claim and scope are an addition to the OpenID Connect Core 1.0 specification and
+not something officially supported by the OpenID Foundation.
+:::
 
 Supported token endpoint authentication methods:
 
@@ -61,7 +88,7 @@ While no promises can be made, if you feel a required OpenID Connect feature is
 
 ## Important Considerations
 
-Tinyauth’s core idea is to be a stateless application, but OIDC requires persistence for session and key storage. Everything is stored in the `/data` directory so, if you are using Docker, add the corresponding volume to your `docker-compose.yml` file:
+Tinyauth’s core idea is to be a stateless application however, OpenID Connect requires persistence for sessions and keys. Everything is stored in the `/data` directory so, if you are using Docker, add the corresponding volume to your `docker-compose.yml` file:
 
 ```yaml
 services:
@@ -76,6 +103,12 @@ You also need to specify the paths where the public and private keys are stored.
 
 Lastly, for the OIDC server to work, HTTPS is **required** on the app URL, which will become the issuer URL. You can use a self‑signed certificate or a certificate from a trusted CA.
 
+:::tip
+In case you are planning to use Tinyauth as a standalone OpenID Connect provider, you can use
+`TINYAUTH_AUTH_SUBDOMAINSENABLED=false` to disable support for wildcard cookies and increase
+security. By disabling wildcard cookies, the forward-auth middleware will ***not*** work.
+:::
+
 ## Creating OIDC Clients
 
 To create an OIDC client, use the `oidc create` command. For example:

src/content/docs/docs/guides/tailscale.mdx

@@ -0,0 +1,108 @@
+---
+title: Tailscale Authentication
+description: Use your Tailscale connection to automatically log in to Tinyauth.
+---
+
+Tinyauth has support for detecting your Tailscale connection and automatically logging you in with
+your Tailscale identity. This is made possible using the Tailscale API.
+
+## Requirements
+
+- A Tailscale account
+- A Tinyauth instance
+
+:::warning
+You will need your proxy to correctly forward the client IP to Tinyauth for the Tailscale detection
+to work. This differs from proxy to proxy, but usually you will need your proxy container to run
+with `network_mode: host` in Docker.
+:::
+
+### K3S
+
+In case you are using K3S (and possibly other Kubernetes deployments that use Traefik+MetalLB) you can use
+the following Helm chart config for Traefik to forward the correct client IP to your applications (including
+Tinyauth):
+
+```yaml
+apiVersion: helm.cattle.io/v1
+kind: HelmChartConfig
+metadata:
+  name: traefik-config
+  namespace: kube-system
+spec:
+  valuesContent: |-
+    service:
+      spec:
+        externalTrafficPolicy: Local
+
+    entryPoints:
+      web:
+        address: ':80'
+        forwardedHeaders:
+          trustedIPs:
+            - 10.42.0.0/24
+      websecure:
+        address: ':443'
+        forwardedHeaders:
+          trustedIPs:
+            - 10.42.0.0/24
+```
+
+You can check if Tinyauth is receiving the correct client IP by visiting it and checking the
+`client_ip` section in the info logs.
+
+## Get the Tailscale API token
+
+Before configuring Tinyauth, you need to obtain your Tailnet ID and an API token from Tailscale. This can be
+done by visiting the Tailscale [admin console](https://login.tailscale.com/admin/settings/general). The Tailnet
+ID is the first thing you see in the page.
+
+![Tailscale Settings](/screenshots/tailscale/tailscale_settings.png)
+
+:::note
+While you can use the Legacy Tailnet ID, it is recommended to use the new random one.
+:::
+
+Then, you can generate an API token in the [keys](https://login.tailscale.com/admin/settings/keys) page.
+
+![Tailscale keys page](/screenshots/tailscale/tailscale_keys.png)
+
+There click the **Generate access token** button, give it a name and click **Generate access token** again.
+You should then be greeted by the following page.
+
+![Tailscale API tokens](/screenshots/tailscale/tailscale_api_token.png)
+
+Make sure to note down your Tailnet ID and the new API token as we will need them in the next part.
+
+## Configure Tinyauth
+
+With your Tailnet ID and API token you can configure Tinyauth in the following way:
+
+```yaml
+services:
+  tinyauth:
+    environment:
+      - TINYAUTH_TAILSCALE_ENABLED=true
+      - TINYAUTH_TAILSCALE_APITOKEN=your-api-token # TINYAUTH_TAILSCALE_APITOKENFILE also supported
+      - TINYAUTH_TAILSCALE_TAILNET=your-tailnet-id
+```
+
+Tinyauth by default caches the user and device list for 5 minutes, you can reduce the cache duration with
+`TINYAUTH_TAILSCALE_CACHEDURATION` (in seconds).
+
+:::note
+Tinyauth does ***not*** support serving on a Tailscale domain (like `tinyauth.funny-name.ts.net`). This is
+because we would need the `tsnet` library to serve on Tailscale which adds a lot of unnecessary weight to the
+binary (+20MB). Features requiring the `tsnet` library will ***not*** be added.
+:::
+
+Make sure to restart Tinyauth after updating the configuration.
+
+## Usage
+
+After restarting and assuming Tinyauth can get your client IP, you should see the following screen
+when visiting Tinyauth to login:
+
+![Tinyauth Tailscale Login](/screenshots/tailscale/tailscale_login.png)
+
+After clicking **Continue with Tailscale**, authentication should proceed as normal.

src/content/docs/docs/integrations/tailscale.mdx

@@ -0,0 +1,95 @@
+---
+title: Tailscale
+description: Use the Tinyauth OpenID Connect provider to authenticate in Tailscale.
+---
+
+import { Steps } from '@astrojs/starlight/components';
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+import CreateOIDCClientTool from "../../../../components/create-oidc-client-tool.astro";
+
+Tinyauth meets all of the criteria to be used as an OpenID Connect provider for Tailscale. This includes
+support for all of the required OpenID Connect scopes, claims and endpoints. Tinyauth also includes support
+for WebFinger which is required for Tailscale to discover the OpenID Connect provider.
+
+## Requirements
+
+- A Tailscale account
+- A Tinyauth instance
+- A domain name
+
+:::caution
+You will need to run Tinyauth with HTTPS to use it as an OpenID Connect provider.
+:::
+
+:::caution
+Tinyauth will need to be accessible from the internet for Tailscale to be able to reach it.
+This means that you will need to have a public domain name and a valid SSL certificate for
+your Tinyauth instance.
+:::
+
+
+## Tinyauth Configuration
+
+To begin with, we need to generate a client ID and secret in Tinyauth for Tailscale. This can be done by running the following command:
+
+<Tabs>
+  <TabItem label="Docker">
+    ```sh
+    docker run -i -t --rm ghcr.io/steveiliop56/tinyauth:v5 oidc create tailscale
+    ```
+  </TabItem>
+  <TabItem label="Binary">
+    ```sh
+    ./tinyauth oidc create tailscale
+    ```
+  </TabItem>
+  <TabItem label="Browser">
+    <CreateOIDCClientTool />
+  </TabItem>
+</Tabs>
+
+From the output, make sure to note down the client ID and secret as we will need them later for the Tinyauth configuration.
+
+Now, we can pass our configuration to Tinyauth using environment variables:
+
+```sh
+TINYAUTH_OIDC_PRIVATEKEYPATH=/path/to/private/key.pem
+TINYAUTH_OIDC_PUBLICKEYPATH=/path/to/public/key.pem
+TINYAUTH_OIDC_CLIENTS_TAILSCALE_CLIENTID=client-id
+TINYAUTH_OIDC_CLIENTS_TAILSCALE_CLIENTSECRET=ta-client-secret
+TINYAUTH_OIDC_CLIENTS_TAILSCALE_TRUSTEDREDIRECTURIS=https://login.tailscale.com/a/oauth_response
+TINYAUTH_OIDC_CLIENTS_TAILSCALE_NAME=Tailscale
+```
+
+## Sign-up in Tailscale
+
+:::note
+These steps are quoted from the [Tailscale documentation](https://tailscale.com/docs/integrations/identity/custom-oidc#tailscale-setup).
+:::
+
+<Steps>
+
+1. Go to the [Sign up with OIDC](https://login.tailscale.com/start/oidc) page of the admin console or
+    when signing-up for a new account, select the **Sign up with OIDC** option.
+
+    <img alt="Tailscale Sign-up with OIDC" width="256"
+        src="https://tailscale.com/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fsign-up-oidc.b699a417.png&w=1080&q=75" />
+
+2. In the Email address field, enter the administrator's full email address.
+    The domain in the email address must match the domain where the WebFinger endpoint is served, and the domain you will use for Tailscale.
+
+3. Select **Get OIDC** Issuer. If Tailscale is able to retrieve the issuer from Tinyauth, it will be displayed in the Issuer field.
+
+4. In the Client ID field, enter the client ID we generated previously.
+
+5. Likewise, in the Client Secret, enter the Client Secret.
+
+6. If you like, you can skip the consent screen of Tinyauth by selecting the `none` prompt.
+
+7. Select **Sign up with OIDC**. You will be redirected to Tinyauth for authentication.
+
+8. Log in to your provider using the email you entered in step 2. Upon authentication, you will be redirected to the Tailscale admin console.
+
+</Steps>
+
+The user that configures OIDC for Tailscale becomes the first user in the tailnet and Owner of the tailnet.

src/content/docs/docs/integrations/zerobyte.mdx

@@ -4,6 +4,7 @@ description: Use the Tinyauth OpenID Connect provider to authenticate users with
 ---
 
 import { Tabs, TabItem } from '@astrojs/starlight/components';
+import CreateOIDCClientTool from "../../../../components/create-oidc-client-tool.astro";
 
 [Zerobyte](https://github.com/nicotsx/zerobyte) is a popular self-hosted backup automation solution based on restic. It allows users to easily manage and automate their backup tasks through a user-friendly web interface. By integrating Tinyauth as an OpenID Connect provider, you can enhance the security of your Zerobyte instance by enabling single sign-on (SSO) and centralized authentication.
 
@@ -32,6 +33,9 @@ To begin with, we need to generate a client ID and secret in Tinyauth for Zeroby
     ./tinyauth oidc create zerobyte
     ```
   </TabItem>
+  <TabItem label="Browser">
+    <CreateOIDCClientTool />
+  </TabItem>
 </Tabs>
 
 From the output, make sure to note down the client ID and secret as we will need them later for the Zerobyte configuration.