From 7350e3486d2e7ac0cdf0f93e460f7db31da22091 Mon Sep 17 00:00:00 2001 From: Kyle Mendell Date: Wed, 5 Feb 2025 10:18:01 -0600 Subject: [PATCH] docs: enhance documentation (#205) Co-authored-by: Elias Schneider --- docs/docs/configuration/allowed-groups.md | 15 +++++++ docs/docs/setup/installation.md | 2 +- docs/docs/setup/user-management.md | 40 ++++++++++++++++++ docs/docs/troubleshooting/common-issues.md | 29 +++++++++++++ docs/sidebars.ts | 48 ++++++++++++---------- 5 files changed, 112 insertions(+), 22 deletions(-) create mode 100644 docs/docs/configuration/allowed-groups.md create mode 100644 docs/docs/setup/user-management.md create mode 100644 docs/docs/troubleshooting/common-issues.md diff --git a/docs/docs/configuration/allowed-groups.md b/docs/docs/configuration/allowed-groups.md new file mode 100644 index 0000000..cdaaa93 --- /dev/null +++ b/docs/docs/configuration/allowed-groups.md @@ -0,0 +1,15 @@ +--- +id: allowed-groups +--- + +# OIDC Client Allowed Groups + +Pocket ID allows you to restrict access to OIDC Clients to specific user groups. This can be useful when you want to restrict access to certain applications to specific users. + +By default, all users are allowed to access all OIDC Clients. To restrict access to specific user groups, follow the steps below: + +1. Navigate to the `OIDC Clients` section in the Pocket ID admin dashboard. +2. Click the edit (pencil) icon on the OIDC client you wish to restrict. +3. Expand the `Allowed User Groups` section. +4. Select the Group(s) you want to allow access to this OIDC Client and save your changes. +5. Now only users in the selected group(s) will be allowed to access that specific client. diff --git a/docs/docs/setup/installation.md b/docs/docs/setup/installation.md index dd1eb68..11d9b10 100644 --- a/docs/docs/setup/installation.md +++ b/docs/docs/setup/installation.md @@ -39,7 +39,7 @@ bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/c Pocket ID is available as a template on the Community Apps store. -### Stand-alone Installation +### Stand-alone Installation (advanced) Required tools: diff --git a/docs/docs/setup/user-management.md b/docs/docs/setup/user-management.md new file mode 100644 index 0000000..ebae744 --- /dev/null +++ b/docs/docs/setup/user-management.md @@ -0,0 +1,40 @@ +--- +id: user-management +--- + +# User Management + +Creating users in Pocket ID can be handled in two ways: + +1. Manually create users via the admin interface. +2. Sync users from an [LDAP](/configuration/ldap) source. + +Once users have been created using one of the methods above, follow the steps below to help configure passkeys for them. + +## Setting Up User Passkeys + +> As the admin, you cannot add passkeys for users; end users must configure them on their own. + +> Passkeys can be stored in services like Bitwarden, LastPass, iCloud, or even locally on certain devices using platform authenticators. + +### One-Time Link + +1. Navigate to the **Users** page in the Pocket ID admin dashboard. +2. Locate the user you want to set up a passkey for. +3. Click the **three dots** on the right side of the user row. +4. Click **One-Time Link**. +5. Select an **Expiration Time** for the link. +6. Click **Generate Link** and send it to the user to allow them to set up their new passkey. + +### One-Time Access Email + +> **This method requires a valid SMTP server set up in Pocket ID.** + +> **Allowing users to sign in with a link sent to their email significantly reduces security, as anyone with access to the user's email can gain entry.** + +1. Navigate to the **Application Configuration** section in the Pocket ID admin dashboard. +2. Expand the **Email** section and enable the **Email One-Time Access** option. +3. Instruct the user to navigate to Pocket ID, e.g., `https://id.example.com`. +4. Have the user click on the **Don't have access to your passkey?** link at the bottom of the page. +5. Have the user enter their email associated with their Pocket ID account and click **Submit**. +6. The user will receive an email with a **One-Time Access** link to set up their passkey. diff --git a/docs/docs/troubleshooting/common-issues.md b/docs/docs/troubleshooting/common-issues.md new file mode 100644 index 0000000..6793d82 --- /dev/null +++ b/docs/docs/troubleshooting/common-issues.md @@ -0,0 +1,29 @@ +--- +id: common-issues +--- + +# Common Issues + +## Unable to Add a Passkey + +Ensure that the `PUBLIC_APP_URL` is set correctly to the public URL of the Pocket ID instance. + +Example: + +```ini +PUBLIC_APP_URL=https://id.example.com +``` + +## Unable to Access the Admin UI After Setup + +To set up the initial passkey for the admin user, navigate to: + +``` +https://id.example.com/login/setup +``` + +## Invalid Callback URL + +One of the most common issues with OIDC clients is a misconfigured `Callback URL`. + +If the `redirect_uri` URL parameter starts with `http` but `https` is expected, the client is the issue. If you can’t resolve the issue on the client side, you can add a secondary callback URL using both `http` and `https` versions. diff --git a/docs/sidebars.ts b/docs/sidebars.ts index c9ebec1..a164c33 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -14,6 +14,10 @@ const sidebars: SidebarsConfig = { type: "doc", id: "setup/installation", }, + { + type: "doc", + id: "setup/user-management", + }, { type: "doc", id: "setup/nginx-reverse-proxy", @@ -28,6 +32,10 @@ const sidebars: SidebarsConfig = { type: "category", label: "Configuration", items: [ + { + type: "doc", + id: "configuration/allowed-groups", + }, { type: "doc", id: "configuration/environment-variables", @@ -48,6 +56,20 @@ const sidebars: SidebarsConfig = { }, ], }, + { + type: "category", + label: "Troubleshooting", + items: [ + { + type: "doc", + id: "troubleshooting/account-recovery", + }, + { + type: "doc", + id: "troubleshooting/common-issues", + }, + ], + }, { type: "category", label: "Client Examples", @@ -61,11 +83,13 @@ const sidebars: SidebarsConfig = { items: [ "client-examples/cloudflare-zero-trust", "client-examples/freshrss", + "client-examples/gitea", "client-examples/grist", "client-examples/headscale", "client-examples/hoarder", "client-examples/immich", "client-examples/jellyfin", + "client-examples/memos", "client-examples/netbox", "client-examples/open-webui", "client-examples/pgadmin", @@ -73,30 +97,12 @@ const sidebars: SidebarsConfig = { "client-examples/proxmox", "client-examples/semaphore-ui", "client-examples/vikunja", - "client-examples/gitea", - "client-examples/memos", ], }, { - type: "category", - label: "Troubleshooting", - items: [ - { - type: "doc", - id: "troubleshooting/account-recovery", - }, - ], - }, - { - type: "category", - label: "Helping Out", - items: [ - { - type: "link", - label: "Contributing", - href: "https://github.com/stonith404/pocket-id/blob/main/CONTRIBUTING.md", - }, - ], + type: "link", + label: "Contributing", + href: "https://github.com/stonith404/pocket-id/blob/main/CONTRIBUTING.md", }, { type: "link",