DOCSEARCHbyAlgolia
Submit Docs

Pocket ID Documentation

repository·main·Indexed 26 days ago

https://github.com/pocket-id/pocket-id

Pocket ID is an OIDC Certified™ and OAuth 2.0 provider focusing on passkey-only authentication for a passwordless login experience. It is designed for securing self-hosted services and applications, with recommended deployment via Docker and Docker Compose using the pocketid/pocket-id:v2 image.

Tokens
1K
Snippets
1
Records
8
Agent score
94%

What's inside Pocket ID

  1. Overview of Pocket ID

    main
    Pocket ID is an OpenID Connect (OIDC) Certified™ and OAuth 2.0 provider designed for simplicity. It allows users to sign in to applications using passkeys, eliminating the need for traditional passwords. This makes it suitable for securing self-hosted services using hardware like Yubikeys.

  3. Run the Pocket ID server

    main
    The Pocket ID backend is a CLI-driven application. When executed, it first validates the environment configuration via common.ValidateEnvConfig. If the configuration is valid, it proceeds to execute the command-line interface defined in cmds.Execute(). Ensure all required environment variables are set before running the binary to avoid configuration errors.

  4. Deploy Pocket ID using Docker Compose

    main

    You can deploy Pocket ID using a docker-compose.yml file. The service uses the pocketid/pocket-id:v2 image (or ghcr.io/pocket-id/pocket-id:v2).

    Key configuration details:

    • Ports: The service listens on port 1411 by default. The host port is mapped to 1411.
    • Persistence: Data is persisted by mounting a local ./data directory to /app/data inside the container.
    • Environment Variables: Configuration is managed via an .env file.
    • Healthcheck: An optional healthcheck is provided using the /app/pocket-id healthcheck command.
    services:
  pocket-id:
    image: pocketid/pocket-id:v2 # or ghcr.io/pocket-id/pocket-id:v2
    restart: unless-stopped
    env_file: .env
    ports:
      - 1411:1411
    volumes:
      - "./data:/app/data"
    # Optional healthcheck
    healthcheck:
      test: [ "CMD", "/app/pocket-id", "healthcheck" ]
      interval: 1m30s
      timeout: 5s
      retries: 2
      start_period: 10s

  5. Interact with the OIDC Client interface

    main

    The Client type provides methods to retrieve OIDC configuration and metadata required for authentication flows. It wraps a model.OidcClient and provides specific implementations for scopes, grant types, and redirect URIs compatible with the fosite library.

    Key methods include:

    • GetID(): Returns the unique client identifier.
    • GetHashedSecret(): Returns the client secret as a byte slice.
    • GetRedirectURIs(): Returns the list of allowed callback URLs.
    • GetGrantTypes(): Returns supported grant types (Authorization Code, Refresh Token, and Device Code are always included; Client Credentials is included only if the client is not public).
    • GetScopes(): Returns the standard OIDC scopes (openid, profile, email, groups, offline_access) plus any additional apiScopes configured for the client.
    • GetAudience(): Returns the client ID and any additional apiAudiences configured.
    • IsPublic(): Indicates if the client is a public client (no secret required).

  7. Retrieve supported OIDC grant types from a Client

    main

    The GetGrantTypes() method returns the allowed OAuth2/OIDC grant types for a specific client.

    • Always included: authorization_code, refresh_token, and device_code.
    • Conditional: client_credentials is only included if IsPublic() returns false (i.e., for confidential clients).