docs: add pocket id as OIDC provider WD-34162 (canonical#17827)

## Done
- add pocket id as OIDC provider
## Checklist

- [ x] I have read the [contributing
guidelines](https://github.com/canonical/lxd/blob/main/CONTRIBUTING.md)
and attest that all commits in this PR are [signed
off](https://github.com/canonical/lxd/blob/main/CONTRIBUTING.md#including-a-signed-off-by-line-in-your-commits),
[cryptographically
signed](https://github.com/canonical/lxd/blob/main/CONTRIBUTING.md#commit-signature-verification),
and follow this project's [commit
structure](https://github.com/canonical/lxd/blob/main/CONTRIBUTING.md#commit-structure).
- [x ] I have checked and added or updated relevant documentation.

Author: tomponline

doc/explanation/authorization.md

@@ -139,8 +139,8 @@ When an OIDC client makes a request to LXD, any groups that can be extracted fro
 
 To configure IdP group mappings in LXD, first configure your IdP to add groups to identity and access tokens as a custom claim.
 This configuration depends on your IdP.
-In [{spellexception}`Auth0`](https://auth0.com/), for example, you can enable [{abbr}`RBAC (role-based access control)`](https://auth0.com/docs/manage-users/access-control/rbac) which will add a "permissions" claim to tokens.
-In Keycloak, you can define a [mapper](https://forum.keycloak.org/t/anyway-to-include-user-groups-into-my-jwt-token/8715) to set Keycloak groups in the token.
+In [{spellexception}`Auth0`](https://auth0.com/), for example, you can enable [{abbr}`RBAC (role-based access control)`](https://auth0.com/docs/manage-users/access-control/rbac) which will add a "permissions" claim to tokens. Then, configure {ref}`automatic mapping to LXD authorization groups <oidc-auth0-automatic-group-mapping>`.
+In Keycloak, you can define a [mapper](https://forum.keycloak.org/t/anyway-to-include-user-groups-into-my-jwt-token/8715) to set Keycloak groups in the token. In [Pocket ID](https://pocket-id.org/docs), you can set up {ref}`custom claims <oidc-pocket-id-automatic-group-mapping>` in your admin dashboard.
 
 Then configure LXD to extract this claim.
 To do so, set the value of the {config:option}`server-oidc:oidc.groups.claim` configuration key to the value of the field name of the custom claim:

doc/howto/oidc.md

@@ -15,6 +15,7 @@ How to configure Auth0 </howto/oidc_auth0>
 How to configure Ory Hydra </howto/oidc_ory>
 How to configure Keycloak </howto/oidc_keycloak>
 How to configure Entra ID </howto/oidc_entra_id>
+How to configure Pocket ID </howto/oidc_pocket_id>
 ```
 
 ## Related topics

doc/howto/oidc_auth0.md

@@ -45,6 +45,7 @@ Users will have no permissions by default. You must set up {ref}`LXD authorizati
 
 1. Configure roles in Auth0 and use automatic mapping to LXD authorization groups as described below.
 
+(oidc-auth0-automatic-group-mapping)=
 ## Set up automatic group mappings
 An admin can set up multiple users in Auth0 and allocate roles to those users. When a user logs in via OIDC, their allocated Auth0 roles can be mapped to LXD authorization groups through custom claims. This section details the steps for configuring roles in Auth0 and setting up a custom claim so that LXD can map those roles to its authorization groups.
 

doc/howto/oidc_pocket_id.md

@@ -0,0 +1,95 @@
+---
+myst:
+  html_meta:
+    description: Configure LXD to authenticate using Pocket ID via OpenID Connect (OIDC) in your tenant.
+---
+
+(oidc-pocket-id)=
+
+# How to configure Pocket ID as login method for LXD
+
+Pocket ID is a modern, self-hosted OIDC provider distributed as a single Go binary. It supports only passkeys (no passwords), allowing you to sign into LXD.
+
+## Using Pocket ID to access LXD
+
+1.  Set up [Pocket ID](https://pocket-id.org/docs) using their [installation guide](https://pocket-id.org/docs/setup/installation). This guide assumes that Pocket ID is available over HTTPS.
+
+1.  Create an admin account at `https://<your-app-url>/setup`.
+
+1.  From the main navigation, go to {guilabel}`Administration` > {guilabel}`OIDC Clients`.
+
+1.  From the {guilabel}`Create OIDC Client` section, click {guilabel}`Add OIDC Client`.
+    - Enter a name such as `lxd-client`.
+    - In the field for {guilabel}`Callback URLs`, enter your LXD UI address, followed by `/oidc/callback`.
+      - Example: `https://example.com:8443/oidc/callback`
+      - You can use an IP address instead of a domain name.
+      - Note `:8443` is the default listening port for the LXD server. It might differ for your setup. You can verify the LXD configuration value `core.https_address` to find the correct port for your LXD server.
+    - Enable the {guilabel}`PKCE` option.
+    - Optionally, to require users to authenticate again on each authorization, turn on the {guilabel}`Requires Re-Authentication` option.
+    - Click {guilabel}`Save`.
+
+1.  In the {guilabel}`Administration` > {guilabel}`OIDC Clients` page, click {guilabel}`Show more details` to see your client configuration.
+
+    ```{figure} /images/auth/pocket-id/pocket-id-show-more-details.png
+    Pocket ID client show more details button
+    ```
+
+    ```{figure} /images/auth/pocket-id/pocket-id-client.png
+    Pocket ID client details
+    ```
+
+    - Copy the {guilabel}`Client ID`, {guilabel}`Issuer URL`, {guilabel}`Client Secret` and set them in LXD server configuration:
+
+      ```bash
+      lxc config set oidc.client.id=<Client ID>
+      lxc config set oidc.issuer=<Issuer URL>
+      lxc config set oidc.client.secret=<Client Secret>
+      ```
+
+1.  From the main navigation, go to {guilabel}`Administration` > {guilabel}`Users`.
+    - From the {guilabel}`Create User` section, click {guilabel}`Add User`. Enter and save the user information.
+
+1.  From the main navigation, go to {guilabel}`Administration` > {guilabel}`User Groups`.
+    - From the {guilabel}`Create User Group` section, click {guilabel}`Add Group`. Enter and save the group information.
+    - From the {guilabel}`Users` section, select the user created in step 6 to the group and click {guilabel}`Save`.
+    - From the {guilabel}`Allowed OIDC Clients` section, select the client created in step 4 and click {guilabel}`Save`.
+
+Now you can access the LXD UI with any browser and use {abbr}`SSO (single sign-on)` login. To use OIDC on the LXD CLI, run `lxc remote add <remote-name> <LXD address> --auth-type oidc` and point a browser to the displayed URL to authenticate.
+
+By default, Pocket ID only has an admin user. Follow the [Pocket ID guide](https://pocket-id.org/docs/setup/user-management) to add users manually or sync with an LDAP source.
+
+Users will have no permissions by default. To grant access to projects and instances, you have two options:
+
+1. Set up {ref}`LXD authorization groups <manage-permissions>` to map a LXD authorization group to the user directly. Note, that the user object in LXD will only be created on the first login of that user to LXD.
+
+1. Configure roles in Pocket ID and use automatic mapping to LXD authorization groups as described below.
+
+(oidc-pocket-id-automatic-group-mapping)=
+
+## Set up automatic group mappings
+
+An admin can set up groups in Pocket ID and allocate roles to those groups. When a user in a group logs in via OIDC, their allocated Pocket ID roles can be mapped to LXD authorization groups through custom claims. This section details the steps for configuring roles in Pocket ID and setting up a custom claim so that LXD can map those roles to their authorization groups.
+
+1.  From the main navigation, go to {guilabel}`Administration` > {guilabel}`User Groups`.
+    - From the {guilabel}`Manage User Groups` section, select the group you want to assign roles to.
+    - From the {guilabel}`Users` section, add and save users to the group.
+    - From the {guilabel}`Custom Claims` section, click {guilabel}`Add custom claim`.
+    - Enter and save a custom claim key and a Pocket ID role value in the {guilabel}`key` and {guilabel}`value` fields, respectively (for example, `lxd-role-claim` as the key and `pocketID-admin` as the role), and remember these values for the next steps.
+
+    ```{figure} /images/auth/pocket-id/pocket-id-custom-claims.png
+    Pocket ID custom claims
+    ```
+
+1.  Tell LXD to use the custom claim from the previous step to extract Pocket ID roles. Replace `<claim_name>` with the exact custom claim key you configured in Pocket ID (for example, `lxd-role-claim`):
+
+    ```bash
+    lxc config set oidc.groups.claim=<claim_name>
+    ```
+
+1.  Map the Pocket ID role from step 1 to a LXD authorization group. Replace `<pocket-id-role-name>` with the exact role string you configured as the custom claim value in Pocket ID (for example, `pocketID-admin`):
+    ```bash
+    lxc auth identity-provider-group create <pocket-id-role-name>
+    lxc auth identity-provider-group group add <pocket-id-role-name> <LXD-group-name>
+    ```
+
+During the OIDC flow, LXD automatically extracts the custom claim from the user's `id_token` based on the LXD `oidc.groups.claim` configuration value. The extracted custom claim is an array of roles for your user from Pocket ID. Those roles are then mapped to LXD authorization groups using the identity provider group created in step 3.