Run a passkey-focused identity provider on your own infrastructure, verify it locally, and make its web endpoint reachable through an HTTP tunnel
Pocket ID is a self-hosted OpenID Connect and OAuth 2.0 provider designed around passwordless authentication with passkeys. In this guide, we explain how to prepare a Docker deployment, preserve the public identity-provider URL correctly, verify the service locally, and connect compatible applications. Once the local deployment works, we show how to publish its HTTP endpoint with Localtonet without configuring inbound router port forwarding, a public IP address, or a VPN. Exact Pocket ID ports, environment variables, paths, and bootstrap values must come from the current Pocket ID deployment files because those details are version-sensitive and are not safely inferred.
📋 What's in this guide
What Pocket ID does and where Localtonet fits
Pocket ID is an OpenID Connect Certified and OAuth 2.0 provider for self-hosted applications. Instead of maintaining a separate username and password in every compatible application, users authenticate through Pocket ID with passkeys. Pocket ID only supports passwordless authentication, so passkey enrollment and recovery planning are central parts of the deployment rather than optional additions.
OpenID Connect, commonly shortened to OIDC, adds an identity layer to OAuth 2.0. A relying application redirects a user to the identity provider, the identity provider authenticates the user, and the browser returns to an approved callback address. The application then validates the protocol response and establishes its own session. OAuth 2.0 can also issue access tokens with scopes for APIs, while OIDC provides identity claims to applications.
Pocket ID supports use cases such as authenticating homelab dashboards, administrative tools, custom applications, APIs, AI applications, and compatible remote MCP servers. Its documented capabilities include group-based access control, LDAP integration, SCIM provisioning, audit logs, an administrative REST API, API resource indicators, multiple languages, and signing in from another device by scanning a QR code and approving the request where the passkey is available.
Localtonet does not replace Pocket ID, OIDC, or application authorization. Pocket ID remains the identity provider, and every relying application must still be configured to trust it. Our role in this workflow is network reachability. The Localtonet client establishes an outbound connection from a device that can reach Pocket ID to one of our relay servers. An HTTP tunnel then provides a public HTTPS address that forwards traffic to Pocket ID's local HTTP listener.
OIDC deployments depend on exact URLs. The public issuer or application URL, discovery metadata, browser redirects, and registered callback addresses must agree. Do not complete production client registrations against a temporary local URL and then change the issuer casually. Decide which stable public hostname will represent Pocket ID, configure Pocket ID according to its current documentation, and test the complete browser flow through that address.
Prerequisites and deployment decisions
Pocket ID supports multiple setup methods, but its project documentation identifies Docker as the easiest and recommended method. This guide therefore assumes a Docker Compose deployment. Before creating containers, prepare the host, decide how data will persist, and determine the public address that relying applications will use.
Docker host requirements
Use a machine on which Docker Engine and the Docker Compose plugin are installed and operational. The host must be able to retrieve container images and must have durable storage for Pocket ID's persistent data. It also needs working system time and DNS resolution. Authentication protocols are sensitive to time differences, so keep the host clock synchronized through the operating system's normal time service.
Confirm Docker and Docker Compose before downloading or editing the Pocket ID deployment files:
docker --version
docker compose versionThese checks validate the Docker tooling only. They do not confirm that the Pocket ID configuration is complete.
Choose the public URL before configuring OIDC
Select the public address that users and applications will treat as Pocket ID's canonical URL. Localtonet HTTP tunnels can use a Random Sub Domain, Custom Sub Domain, or Custom Domain process type. All three serve content at a public HTTPS address, but their suitability for an identity provider differs operationally.
| Process type | Appropriate use | Identity-provider consideration |
|---|---|---|
| Random Sub Domain | Initial testing and short-lived evaluation | A changed public address can invalidate issuer expectations, redirect registrations, and saved application configuration. |
| Custom Sub Domain | A selected Localtonet subdomain where the current dashboard and plan support it | Use the exact assigned HTTPS address consistently in Pocket ID and every relying application. |
| Custom Domain | A stable hostname controlled by the operator | Check the current Localtonet custom-domain and DNS instructions before making changes because exact DNS requirements are not established in this guide. |
Availability can vary by plan, client version, and current product configuration. Obtain the available process types and relay-server choices from the current Localtonet dashboard rather than assuming that every option is included.
Prepare passkeys and recovery access
Because Pocket ID does not offer password authentication, decide which passkey-capable devices or hardware security keys administrators will use. Avoid creating a deployment whose only administrative passkey exists on one device. The exact enrollment and recovery workflow must follow the current Pocket ID interface and documentation, but the operational goal is straightforward: prevent the loss of one phone, computer, or security key from becoming a permanent administrative lockout.
Prepare the Localtonet client device
Install and run the Localtonet client on the Pocket ID host or on another trusted device that can reach Pocket ID's local IP address and port. The tunnel target is evaluated from that client device. A loopback address refers to the Localtonet client device itself, so it is suitable only when Pocket ID is reachable on that same device.
You will also need a Localtonet device authentication token and an available relay server selection. Tokens are device-specific secrets. Do not paste a token into compose files, screenshots, application logs, public issue reports, or tutorial examples.
Install and start Pocket ID with Docker Compose
The Pocket ID repository contains a Docker Compose file and an environment example, but the supplied project evidence does not establish the current required environment-variable names, default port, volume paths, image reference, or bootstrap procedure. Those details can change between releases. We will not reproduce guessed values because an incorrect issuer setting or storage mapping can produce a deployment that appears to work while breaking login flows or losing state.
Obtain the current Docker installation files from the official Pocket ID project and keep them together in a dedicated deployment directory. Review the matching Pocket ID documentation for the version you intend to deploy. Do not combine a compose file from one release with an environment example copied from another release.
Create a dedicated deployment directory
Keep the Pocket ID compose file, its environment file, and any deployment notes in a directory used only for this service. Restrict access because configuration files may contain secrets or operational details.
Obtain matching official deployment files
Download the current Docker Compose file and environment example from the official Pocket ID project or use the files associated with the release you have selected. Review release notes before upgrading or using a version-specific file.
Complete the documented configuration
Set every required value exactly as described by the current Pocket ID documentation. Pay particular attention to the canonical external URL, persistent storage, generated secrets, and any reverse-proxy settings. Do not infer undocumented variable names or reuse example secrets.
Validate the Compose model
From the directory containing the compose file, ask Docker Compose to render and validate the resolved configuration. Inspect the result carefully and avoid publishing output that contains secrets.
Start Pocket ID
Start the deployment in detached mode from the directory containing the reviewed compose file. Then inspect container state and logs before opening the service to another network.
Complete the documented first-run flow
Open the local web interface using the host and port defined by your actual configuration. Complete Pocket ID's current administrator bootstrap and passkey-enrollment workflow. Record operational recovery information securely, but never store private credentials in public notes.
Run the validation and startup commands from the directory containing the official compose file:
docker compose config
docker compose up -d
docker compose ps
docker compose logs
The rendered output from docker compose config can include expanded configuration and secrets. Treat it as sensitive. If Pocket ID does not start, use the logs to identify the reported configuration problem rather than cycling through guessed environment variables.
The available project evidence confirms that Docker is recommended and that compose and environment-example files exist, but it does not establish exact current variable names, local ports, paths, or defaults. Copying invented values into an identity provider would be unsafe. Use one matching version of the official files, and treat that version's documentation as authoritative for required configuration fields.
Verify Pocket ID locally before exposing it
A tunnel cannot repair an unhealthy container, an incorrect issuer URL, a missing volume, or a broken OIDC client registration. Establish a clear local baseline first. Keep the public tunnel stopped while performing initial bootstrap unless Pocket ID's current documented first-run process explicitly requires the final external address.
Check container state and logs
Use docker compose ps to confirm that the expected service is running. Review docker compose logs for startup failures, invalid configuration, storage errors, or repeated restarts. The exact healthy-state wording depends on the Pocket ID release and must not be guessed.
Open the configured local endpoint
Use the exact host port published by your compose configuration. Open that address from the Pocket ID host, then from the device that will run the Localtonet client if it is a different machine. This second test is important because a service can be accessible through loopback on its host while remaining unreachable over the local network.
Confirm that the web interface loads without a redirect loop and that static resources render. If the browser is unexpectedly redirected to another host, compare the address with Pocket ID's configured external URL. Redirect behavior is particularly important for identity services because it often reveals a mismatch before an OIDC application is involved.
Test administrator authentication
Complete the documented first-run setup and register an administrator passkey. Sign out, then sign in again. If Pocket ID offers the documented cross-device QR workflow in your selected version, test it with an appropriate passkey-capable device. Do not treat successful enrollment alone as proof that future sign-in works.
Confirm persistence before adding applications
Restart the deployment and verify that administrative state remains available:
docker compose restart
docker compose ps
docker compose logsSign in again after the restart. If users, passkeys, or configuration disappear, stop and correct the persistent-storage mapping before proceeding. Do not repeatedly recreate production identity data on an unverified volume.
Record a local baseline
Keep a private record of the deployed Pocket ID version, compose-file origin, external URL, local target address, storage location, backup procedure, and date of the last successful login test. Do not include client secrets, Localtonet tokens, passkey private material, or recovery credentials in that record unless it is held in an appropriately protected secrets system.
Configure Pocket ID and relying applications correctly
After Pocket ID works locally, connect one non-critical application as a controlled test. Each application's documentation determines which OIDC fields it requires. Common concepts include an issuer or discovery address, client identifier, client secret where applicable, redirect URI, requested scopes, and logout behavior. Use the exact values Pocket ID presents for the client instead of constructing endpoint paths manually.
Pocket ID supports standard identity-provider functions as well as group-based application access. The current project also supports RFC 8414 authorization-server metadata and metadata-based OAuth clients. Whether a particular relying application can consume those mechanisms depends on that application's implementation.
| Configuration element | Where it belongs | Common failure |
|---|---|---|
| Canonical issuer or external URL | Pocket ID configuration and the relying application's provider settings | Using a local URL in one place and the public HTTPS URL in another |
| Redirect URI | Registered Pocket ID client and relying application | A scheme, hostname, port, path, or trailing slash differs from the actual callback |
| Client identifier | Generated or displayed for the Pocket ID client, then copied to the application | Copying the identifier from a different client registration |
| Client secret | Only where the client type and integration require one | Exposing it in logs, screenshots, source control, or browser-delivered code |
| Scopes and API resource | Client and authorization configuration | Requesting more access than needed or confusing identity scopes with API permissions |
| Group access policy | Pocket ID application authorization | Assuming authentication automatically grants access to every registered user |
Begin with the minimum scopes and access needed by the test application. Successful authentication proves who the user is, but authorization still decides what that user may access. Where supported by the integration, use Pocket ID groups to restrict which users can sign in to the application.
Test the complete sequence in a private browser window: open the relying application, initiate sign-in, authenticate at Pocket ID, approve any documented consent step, return to the registered callback, and confirm the expected application identity and permissions. Then sign out and repeat the flow. A direct visit to the Pocket ID homepage does not validate this end-to-end protocol exchange.
A secret used by a confidential OIDC client belongs in that application's protected server-side configuration. Browser applications, mobile applications, and other public clients cannot reliably keep embedded secrets confidential. Follow the relying application's documented client type and flow rather than forcing a secret into an unsuitable client.
Publish Pocket ID with a Localtonet HTTP tunnel
Once Pocket ID works locally and its external URL has been planned, create an HTTP tunnel. An HTTP tunnel is appropriate because Pocket ID exposes a web and OIDC HTTP endpoint. Do not describe this as a VPN. Localtonet VPN Manager is our separate private mesh VPN feature, while this workflow publishes one HTTP service.
The Localtonet client must run on the Pocket ID host or another device that can connect to Pocket ID's local listener. If Docker publishes Pocket ID only on loopback, a Localtonet client on another machine will not be able to reach it. Test the target from the actual client device before creating the tunnel.
Install and run the Localtonet client
Run the client on the Pocket ID host or another trusted device with network access to the configured Pocket ID listener. Confirm that this device can open the local Pocket ID endpoint.
Authenticate or select the client device
Use the device-specific authentication token associated with the intended client. Keep the token private and do not substitute a token copied from an unrelated device.
Select an available relay server
Choose from the relay servers or regions currently available in the Localtonet dashboard. Do not hardcode a server code from an old guide because availability can change.
Create the HTTP tunnel configuration
Select the required HTTP process type and point the tunnel to the local IP address and port from the verified Pocket ID deployment. Use the exact local target that succeeded from the Localtonet client device.
Start the tunnel
Creating a tunnel does not start it. Press Start and wait until the selected client is connected and the tunnel is running. The public address works only while both conditions remain true.
Test the assigned public HTTPS address
Open the public URL from a network outside the Pocket ID host's local environment. Confirm the Pocket ID interface loads, then repeat a complete OIDC login through a test application using the final public address.
The current Localtonet HTTP tunnel documentation should be checked during setup for the exact dashboard fields and options available to your account. The tunnel target itself remains the verified local IP address and port on or reachable from the selected client device.
If you use a Localtonet-generated hostname for evaluation, configure Pocket ID and the test application with that exact HTTPS address as required by Pocket ID's current reverse-proxy guidance. For a long-lived deployment, prefer a public address that you intend to retain. Before using a custom domain, consult the current Localtonet documentation for exact DNS requirements rather than copying records from an unrelated setup.
Saving the configuration does not make Pocket ID publicly reachable. The selected Localtonet client must be connected, and the tunnel must be started. If either stops, the public address cannot reach the local service even if Pocket ID itself is still healthy.
Security checklist for a public identity endpoint
Publishing an identity provider increases its exposure to internet traffic. Passkeys remove shared-password authentication from Pocket ID, but they do not eliminate the need for host hardening, authorization, backups, monitoring, careful client registration, and software updates.
Restrict the Docker host to trusted administrators and keep the operating system maintained. Do not expose unrelated Docker management ports or services. If Pocket ID needs to communicate with LDAP, SCIM targets, or other internal systems, allow only the network paths required for those integrations.
Review every redirect URI. An overly broad or incorrect callback registration can undermine an otherwise correct identity deployment. Remove unused OIDC clients, rotate exposed client secrets according to Pocket ID and application procedures, and revoke access when an application is retired.
Pocket ID can issue scoped access tokens for APIs and supports OAuth 2.0 resource indicators. Use the intended API resource and only the actions required by the client. Do not assume that a token intended for one API should be accepted by another.
A copied directory is not automatically a valid recovery plan. Follow Pocket ID's version-appropriate backup and restoration guidance, protect backup confidentiality, and test recovery in an isolated environment. Do not add Docker's volume-removal options to routine shutdown commands unless permanent deletion is explicitly intended and verified.
Routine operations and troubleshooting
Check the two independent service layers
Troubleshoot Pocket ID and the tunnel separately. First test the local Pocket ID endpoint from the Localtonet client device. If that fails, inspect Docker, the local bind address, host firewall policy, container logs, and Pocket ID configuration. If local access works but public access fails, inspect the Localtonet client connection, selected device, tunnel state, local target, and current public address.
| Symptom | Likely area | What to verify |
|---|---|---|
| The local page does not load | Pocket ID or Docker | Container state, logs, published port, bind address, configuration validation, and storage access |
| Local access works only on the Pocket ID host | Listener scope or network path | Whether the Localtonet client runs on that host and whether the configured target is reachable from the client device |
| The public URL is unavailable | Localtonet tunnel lifecycle | Client connection, selected device token, tunnel Start state, relay selection, and local target |
| The public page loads but login loops | Canonical URL or proxy configuration | Pocket ID's documented external URL settings, the public HTTPS hostname, and forwarded-request handling required by the current version |
| The application reports an issuer error | OIDC metadata consistency | The exact configured issuer and metadata returned through the public address, without manually rewriting endpoint paths |
| The callback is rejected | Client registration | Exact scheme, hostname, port, path, capitalization, and trailing-slash behavior of the registered redirect URI |
| Authentication succeeds but access is denied | Authorization | Application group policy, user membership, scopes, API resource, and the relying application's own permissions |
| State disappears after recreation | Persistent storage | Volume or bind-mount configuration and whether the deployment was recreated with the same durable storage |
View status and logs
docker compose ps
docker compose logsAdd service-specific or time-filtering options only when supported by your installed Docker Compose version and needed for the investigation. Redact secrets, tokens, client identifiers where sensitive, user information, and private endpoints before sharing logs.
Restart without changing the deployment
docker compose restartA restart can recover a transient process problem, but it does not correct invalid configuration. If the service repeatedly fails, inspect the first relevant startup error rather than relying on repeated restarts.
Upgrade deliberately
Before upgrading, read the release notes for every version involved, verify current backup guidance, and preserve a tested recovery point. Retrieve the intended image only after confirming compatibility with your compose and environment files. A typical Compose refresh uses the following commands, but Pocket ID's release-specific migration and rollback instructions take precedence:
docker compose pull
docker compose up -d
docker compose ps
docker compose logsAfter an upgrade, repeat local sign-in, public sign-in, OIDC discovery or metadata consumption through a test client, callback handling, group authorization, and persistence checks. Confirm that the public issuer has not changed.
Stop the public endpoint when it is not needed
Use the Localtonet dashboard to stop the tunnel when public access is unnecessary. You can later start it again while retaining the configuration, or delete it if it is no longer needed. Remember that stopping the Localtonet tunnel does not stop Pocket ID locally, and stopping Pocket ID does not delete the tunnel configuration.
This separation is useful during maintenance. Stop the tunnel, perform the Pocket ID maintenance locally, verify the service, and then start the tunnel again. Finally, test the full public login path rather than assuming local success guarantees remote success.
Frequently asked questions
What is Pocket ID?
Pocket ID is a self-hosted OpenID Connect Certified and OAuth 2.0 provider. It lets users authenticate to compatible applications with passkeys and does not support password authentication. It also provides capabilities including group-based access control, LDAP integration, SCIM provisioning, audit logs, an administrative REST API, and scoped API access.
Why does this guide use Docker?
Pocket ID can be installed in multiple ways, but the project identifies Docker as its easiest and recommended setup method. Docker Compose also gives operators a repeatable way to validate configuration, start the service, inspect logs, restart it, and apply controlled image updates.
Which local port does Pocket ID use?
This article does not claim a default port because the supplied project evidence does not establish one, and deployment mappings can change. Use the exact published host port in the official compose configuration for your selected Pocket ID version. Verify that address locally and enter the same reachable target in the Localtonet HTTP tunnel.
Does Localtonet replace an OIDC reverse-proxy configuration?
No. Localtonet provides public network reachability for the local HTTP endpoint. Pocket ID must still be configured according to its current documentation for its canonical external URL and any required forwarded-request or reverse-proxy behavior. Relying applications must use matching issuer and redirect values.
Do I need router port forwarding or a public IP address?
No. The Localtonet client establishes an outbound connection to a Localtonet relay server. This allows the HTTP service to receive traffic through its public address without inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
Is a random public subdomain suitable for production OIDC?
A random subdomain is useful for evaluation, but an identity provider normally benefits from a stable address. Changing the hostname can require changes to Pocket ID's external URL, relying-application issuer settings, redirect registrations, and metadata expectations. Choose a retained address before onboarding production applications.
Why can the Localtonet client not reach Pocket ID when a browser on the host can?
Pocket ID may be bound only to the host's loopback interface. If the Localtonet client runs on a different device, that device cannot use the Pocket ID host's loopback address. Either run the Localtonet client on the same host or configure a trusted network path that makes the Pocket ID listener reachable from the selected client device, following the project's security guidance.
Does creating a Localtonet tunnel start it automatically?
No. Creating and starting are separate lifecycle actions. After saving the tunnel, press Start. The public address remains available only while the selected Localtonet client is connected and the tunnel is running.
Should I expose Pocket ID before testing it locally?
No. First validate the Docker configuration, confirm the container remains healthy, complete the documented administrator setup, test passkey sign-in, restart the deployment to verify persistence, and connect one test application. Public tunneling should be a distinct next step after the local service is known to work.
Publish your verified Pocket ID endpoint with Localtonet
Once Pocket ID works locally and its stable external URL is planned, run our client on a device that can reach it, create an HTTP tunnel, start the tunnel, and test the complete OIDC sign-in flow through the assigned public HTTPS address.
Get Started Free →
