From 27df9c89904e8e09a75ce78a9849833e3f9cbfaa Mon Sep 17 00:00:00 2001 From: Will Stranton <2659963+willstranton@users.noreply.github.com> Date: Thu, 18 Sep 2025 05:07:25 +0000 Subject: [PATCH] Add documentation for all module config directives --- README.md | 123 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 106 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 634a7bd..1df7c8f 100644 --- a/README.md +++ b/README.md @@ -8,31 +8,120 @@ User Info endpoint. ## Configuration -TODO +The following module directives are set under an NGINX `location` block. -`OpenIDCProvider` -Configures the OpenID Connect Provider settings. +### OpenIDCProvider -`OpenIDCClient` -Configures the OpenID Connect Client settings. +`OpenIDCProvider (file|string|url) [session=];` -`OpenIDCClaim` -Populates configuration variables based on available claims. +Configures the OpenID Connect Provider config. The `provider-config-json` can be provided as a local `file`, a `string` containing the JSON object, or a `url` to the JSON config. Identity providers supporting discovery will have this JSON config available under the path `/.well-known/openid-configuration`. -`OpenIDCCryptoPassphrase` -Set the passphrase used for encryption of cache, cookies, state etc. +Example: -`OpenIDCCache` -Configures a (default or named) cache backend. +``` +# 3 different ways to provide the config: +OpenIDCProvider file /etc/nginx/conf.d/provider.json; +OpenIDCProvider string '{"issuer":"https://keycloak.example.com", ...}'; +OpenIDCProvider url https://accounts.google.com/.well-known/openid-configuration; +``` -`OpenIDCSession` -Configures the session type and options, e.g. cache/cookie, session duration, etc. +### OpenIDCClient -`OpenIDCConfig` -Configures global setting such as redirect URI, etc. +`OpenIDCClient (string|json|file) [ssl_verify=on|off];` -```nginx - ``` +Configures the OpenID Connect Client settings. The `client-config` can be provided as a `string` that is form-encoded (eg. `key1=value1&key2=value2`), a `json` string, or a local `file` containing a JSON object. The keys that are required to be set in the config are: + + * `client_id` - the client identifier + * `client_secret` - the client password for authentication + * `scope` - request that specific sets of information be made available as Claim Values. Multiple scope values are space-delimited. OpenID Connect requests MUST contain the `openid` scope value. + * `token_endpoint_auth_method` - how the client should authenticate. Supported values are: `none`, `client_secret_basic`, `client_secret_post`, `client_secret_jwt`, `private_key_jwt`, `client_cert`, `basic`. + +Example: +``` +# 3 different ways to provide the client settings: +OpenIDCClient string client_id=myapp&client_secret=3GrV8... ssl_verify=off; +OpenIDCClient json '{"client_id": "myapp", "client_secret": "3GrV8...", ...}' ssl_verify=off; +OpenIDCClient file /etc/nginx/conf.d/client.json ssl_verify=off; +``` + +### OpenIDCClaim + +`OpenIDCClaim $;` + +Populates configuration variables based on available claims from the [ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken). Refer to your provider's documentation for the available fields/claims available. Each line of `OpenIDCClaim` maps one claim to one variable (i.e. to map 3 variables, you will need 3 config lines). + +Example: +``` +# Mapping three different claims: +OpenIDCClaim iss $pfc_claim_iss; +OpenIDCClaim sub $pfc_claim_sub; +OpenIDCClaim aud $pfc_claim_aud; +``` + +### OpenIDCCryptoPassphrase + +`OpenIDCCryptoPassphrase ;` + +Set the passphrase used for encryption of cache, cookies, state etc. Optional - if a passphrase isn't set, a random passphrase will be generated each time the NGINX server is started. + +Example: +``` +OpenIDCCryptoPassphrase fde1afb7063f; +``` + +### OpenIDCCache + +`OpenIDCCache [form-encoded-options];` + +Configures a (default or named) cache backend. Optional - defaults to `shm`. Form-encoded options include: + +* `key_hash_algo` - a supported OpenSSL digest algorithm. Defaults to `sha256`. +* `passphrase_hash_algo` - a supported OpenSSL digest algorithm. Defaults to `sha256`. +* `encrypt` - whether to encrypt or not. Set to `true` to encrypt. + +Example: +``` +OpenIDCCache shm key_hash_algo=sha256&passphrase_hash_algo=sha256&encrypt=false; +``` + +### OpenIDCSession + +`OpenIDCSession [form-encoded-options];` + +Configures the session type and options, e.g. cache/cookie, session duration, etc. Optional, defaults to `cookie`. Form-encoded options include: + + * `cookie.name` - defaults to `openidc_session` + * `cookie.path` - defaults to `/` + * `max_duration` - defaults to 28800 seconds (8 hours) + * `inactivity_timeout` - defaults to 300 seconds (5 minutes) + +Example: +``` +OpenIDCSession cookie cookie.name=openidc_session&cookie.path=/&max_duration=28800&inactivity_timeout=300; +``` + +### OpenIDCConfig + +`OpenIDCConfig ;` + +Configures global setting such as redirect URI, etc. Options include: + +* `handler_path` - defaults to `/openid-connect` +* `redirect_uri` - the uri to redirect to after authenticating on the identity provider. Defaults to `$handler_path` + `/redirect_uri` +* `state.cookie.name.prefix` - defaults to `openidc_state_` +* `state.cookie.timeout` - defaults to 300 seconds (5 minutes) +* `state.cookie.max` - defaults to 6 +* `state.cookie.delete.oldest` - defaults to false +* `unauth_action` - Defines the action to be taken when an unauthenticated request is made. Defaults to `auth`. Available values: + * `auth` - user is redirected to the OpenID Connect Provider or Discovery page. + * `pass` - unauthenticated request will pass but claims will still be passed when a user happens to be authenticated already + * `401` - HTTP 401 Unauthorized is returned + * `410` - HTTP 410 Gone is returned + +Example: +``` +OpenIDCConfig handler_path=/openid-connect&redirect_uri=/redirect_uri; +``` ## Samples