Authentication

查看 Markdown查看 Markdown

Public API authentication is off by default. Configure auth.authenticators to require a bearer credential on every FlowService and WorkerTaskService call. gRPC health needs no credential. Authenticators are tried in order.

auth:
  authenticators:
    - kind: jwt
      issuer: https://issuer.example.com
      audiences: ["dex"]
      adminAudiences: []
      jwksURL: ""
      allowInsecureJWKSURL: false
      caFile: ""
    - kind: staticTokens
      file: /etc/dex-server-zd/tokens.yaml

allowInsecureJWKSURL allows a plain HTTP jwksURL on a trusted network. An empty jwksURL discovers the key set through the issuer's OpenID configuration. caFile adds a PEM bundle to the system roots. adminAudiences lists the audiences that authorize admin calls.

The static token file lists SHA-256 hashes, never plaintext tokens:

tokens:
  - sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

The file must be valid at startup. Changes take effect within a second. A malformed update keeps the last valid content. An empty or missing file revokes every token.

The server checks a credential once, when a call starts. An open pull Worker stream stays open after its token expires or is revoked. The Worker needs a valid credential when it reconnects.

api.listen serves plaintext gRPC, so bearer credentials cross the network in clear text. Terminate TLS in front of the server, or restrict the network to trusted callers.

Admin credentials

Admin calls, such as describe and step down, need their own credential. Each jwt authenticator can list adminAudiences: the JWT audiences that make a token of its issuer an admin credential. The list is empty by default, so no issuer authorizes admin calls until you configure one.

auth:
  authenticators:
    - kind: jwt
      issuer: https://issuer.example.com
      audiences: ["dex"]
      adminAudiences: ["dex-operators"]

When auth.authenticators is not empty, an admin call needs a JWT that its issuer's jwt authenticator accepts. One of the token's audiences must be in that authenticator's adminAudiences. Static tokens never authorize admin calls. A missing or invalid credential fails with UNAUTHENTICATED. A valid public API credential without an admin audience fails with PERMISSION_DENIED.

Give adminAudiences only to an issuer that decides the audiences of its tokens itself. Never give them to an issuer that lets callers choose aud, such as Kubernetes projected service account tokens or a CI OIDC provider shared with other projects. Anyone who can get a token from such an issuer could ask for an admin audience and step the node down.

adminAudiences applies only to jwt authenticators. Its entries must not be empty and must differ from the same authenticator's audiences, so a public API credential never authorizes an admin call.

An issuer that only signs admin credentials can leave audiences empty when adminAudiences is set. Its tokens then never authorize FlowService or WorkerTaskService calls. If that issuer is the only authenticator, public API authentication is still on, so every FlowService and Worker call is denied.

The API key exchange of dexcli sends only the server ID and the API key, so it cannot ask for an admin audience. An API key works for admin commands only if the token endpoint itself issues tokens with an admin audience for that key.

When authentication is off, as on a local development server, admin calls need no credential. Anyone who can reach api.listen can then step the node down, again and again.

server-zd validates adminAudiences at startup. It logs each authorized admin call with the caller's iss and sub claims. It logs denied admin calls as warnings, at most once every 10 seconds.