Bookmarks

    Nothing saved yet. Use the bookmark on any article. Bookmarks are kept on this device only: they stay private and work without an account.

    Settings

    Appearance

    Reading mode

    Font size

    Content width

    Line spacing

    Keyboard shortcuts

    /
    Search
    j k
    Next / previous story
    ← →
    Previous / next section (columns)
    b
    Bookmarks
    s
    Settings
    r
    Columns / scroll
    t
    Light / dark

    Saved in this browser only.

    Ping2Prompt
    Subscribe to the Weekly Brief Sign in
    A network equipment rack with many patch cables plugged into switch ports, lit by green light.
    Photo by Tyler on Unsplash

    Put Proxmox admin sign-in behind Pocket ID passkeys and a management-only firewall

    Automated source check Documentation reviewed

    Proxmox VE

    What you get

    Here is the end state you are building this weekend. Proxmox VE supports OpenID Connect realms, and Pocket ID documents a step-by-step Proxmox client setup. OpenID Connect lets Proxmox verify who you are from a sign-in done by an external server.

    The threat is a stolen or reused admin password on a login page that too many machines can reach. The Proxmox firewall is completely disabled by default, so the build turns it on. You then limit remote access to the web GUI on port 8006 to a management list of IPs.

    Apps without native OIDC, SAML or LDAP can sit behind authentik's proxy provider. Know the limits up front.

    The sources do not say Pocket ID can force passkey-only sign-in, and they say nothing about hardware keys. They also do not cover TrueNAS, so it is left out of this build.

    Before you start

    You need a Proxmox VE host and a Pocket ID instance that you reach over HTTPS. The sources do not explain how to install Pocket ID or put it behind HTTPS, so use its own docs for that. Note the release you tested for Proxmox VE, Pocket ID and authentik, because the sources name no release.

    Set APP_URL to the address you open Pocket ID at, with no path, for example https://id.example.com. Passkeys are bound to that domain, so settle the final hostname before anyone enrolls. Only ENCRYPTION_KEY is required, and it must be at least 16 bytes.

    Set ALLOW_INSECURE_CALLBACK_URLS to false, because its default of true allows http callback URLs on hosts other than localhost. Pocket ID listens on port 1411 by default. Here is the one decision to make now.

    Decide which IP addresses count as your management network, and write them down. They go into the firewall list in Step 5.

    Step 1

    Build the safety net first. Open an SSH connection to a Proxmox host before enabling the firewall, and leave it open. The Linux PAM realm is added by default and cannot be removed.

    PAM users are system users on the host, for example created with adduser (verify before running, per the Proxmox user management docs). They must exist on every node where they log in. In a cluster, a password change through the GUI or the /access/password endpoint applies only to the local node.

    Back up /etc/pve/domains.cfg before you change realms. It worked when you can sign in with the PAM admin and the SSH session is still open.

    Step 2

    Create the client in Pocket ID. Go to Administration, then OIDC Clients, and click Add OIDC Client (verify before running, from the Pocket ID Proxmox example). Name it, for example Proxmox, and set the callback URL to https://proxmox.example.com.

    The example gives no port, and the sources do not say whether the web GUI port or a proxy belongs in the URL. Test with the address you actually use to open Proxmox. Create the client, then copy the Client ID and the Client secret.

    The secret is shown only once, so store it now. On the client's Access tab, choose Allowed User Groups or All Users. It worked when the client is listed and you hold the ID and secret.

    Step 3

    Add the realm in Proxmox. Go to Datacenter, then Permissions, then Realms, and add an OpenID Connect Server realm (verify before running). Set the Issuer URL to your Pocket ID address, such as https://id.example.com.

    Choose a realm name such as PocketID, and enter the Client ID. Paste the Pocket ID client secret into the Client Key field. Tick Autocreate Users and set Username Claim to username.

    Tick Default if you want the realm preselected, leave the rest as defaults, and click OK. Realms are stored in /etc/pve/domains.cfg. It worked when the new realm appears in the realm list.

    Step 4

    Give your identity a role. Sign in once with a Pocket ID user, so the account is autocreated. The sources do not say what an autocreated user can do by default, so check it yourself.

    From your PAM admin session, open Datacenter, Permissions, Add, User Permission (verify before running). Set Path to /, pick the user such as name@PocketID, and set Role to Administrator. Proxmox recommends granting permissions to groups rather than to individual users.

    For groups, create Proxmox Users and Proxmox Admins in Pocket ID, and allow them on the client's Access tab. Then edit the realm: set Scope to 'openid profile email groups', set Group Claim to groups, and tick Autocreate Groups. Assign PVEAudit to Proxmox Users@PocketID and Administrator to Proxmox Admins@PocketID under Datacenter, Permissions.

    Passkey enrollment steps are not in the sources, so follow Pocket ID's own docs. It worked when you sign in through the PocketID realm and can act with the role you assigned.

    Step 5

    Now narrow the web GUI port with the firewall. Confirm the SSH session from Step 1 is still open. Create an IPSet named management and add all your remote admin IPs (verify before running, per the Proxmox firewall docs).

    The docs say this creates all the rules required for GUI access. The alternative is explicit rules allowing those IPs to port 8006, optionally port 22 for SSH and 3128 for SPICE. Cluster-wide config lives in /etc/pve/firewall/cluster.fw, and you can also use Datacenter, Firewall in the GUI.

    That file has [OPTIONS], [RULES] and [IPSET ] sections. Switch the firewall on with enable: 1 in the [OPTIONS] section. Once enabled, traffic to all hosts is blocked by default, with exceptions for the local network to the WebUI, SSH and other important services.

    The sources do not say whether that exception keeps the web GUI port open to your whole local network, or how to narrow it. They also omit exact rule syntax, so use the GUI and test from an address outside the management list. Host-level rules in /etc/pve/nodes//host.fw take precedence over datacenter-level rules, so check that file too.

    The pve-firewall service updates iptables automatically when the config changes. If Pocket ID runs on the same Proxmox host, a lockout loop is possible, and the sources do not cover it.

    Step 6

    Put one non-OIDC app behind authentik. The proxy provider offers Proxy, Forward auth for a single application, and Forward auth at domain level. With an existing reverse proxy, use a forward auth mode, where the outpost checks authentication and authorization.

    Pick single-application mode, because domain-level mode cannot enforce different authorization rules per app. The outpost listens on port 9000 for HTTP and 9443 for HTTPS. It passes headers such as X-authentik-username, X-authentik-groups, X-authentik-email and X-authentik-uid to the app.

    The sources do not give the provider, application and outpost steps, or any reverse proxy snippet, so use authentik's own guide. If you add Unauthenticated Paths, remember they are regexes. A pattern that fails to compile is skipped with only a warning in the outpost logs.

    Matching uses the request path in single-app mode, and the full URL in domain-level mode. Leave that list empty if you can.

    Sign out at /outpost.goauthentik.io/sign_out on the host serving the outpost (verify before running). That invalidates all of the user's sessions within the outpost.

    Verify

    Run these checks from a management address first. Open Proxmox, pick the PocketID realm, and complete sign-in with your passkey. Check that the role assignments under Datacenter, Permissions match what you set.

    Check that cluster.fw contains enable: 1 under [OPTIONS]. Try port 8006 from an address outside the management list. The sources give no expected output, so write down what you see and judge it against your own goal.

    Confirm the PAM fallback still works from the management network. Open the proxied app without a session and confirm you are sent to authentik. Scan the outpost logs for regex warnings.

    Disable a test user and confirm new sessions are blocked. Remember that already started tasks, such as terminal sessions, are not terminated automatically. The sources do not say whether the PAM or PVE login form can be disabled, so the firewall is your only narrowing control here.

    Rollback

    Undo in reverse order, and keep the PAM admin until the build has proven itself. Reverse the enable: 1 setting in [OPTIONS] of /etc/pve/firewall/cluster.fw, from your open SSH session (verify before running). Restore the domains.cfg backup, or remove the PocketID realm from the Realms list.

    Disable or delete autocreated users and groups, knowing that running tasks keep going. Delete the Pocket ID client if you no longer need it.

    The sources do not document deletion steps for Pocket ID or authentik. Remove the forward-auth check from your reverse proxy config for the app, using the snippet you wrote.

    Sources

    Image: Photo by Tyler on Unsplash


    This story was produced with AI assistance from the sources listed above and fact-checked against them before publication. Read our editorial methodology and the corrections log. Spotted an error? Email [email protected].

    Continue

    Share on Bluesky · Mastodon · Email ·

    Discussion