Skip to content
Drydock
ConfigurationAuthenticationOIDC

OpenID Connect Authentication

The oidc authentication lets you protect drydock access using the OpenID Connect standard.

logo

Variables

Env varRequiredDescriptionSupported valuesDefault value when missing
DD_AUTH_OIDC_{auth_name}_CLIENTID🔴Client ID
DD_AUTH_OIDC_{auth_name}_CLIENTSECRET🔴Client Secret
DD_AUTH_OIDC_{auth_name}_DISCOVERY🔴OIDC discovery URL
DD_AUTH_OIDC_{auth_name}_CAFILE⚪Path to a PEM CA certificate (or chain) used for OIDC HTTPS requestsFile pathempty
DD_AUTH_OIDC_{auth_name}_INSECURE⚪Disable TLS certificate verification for OIDC HTTPS requests (development only)true, falsefalse
DD_AUTH_OIDC_{auth_name}_REDIRECT⚪Skip internal login page & automatically redirect to the OIDC providertrue, falsefalse
DD_AUTH_OIDC_{auth_name}_LOGOUTURL⚪Explicit IdP logout URL fallback when discovery metadata has no end_session_endpointURLempty
DD_AUTH_OIDC_{auth_name}_TIMEOUT⚪Timeout (in ms) when calling the OIDC providerMust be greater than 5005000
DD_AUTH_OIDC_{auth_name}_BEARER⚪Accept OIDC access tokens as Authorization: Bearer on API requests (see Bearer tokens)true, falsefalse
DD_AUTH_OIDC_{auth_name}_BEARERAUDIENCES⚪Extra aud values accepted on bearer access tokens, besides the client ID (see Bearer tokens)Comma-separated listempty
DD_AUTH_OIDC_{auth_name}_ALLOWEDEMAILS⚪Only these email addresses may sign in (see Restricting who can sign in)Comma-separated list, case-insensitiveempty (no restriction)
DD_AUTH_OIDC_{auth_name}_ALLOWEDEMAILDOMAINS⚪Only addresses at these domains may sign inComma-separated list, case-insensitiveempty (no restriction)
DD_AUTH_OIDC_{auth_name}_REQUIREDGROUP⚪The user must belong to this groupGroup name, exact matchempty (no restriction)
DD_AUTH_OIDC_{auth_name}_GROUPCLAIM⚪Claim that carries the user's groupsClaim namegroups
DD_PUBLIC_URL🔴Public URL of your drydock instance (used to build the OIDC callback URL)URL

The callback URL (to configure in the IDP) is built as ${DD_PUBLIC_URL}/auth/oidc/${auth_name}/cb.

OIDC configuration requirements:

  • DD_PUBLIC_URL is required — Without it, the OIDC provider will fail to register at startup and the login page will show "No authentication methods configured". Check startup logs for the exact error.
  • HTTPS discovery is required — http:// OIDC discovery URLs are rejected as of v1.6. Migrate your IdP to HTTPS; INSECURE only relaxes certificate verification for HTTPS and does not re-enable HTTP.
  • INSECURE is for dev only — DD_AUTH_OIDC_{auth_name}_INSECURE=true disables TLS certificate verification for OIDC HTTPS calls (discovery, token, userinfo, JWKS). Use only for local/dev troubleshooting.

Notes:

  • If your IdP is on a different domain and callback fails with OIDC session is missing or expired, check DD_SERVER_COOKIE_SAMESITE (server config). Default is lax for OIDC compatibility; strict can break cross-site callbacks. Use none only for explicit cross-site/embed cases over HTTPS.
  • If your provider uses a private/self-signed CA, the quickest container-level workaround is NODE_EXTRA_CA_CERTS=/path/to/ca.pem. Drydock also supports OIDC-scoped TLS settings with DD_AUTH_OIDC_{auth_name}_CAFILE and DD_AUTH_OIDC_{auth_name}_INSECURE.
  • Node 24 compatibility — DD_AUTH_OIDC_{auth_name}_CAFILE and DD_AUTH_OIDC_{auth_name}_INSECURE=true both require a custom TLS dispatcher. Drydock uses fetch from userland undici when a custom dispatcher is needed to avoid a Node 24 / undici v7 vs v8 dispatcher mismatch that caused opaque TypeError: fetch failed errors in prior releases. No configuration is needed — the fix is automatic.
  • Redirect URL validation — Post-login redirects are validated against the backend's endpoint allowlist. OIDC flows cannot be hijacked into landing on arbitrary paths. No configuration is needed.
  • OIDC error log redaction — OIDC warn logs redact RFC-1918 IP addresses ([internal-addr]) and absolute filesystem paths ([path]) from error cause chains so private network addresses and CA certificate file paths do not appear in centralized log aggregators.
  • OIDC logout URL resolution — drydock first tries the provider discovery end_session_endpoint. If it is missing, you can set DD_AUTH_OIDC_{auth_name}_LOGOUTURL when your provider (or proxy) exposes a logout URL outside discovery metadata. If neither is available, POST /auth/logout only destroys the local drydock session.

Restricting who can sign in

By default every user your IdP authenticates can sign in. Set any of these options to narrow that:

DD_AUTH_OIDC_KEYCLOAK_ALLOWEDEMAILDOMAINS=example.com
DD_AUTH_OIDC_KEYCLOAK_REQUIREDGROUP=drydock-users
  • Email and domain lists are alternatives. A user is admitted when their email is in ALLOWEDEMAILS or its domain is in ALLOWEDEMAILDOMAINS. Matching is case-insensitive. A domain matches exactly, so example.com does not admit sub.example.com.
  • Verified email. When an email list is set, the IdP must supply an email claim, and if it also supplies email_verified that value must be true. An unverified address is denied. If the IdP sends no email_verified claim at all, the email is accepted as is.
  • Required group. The user's groups are read from the claim named by GROUPCLAIM (default groups), in the userinfo response or the ID token. The claim can be an array of strings or a single string; a string is split on commas and whitespace. The group name must match exactly, including case.
  • Both together. If an email or domain list and a required group are set, the user must pass both.
  • Bearer tokens are held to the same rules, because the same userinfo claims are checked.

A denied user gets a 403 with Access denied and no session. Drydock logs the reason (for example required group is missing) as a warning, without the user's email, groups or any token. If everyone is denied, check that your IdP actually releases the groups claim to the drydock client, usually through a scope or claim mapping.

Bearer tokens

Bearer authentication is off by default. Set DD_AUTH_OIDC_{auth_name}_BEARER=true and an OIDC access token sent as Authorization: Bearer <token> authenticates API requests, in addition to the browser login. While it is off, a Bearer token is rejected like any unauthenticated request and Drydock logs a rate-limited warning naming the variable. Once on, Drydock only accepts a token that the configured IdP issued for this drydock client. A token the same IdP minted for a different application is rejected with 401, even though the IdP would still answer a userinfo call for it.

How a token is checked:

  • JWT access tokens are verified against the IdP's jwks_uri signature keys. The iss must match the discovery issuer, exp and nbf are enforced with 30 seconds of clock skew, and the token must be bound to this client: aud contains the client ID, or azp or client_id equals the client ID.
  • Opaque access tokens are checked with RFC 7662 introspection when discovery advertises an introspection_endpoint, authenticated with the client ID and secret. The response must have active: true and the same issuer, expiry and client binding rules apply (client_id, azp or aud).
  • Neither available: the token is rejected and a warning is logged. Drydock does not fall back to accepting a token on a userinfo call alone.

Once a token passes, the userinfo endpoint is used only to map it to a username.

DD_AUTH_OIDC_KEYCLOAK_BEARER=true
# Only when the IdP puts a separate API audience on the token:
DD_AUTH_OIDC_KEYCLOAK_BEARERAUDIENCES=api://drydock

If your IdP puts a separate API audience on the access token instead of the client ID, list it in DD_AUTH_OIDC_{auth_name}_BEARERAUDIENCES, for example DD_AUTH_OIDC_ENTRA_BEARERAUDIENCES=api://<drydock_app_id>. Extra audiences are matched against aud only.

IdPWhat to check
KeycloakAccess tokens carry azp set to the client ID, so nothing extra is needed.
AuthentikAccess tokens carry the provider's client ID in aud, so nothing extra is needed. Keep the provider's signing key set so tokens are JWTs.
Microsoft Entra IDTokens issued to the drydock app registration have aud set to the application ID or api://<application_id>. Add the api://... form to BEARERAUDIENCES if that is what your tokens carry.
As of v1.8, bearer authentication is opt-in, and tokens issued for other clients stop working. Machine clients that reuse a token minted for another application must request one for the drydock client (or for an audience listed in BEARERAUDIENCES). See DEPRECATIONS.

How to integrate with Authelia

logo

Configure an Openid Client for drydock in Authelia configuration.yml (see official authelia documentation)

identity_providers:
  oidc:
    hmac_secret: <a-very-long-string>
    issuer_private_key: |
      YOUR_OIDC_SIGNING_PRIVATE_KEY
    access_token_lifespan: 1h
    authorize_code_lifespan: 1m
    id_token_lifespan: 1h
    refresh_token_lifespan: 90m
    clients:
      - client_id: my-drydock-client-id
        client_name: drydock openid client
        client_secret: this-is-a-very-secure-secret
        public: false
        authorization_policy: one_factor
        audience: []
        scopes:
          - openid
          - profile
          - email
        redirect_uris:
          - https://<your_drydock_public_domain>/auth/oidc/authelia/cb
        grant_types:
          - refresh_token
          - authorization_code
        response_types:
          - code
        response_modes:
          - form_post
          - query
          - fragment
        userinfo_signing_algorithm: none

Configure drydock

services:
  drydock:
    image: codeswhat/drydock:1.9.0-rc.1
    ...
    environment:
      - DD_PUBLIC_URL=https://<your_drydock_public_domain>
      - DD_AUTH_OIDC_AUTHELIA_CLIENTID=my-drydock-client-id
      - DD_AUTH_OIDC_AUTHELIA_CLIENTSECRET=this-is-a-very-secure-secret
      - DD_AUTH_OIDC_AUTHELIA_DISCOVERY=https://<your_authelia_public_domain>/.well-known/openid-configuration

image

image

How to integrate with Auth0

logo

Create an application (Regular Web Application)

  • Allowed Callback URLs: https://<your_drydock_public_domain>/auth/oidc/auth0/cb

Configure drydock

services:
  drydock:
    image: codeswhat/drydock:1.9.0-rc.1
    ...
    environment:
      - DD_PUBLIC_URL=https://<your_drydock_public_domain>
      - DD_AUTH_OIDC_AUTH0_CLIENTID=<paste the Client ID from auth0 application settings>
      - DD_AUTH_OIDC_AUTH0_CLIENTSECRET=<paste the Client Secret from auth0 application settings>
      - DD_AUTH_OIDC_AUTH0_DISCOVERY=https://<paste the domain from auth0 application settings>/.well-known/openid-configuration

image

image

How to integrate with Authentik

logo

On Authentik, create a provider with type Oauth2/OpenID (or configure an existing one)

image

Important values

  • Client Type: Confidential
  • Client ID: <generated value>
  • Client Secret: <generated value>
  • Redirect URIs/Origins: https://<your_drydock_public_domain>/auth/oidc/authentik/cb
  • Scopes: email, openid, profile

On Authentik, create an application associated to the previously created provider

image

Configure drydock

services:
  drydock:
    image: codeswhat/drydock:1.9.0-rc.1
    ...
    environment:
      - DD_PUBLIC_URL=https://<your_drydock_public_domain>
      - DD_AUTH_OIDC_AUTHENTIK_CLIENTID=<paste the Client ID from authentik drydock_oidc provider>
      - DD_AUTH_OIDC_AUTHENTIK_CLIENTSECRET=<paste the Client Secret from authentik drydock_oidc provider>
      - DD_AUTH_OIDC_AUTHENTIK_DISCOVERY=<authentik_url>/application/o/<authentik_application_name>/.well-known/openid-configuration
      # - DD_AUTH_OIDC_AUTHENTIK_REDIRECT=true # optional (to skip internal login page)
Authentik token encryption — In the Authentik provider's Advanced protocol settings, ensure the Encryption Key is unset ("Select an encryption key..."). Drydock does not support JWE (encrypted) tokens. If an encryption key is selected, Authentik will encrypt the ID token and Drydock will fail to validate it.
Self-signed certificates — If your Authentik instance uses a self-signed certificate, use DD_AUTH_OIDC_AUTHENTIK_INSECURE=true to skip TLS verification for OIDC calls only (does not affect registry or webhook TLS). Alternatively, mount the CA certificate and use DD_AUTH_OIDC_AUTHENTIK_CAFILE=/path/to/ca.pem. For the CAFILE approach, ensure the PEM file contains the full certificate chain (not just the leaf certificate).

How to integrate with Dex

Dex does not currently advertise end_session_endpoint in discovery metadata. Without an explicit DD_AUTH_OIDC_DEX_LOGOUTURL, POST /auth/logout clears only the local drydock session. Set DD_AUTH_OIDC_DEX_LOGOUTURL only if you have a real IdP logout endpoint in front of Dex (for example, via your auth proxy/portal).
services:
  drydock:
    image: codeswhat/drydock:1.9.0-rc.1
    ...
    environment:
      - DD_PUBLIC_URL=https://<your_drydock_public_domain>
      - DD_AUTH_OIDC_DEX_CLIENTID=<dex_client_id>
      - DD_AUTH_OIDC_DEX_CLIENTSECRET=<dex_client_secret>
      - DD_AUTH_OIDC_DEX_DISCOVERY=https://<your_dex_public_domain>/dex/.well-known/openid-configuration
      # Optional: only when a real IdP logout endpoint exists
      # - DD_AUTH_OIDC_DEX_LOGOUTURL=https://<your_logout_endpoint>