Pocket ID

To use Pocket ID for user authentication, create a new OAuth2 Client (application) and configure the callback to https://<endpoint>/portals/<portal>/oauth2/callback (see examples depending on how Traefik Forward Auth is exposed).

Configure a provider with these options in the pocketID property:

endpoint: Pocket ID server endpoint.
This is generally a URL like https://pocketidid.example.com.
clientID: Client ID of your application
clientSecret: Client secret of your application

The Pocket ID provider supports additional configuration options that can be helpful to configure how Traefik Forward Auth communicates with the Pocket ID:

tlsInsecureSkipVerify: If true, skips validating TLS certificates when communicating with Pocket ID. While this option can enable support for self-signed TLS certificates, it should be used with caution.
tlsCACertificatePEM: PEM-encoded CA certificate used when communicating with Pocket ID.
tlsCACertificatepath: Path to a file containing the PEM-encoded CA certificate used when communicating with Pocket ID.

Full configuration example#

The following is a complete tfa-config.yaml example using Pocket ID as the authentication provider.

# tfa-config.yaml
server:
  # Domain(s) served by Traefik Forward Auth
  # `domain` is the cookie domain (the domain where the app is reachable, or a parent domain)
  # `authHost` is the public hostname of Traefik Forward Auth itself (omit it when using "sub-path" mode)
  domains:
    - domain: "example.com"
      authHost: "auth.example.com"

portals:
  - name: "main"
    providers:
      # Configure authentication with Pocket ID
      - pocketID:
          endpoint: "https://pocketidid.example.com"
          clientID: "your-client-id"
          clientSecret: "your-client-secret"

          # Recommended on supported platforms: use a Federated Client Credential instead of `clientSecret`
          # See "Using Federated Client Credentials" below for details
          #clientAssertion: "AzureManagedIdentity"

          # Optional: TLS configuration for communicating with Pocket ID
          #tlsInsecureSkipVerify: false
          #tlsCACertificatePEM: ""
          #tlsCACertificatePath: ""

Full list of configuration options for Pocket ID

Using Federated Client Credentials#

Using Federated Client Credentials is an alternative to configuring your Pocket ID application with a client secret. This offers better security because there are no pre-shared secrets to manage, and easier maintenance since client secrets need to be rotated periodically.

Using Federated Client Credentials is the recommended approach when:

The application is running on Azure on a platform that supports Managed Identity. Both system-assigned and user-assigned identities are supported.
The application is running on platforms that support Workload Identity Federation, for example on Kubernetes (on any cloud or on-premises) or other clouds.
The application is running on Kubernetes and can use service account tokens.
The application is running on a node connected to a Tailscale network and you have deployed tsiam.

To use Federated Client Credentials, you first need to configure your OAuth2 Client in Pocket ID, as described in the official documentation.

Finally, configure Traefik Forward Auth by setting a value for clientAssertion:

AzureManagedIdentity: uses Azure Managed Identity with a system-assigned identity
AzureManagedIdentity=client-id: uses Azure Managed Identity with a user-assigned identity whose client id is “client-id” (e.g. “AzureManagedIdentity=00000000-0000-0000-0000-000000000000”)
AzureWorkloadIdentity: uses Azure Workload Identity, e.g. in Kubernetes
KubernetesServiceAccountToken=path: uses a token read from a Kubernetes service account token file. If path is omitted, defaults to /var/run/secrets/kubernetes.io/serviceaccount/token.
tsiam=endpoint: uses tsiam to obtain Workload Identity from nodes that use Tailscale. Specify the endpoint of tsiam as value, e.g. tsiam=https://tsiam. Uses as resource name the value of endpoint.