oidc-discovery-provider

SPIRE OIDC Discovery Provider

The SPIRE OIDC Discovery Provider is a small helper that provides a minimal implementation of a subset of the OIDC discovery document as related to exposing a JSON Web Key Set (JWKS) for JSON Web Token (JWT) validation.

It provides the following endpoints:

The provider by default relies on ACME to obtain TLS certificates that it uses to serve the documents securely.

Configuration

Command Line Configuration

The provider has the following command line flags:

HCL Configuration

The configuration file is required by the provider. It contains HCL encoded configurables.

Considerations for Unix platforms

[1]: One of acme, serving_cert_file or listen_socket_path must be defined.

[3]: The allow_insecure_scheme should only be used in a local development environment for testing purposes. It only works in conjunction with insecure_addr or listen_socket_path.

Considerations for Windows platforms

[1]: One of acme, serving_cert_file or listen_named_pipe_name must be defined.

[3]: The allow_insecure_scheme should only be used in a local development environment for testing purposes. It only works in conjunction with insecure_addr or listen_named_pipe_name.

Considerations for all platforms

[2]: One of server_api or workload_api must be defined. The provider relies on one of these two APIs to obtain the public key material used to construct the JWKS document.

The domains configurable contains the list of domains the provider is expected to be served from. If a request is received from a domain other than one in the list (as determined by the Host or X-Forwarded-Host header), it will be rejected. Likewise, when ACME is used, the domains list contains the allowed domains for which certificates will be obtained. The TLS handshake will terminate if another domain is requested.

[4]: SPIRE OIDC Discovery provider monitors and reloads the files provided in the serving_cert_file configuration at runtime.

ACME Section

Serving Certificate Section

Server API Section

Workload API Section

Health Checks Section

Health checks are enabled by adding health_checks {} to the configuration. The health checks endpoints are hosted on a dedicated listener on localhost.

• The "ready" state is determined by the availability of keys fetched via the workload/server API. If the keys where fetched successfully but can't be fetched anymore (e.g. workload or server API can't be reached), the server is still determined ready for the threshold interval.
• The "live" state is either determined by the availability of keys fetched via the workload/server API or the threshold interval after the server started serving requests. If the keys where fetched successfully but can't be fetched anymore (e.g. workload/server API can't be reached), the server is still determined live for the threshold interval.

The threshold interval is currently set to 5 times the workload/server APIs poll interval, but at least 3 minutes. Both states respond with a 200 OK status code for success or 500 Internal Server Error for failure.

Examples (Unix platforms)

Server API and ACME

log_level = "debug"
domains = ["mypublicdomain.test"]
acme {
    cache_dir = "/some/path/on/disk/to/cache/creds"
    email = "email@domain.test"
    tos_accepted = true
}
server_api {
    address = "unix:///tmp/spire-server/private/api.sock"
}

Workload API and ACME

log_level = "debug"
domains = ["mypublicdomain.test"]
acme {
    cache_dir = "/some/path/on/disk/to/cache/creds"
    email = "email@domain.test"
    tos_accepted = true
}
workload_api {
    socket_path = "/tmp/spire-agent/public/api.sock"
    trust_domain = "domain.test"
}

Server API and Serving Certificate

log_level = "debug"
domains = ["mypublicdomain.test"]
serving_cert_file {
 cert_file_path = "/some/path/on/disk/to/cert.pem"
 key_file_path = "/some/path/on/disk/to/key.pem"
}
server_api {
    address = "unix:///tmp/spire-server/private/api.sock"
}

Workload API and Serving Certificate

log_level = "debug"
domains = ["mypublicdomain.test"]
serving_cert_file {
 cert_file_path = "/some/path/on/disk/to/cert.pem"
 key_file_path = "/some/path/on/disk/to/key.pem"
}
workload_api {
    socket_path = "/tmp/spire-agent/public/api.sock"
    trust_domain = "domain.test"
}

Listening on a Unix Socket

The following configuration has the OIDC Discovery Provider listen for requests on the given socket. This can be used in conjunction with a webserver like Nginx, Apache, or Envoy which supports reverse proxying to a unix socket.

log_level = "debug"
domains = ["mypublicdomain.test"]
listen_socket_path = "/run/oidc-discovery-provider/server.sock"

workload_api {
    socket_path = "/tmp/spire-agent/private/api.sock"
    trust_domain = "domain.test"
}

A minimal Nginx configuration that proxies all traffic to the OIDC Discovery Provider's socket might look like this.

daemon off;
 events {}
 http {
   access_log /dev/stdout;
   upstream oidc {
     server unix:/run/oidc-discovery-provider/server.sock;
   }
   server {
     # ... Any TLS and listening config you may need
     location / {
       proxy_pass http://oidc;
     }
   }
 }

Examples (Windows)

Server API and ACME

log_level = "debug"
domains = ["mypublicdomain.test"]
acme {
    cache_dir = "c:\\some\\path\\on\\disk\\to\\cache\\creds"
    email = "email@domain.test"
    tos_accepted = true
}
server_api {
    experimental {
        named_pipe_name = "\\spire-server\\private\\api"
    }
}

Workload API and ACME

log_level = "debug"
domains = ["mypublicdomain.test"]
acme {
    cache_dir = "c:\\some\\path\\on\\disk\\to\\cache\\creds"
    email = "email@domain.test"
    tos_accepted = true
}
workload_api {
    experimental {
        named_pipe_name = "\\spire-agent\\public\\api"
    }
    trust_domain = "domain.test"
}

Server API and Serving Certificate

log_level = "debug"
domains = ["mypublicdomain.test"]
serving_cert_file {
    cert_file_path = "c:\\some\\path\\on\\disk\\to\\cert.pem"
    key_file_path = "c:\\some\\path\\on\\disk\\to\\key.pem"
}
server_api {
    experimental {
        named_pipe_name = "\\spire-server\\private\\api"
    }
}

Workload API and Serving Certificate

log_level = "debug"
domains = ["mypublicdomain.test"]
serving_cert_file {
 cert_file_path = "c:\\some\\path\\on\\disk\\to\\cert.pem"
 key_file_path = "c:\\some\\path\\on\\disk\\to\\key.pem"
}
workload_api {
    experimental {
        named_pipe_name = "\\spire-agent\\public\\api"
    }
    trust_domain = "domain.test"
}

Listening on a Named Pipe

The following configuration has the OIDC Discovery Provider listen for requests on the given named pipe. This can be used in conjunction with a webserver that supports reverse proxying to a named pipe.

log_level = "debug"
domains = ["mypublicdomain.test"]
experimental {
    listen_named_pipe_name = "oidc-discovery-provider"
}

workload_api {
    experimental {
        named_pipe_name = "\\spire-agent\\public\\api"
    }
    trust_domain = "domain.test"
}