OpenID Connect (OIDC)

Yopass supports OpenID Connect for user authentication. When configured, a Sign in button appears in the navbar and you can optionally restrict secret creation to authenticated users only.

Requires a valid license. OIDC is a premium feature gated behind --license-key. With no license key at all, the server refuses to start rather than silently ignoring --oidc-issuer. Once a license has been provided, expiry degrades gracefully instead of turning OIDC off — see expiry behavior.

How it works

A user clicks Sign in in the navbar.
The browser is redirected to /auth/login, which redirects to your OIDC provider.
After the user authenticates, the provider redirects back to /auth/callback.
Yopass exchanges the authorization code for tokens, reads the user's sub, email, and name from the UserInfo endpoint, and stores them in a signed, encrypted session cookie.
The navbar shows the user's name and a Sign out button.
Secrets can be created for public (unauthenticated) or internal (authenticated-only) consumption.

Flags

Flag	Env var	Default	Description
`--oidc-issuer`	`OIDC_ISSUER`	—	OIDC provider issuer URL
`--oidc-client-id`	`OIDC_CLIENT_ID`	—	OAuth2 client ID
`--oidc-client-secret`	`OIDC_CLIENT_SECRET`	—	OAuth2 client secret
`--oidc-redirect-url`	`OIDC_REDIRECT_URL`	—	Full callback URL (must match the provider)
`--require-auth`	`REQUIRE_AUTH`	`false`	Reject secret creation requests from unauthenticated users
`--oidc-session-key`	`OIDC_SESSION_KEY`	—	64-byte hex session key (see Multi-instance)
`--oidc-allowed-domains`	`OIDC_ALLOWED_DOMAINS`	—	Restrict OIDC logins and authenticated access to these email domains, comma-separated (e.g. `corp.example.com,example.com`)
`--oidc-require-verified-email`	`OIDC_REQUIRE_VERIFIED_EMAIL`	`true`	Require the provider to return `email_verified: true` for new logins
`--api-token`	`API_TOKEN`	—	Static bearer token(s) for machine clients, formatted as `name:secret` (see Machine-to-machine)

All three of --oidc-issuer, --oidc-client-id, and --oidc-redirect-url are required to enable OIDC.

Email verification

By default, new OIDC logins require email_verified: true in the provider's UserInfo response, even when no email domains are restricted. A missing or false claim returns 403 Forbidden and no session is created. API tokens are unaffected.

Check your provider's UserInfo claims. OIDC permits providers to omit email_verified; requesting the email scope does not guarantee it will be returned. The Microsoft identity platform UserInfo endpoint, for example, documents subject, name, and email claims without email_verified.

For providers that omit verification, administrators can explicitly disable this requirement with either:

--oidc-require-verified-email=false

or the environment variable:

OIDC_REQUIRE_VERIFIED_EMAIL=false

This opt-out accepts both missing and explicitly false verification claims. It does not bypass subject validation or --oidc-allowed-domains, and the server logs a startup warning when it is enabled with OIDC. Yopass then trusts the provider's email assertion without evidence of verification. Use it only when the provider controls the email attribute and application access appropriately.

For Microsoft Entra deployments, configure the intended tenant and restrict access to the Yopass application to the intended users or groups, including an explicit guest-access policy. Ensure users cannot supply an arbitrary allowed-domain email attribute. An email suffix alone does not establish organization membership. Do not enable the opt-out merely to make a login error disappear without checking these controls.

Example: Google as OIDC provider

1. Create a Google OAuth 2.0 client

Open Google Cloud Console and select your project (or create one).
Go to APIs & Services → Credentials.
Click Create Credentials → OAuth 2.0 Client ID.
Set the application type to Web application.
Under Authorized redirect URIs, add your callback URL:
```
https://yopass.example.com/auth/callback
```
Click Create. Copy the Client ID and Client Secret.

2. Run Yopass with OIDC enabled

yopass-server \
  --license-key   "your-license-key" \
  --oidc-issuer   "https://accounts.google.com" \
  --oidc-client-id     "123456789-abc.apps.googleusercontent.com" \
  --oidc-client-secret "GOCSPX-…" \
  --oidc-redirect-url  "https://yopass.example.com/auth/callback"

Or with environment variables:

LICENSE_KEY=your-license-key \
OIDC_ISSUER=https://accounts.google.com \
OIDC_CLIENT_ID=123456789-abc.apps.googleusercontent.com \
OIDC_CLIENT_SECRET=GOCSPX-… \
OIDC_REDIRECT_URL=https://yopass.example.com/auth/callback \
yopass-server

Yopass fetches Google's discovery document (https://accounts.google.com/.well-known/openid-configuration) at startup. If the provider is unreachable the server will not start.

Require authentication to create secrets

Add --require-auth to prevent unauthenticated users from creating secrets. They will see a Sign in prompt on the home page and the upload page. Secret retrieval links continue to work without authentication.

yopass-server \
  --license-key        "your-license-key" \
  --oidc-issuer        "https://accounts.google.com" \
  --oidc-client-id     "123456789-abc.apps.googleusercontent.com" \
  --oidc-client-secret "GOCSPX-…" \
  --oidc-redirect-url  "https://yopass.example.com/auth/callback" \
  --require-auth

Tip: Combine --require-auth with a --read-only public instance to create a two-tier deployment:

Instance	Flags	Purpose
Internal	`--require-auth`	Employees create secrets after signing in
Public	`--read-only`	Anyone can open a secret link

Both instances share the same database (Memcached or Redis).

Restricting by email domain

Use --oidc-allowed-domains to restrict OIDC logins to users whose email address belongs to one of the specified domains. Users from other domains receive 403 Forbidden at the login callback. Domain restrictions are also checked for existing sessions on authenticated creation and access to authentication-protected secrets.

yopass-server \
  --require-auth \
  --oidc-allowed-domains "corp.example.com,example.com" \
  # … other OIDC flags

Multiple domains can be specified as a comma-separated list.
The check is case-insensitive (Example.COM matches example.com).
Public secrets remain accessible with their secret links. Authentication-protected retrieval and deletion enforce the domain restriction.
Domain restrictions apply to OIDC login even without --require-auth. That flag separately requires authentication for creation.

Machine-to-machine API tokens

--require-auth gates secret creation on the interactive OIDC browser flow, which backend services and automation cannot complete. Use --api-token to give such clients a static bearer token instead:

# Generate a strong secret (minimum 16 characters enforced)
openssl rand -hex 32

yopass-server \
  --require-auth \
  --api-token "cmdb:4f6a…9c2e" \
  # … other OIDC flags

Multiple tokens are configured as a comma-separated list (cmdb:secret1,ops:secret2) or via the API_TOKEN environment variable. Each token has a name so audit logs record which service acted: creations authenticated by a token are attributed as service:<name> (e.g. service:cmdb).

The client sends the secret in the Authorization header:

curl https://yopass.example.com/create/secret \
  -H "Authorization: Bearer 4f6a…9c2e" \
  -H "Content-Type: application/json" \
  -d '{"message":"-----BEGIN PGP MESSAGE-----…","expiration":3600,"one_time":true}'

Notes:

API tokens grant access to the creation endpoints only (/create/secret, /create/file, and /request). Retrieving a secret marked require authentication still demands an interactive session.
Tokens are service accounts, so --oidc-allowed-domains does not apply to them.
--api-token requires --require-auth; without it the creation endpoints are open and the flag is rejected at startup.
Treat token secrets like passwords: pass them via the API_TOKEN environment variable or a config file rather than command-line flags where possible, and rotate them by restarting with a new value.

Multi-instance deployments

Session cookies are signed and encrypted with keys generated randomly at startup. This means sessions created by one instance cannot be validated by another — users will be logged out whenever a request hits a different server.

To share sessions across instances, generate a fixed 64-byte key and set it on every instance:

# Generate once and store securely
openssl rand -hex 64
# → e.g. 3f2a1b…c9d8e7  (128 hex characters)

Then pass it to every instance:

yopass-server \
  --oidc-session-key "3f2a1b…c9d8e7" \
  # … other OIDC flags

Or as an environment variable:

OIDC_SESSION_KEY=3f2a1b…c9d8e7 yopass-server …

Keep this value secret. Treat it like a password — rotate it if it is ever exposed (all active sessions will be invalidated when it changes). An empty key uses ephemeral per-instance keys; a nonempty key must be exactly 128 hexadecimal characters or the server will refuse to start.

Docker Compose example

services:
  yopass:
    image: jhaals/yopass:latest
    ports:
      - "1337:1337"
    environment:
      MEMCACHED: memcached:11211
      LICENSE_KEY: your-license-key
      OIDC_ISSUER: https://accounts.google.com
      OIDC_CLIENT_ID: 123456789-abc.apps.googleusercontent.com
      OIDC_CLIENT_SECRET: GOCSPX-…
      OIDC_REDIRECT_URL: https://yopass.example.com/auth/callback
      REQUIRE_AUTH: "true"
      OIDC_ALLOWED_DOMAINS: example.com  # optional: comma-separated list of allowed email domains
      OIDC_SESSION_KEY: 3f2a1b…c9d8e7   # required for replicated deployments
    depends_on:
      - memcached

  memcached:
    image: memcached

Other OIDC providers

Use a provider that implements OpenID Connect Discovery and supplies subject and email claims through UserInfo. By default, it must also supply email_verified: true; see email verification. Set --oidc-issuer to the provider's issuer URL.

Session cookies are ignored on API requests initiated by foreign origins and on GET navigations. The bundled frontend uses fetch requests; split-origin frontends must send an Origin matching --frontend-url. Direct browser navigation to an authentication-protected secret/file API URL returns 401; use the frontend share link instead. CLI clients without browser metadata and API-token authentication remain supported.

Fetch Metadata normally requires HTTPS. Requests without both Origin and Fetch Metadata remain accepted for non-browser compatibility. Keep --prefetch-secret=true for the reveal confirmation on one-time frontend links; with it disabled, navigating to a frontend link intentionally retrieves the secret automatically. Origin checks cannot prevent that frontend-initiated action.

How it works​

Flags​

Email verification​

Example: Google as OIDC provider​

1. Create a Google OAuth 2.0 client​

2. Run Yopass with OIDC enabled​

Require authentication to create secrets​

Restricting by email domain​

Machine-to-machine API tokens​

Multi-instance deployments​

Docker Compose example​

Other OIDC providers​

Cookie authority and browser origins​