diff --git a/auth_openidc.conf b/auth_openidc.conf index ec6620c5..9268e75e 100644 --- a/auth_openidc.conf +++ b/auth_openidc.conf @@ -18,7 +18,7 @@ # - encryption of cache entries, that may include the session cookie, see: OIDCCacheEncrypt and OIDCSessionType # Note that an encrypted cache mechanism can be shared between servers if they use the same OIDCCryptoPassphrase # If the value begins with exec: the resulting command will be executed and the -# first line returned to standard output by the program will be used as the password, e.g: +# first line returned to standard output by the program will be used as the password, e.g.: # OIDCCryptoPassphrase "exec:/bin/bash -c \"head /dev/urandom | tr -dc A-Za-z0-9 | head -c 32\"" # (notice that the above typically only works in non-clustered environments) # The command may be absolute or relative to the web server root. @@ -73,7 +73,7 @@ # OpenID Connect Provider Signed JWKS URL (e.g. https://localhost:9031/pf/JWKS) followed by the verification key set # formatted as either JWK or JWKS. The verification key set is used to verify the provided JWKs value. # Specifying multiple keys allows the OP rotate the key used for signing the JWKs. -# I.e this is the URL on which the ID Token signing keys for this OP are hosted, in verifiable JWT formatting +# I.e. this is the URL on which the ID Token signing keys for this OP are hosted, in verifiable JWT formatting # rather than relying on TLS for authentication and integrity protection. # Used when OIDCProviderMetadataURL is not defined or the metadata obtained from that URL does not set signed_jwks_uri. # When defined it takes precedence over OIDCProviderJwksUri @@ -81,7 +81,7 @@ # OIDCProviderSignedJwksUri https://localhost:9031/pf/JWKS "{\"kty\":\"oct\", \"k\":\"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow\"}" # OIDCProviderSignedJwksUri https://localhost:9031/pf/JWKS "{\"keys\":[{\"kty\":\"oct\", \"k\":\"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow\"}]}" # NB: for multi-OP setups: -# the 1st parameter is not used, it needs to be set anyhow (e.g. to "") if you wish to used the 2nd parameter +# the 1st parameter is not used, it needs to be set anyhow (e.g. to "") if you wish to use the 2nd parameter # the 2nd parameter is the default verification JWK for content pulled from the signed_jwks_uri for all providers and # and its can be overridden with a per-provider key in the .conf file using the key: signed_jwks_uri_key #OIDCProviderSignedJwksUri [ | ] @@ -150,13 +150,13 @@ #OIDCProviderBackChannelLogoutSupported [On|Off] # Extra JSON parameters that need to be passed in the registration request to the Registration Endpoint. -# This settings serves as a default value for multiple OPs only. +# This setting serves as a default value for multiple OPs only. # Parameter names and values need to be provided in JSON form and will be merged in to the request. # When not defined no extra parameters will be passed. # NB: this can be overridden on a per-OP basis in the .conf file using the key: registration_endpoint_json #OIDCProviderRegistrationEndpointJson -# Define the OpenID Connect scope that is requested from the OP (eg. "openid email profile"). +# Define the OpenID Connect scope that is requested from the OP (e.g. "openid email profile"). # When not defined, the bare minimal scope "openid" is used. # NB: multiple scope values must be enclosed in a single pair of double quotes # NB: this can be overridden on a per-OP basis in the .conf file using the key: scope @@ -171,7 +171,7 @@ # in the .provider metadata (though that would not work with Discovery OPs). # # One can pass on query parameters from the request to the authorization request by adding -# e.g. "foo=#" which which will dynamically pull in the query parameter value from the +# e.g. "foo=#" which will dynamically pull in the query parameter value from the # request query parameter and add it to the authentication request to the OP. # # The default is to not add extra parameters. @@ -348,7 +348,7 @@ #OIDCIDTokenEncryptedResponseEnc [A128CBC-HS256|A256CBC-HS512|A256GCM] # The accepted value(s) of the "aud" claim in the ID token, restricted to only those values that have been defined here. -# The convienience value "@" can be used to refer to the configured client id (i.e. in case of dynamic client registration). +# The convenience value "@" can be used to refer to the configured client id (i.e. in case of dynamic client registration). # When not defined the default is to accept any list of values (or a single string value) that includes value of OIDCClientID. # NB: this can be overridden on a per-OP basis in the .conf file using the key: id_token_aud_values with the value set to a JSON array of strings. #OIDCIDTokenAudValues + @@ -439,7 +439,7 @@ # When not defined no extra parameters will be passed. #OIDCOAuthIntrospectionEndpointParams =[&=]* -# Name of the parameter whose value carries the access token value in an validation request to the token introspection endpoint. +# Name of the parameter whose value carries the access token value in a validation request to the token introspection endpoint. # When not defined the default "token" is used. #OIDCOAuthIntrospectionTokenParamName @@ -503,8 +503,8 @@ # claim value from the 1st parameter and the first match returned from that expression will # be set as the REMOTE_USER. E.g. to strip a domain from an e-mail style address you'd use ^(.*)@ # -# An optional 3rd parameter can be added that would contain string with number backrefrences. -# Backrefrences must be in the form $1, $2.. etc. +# An optional 3rd parameter can be added that would contain string with number backreferences. +# Backreferences must be in the form $1, $2.. etc. # E.g. to extract username in the form DOMAIN\userid from e-mail style address you may use # ^(.*)@([^.]+)\..+$ $2\\$1 #OIDCOAuthRemoteUserClaim [] [substitution-string] @@ -581,7 +581,7 @@ # When not defined the default is On (Lax). #OIDCCookieSameSite [ On | Off | Strict | Lax | None | Disabled ] -# Specify the names of cookies to pickup from the browser and send along on backchannel +# Specify the names of cookies to pick up from the browser and send along on backchannel # calls to the OP and AS endpoints. This can be used for load-balancing purposes. # When not defined, no such cookies are sent. #OIDCPassCookies []+ @@ -593,7 +593,7 @@ # When not defined, no cookies are stripped. #OIDCStripCookies []+ -# Specify the maximum number of state cookies i.e. the maximum number of parallel outstanding +# Specify the maximum number of state cookies, i.e. the maximum number of parallel outstanding # authentication requests. See: https://github.com/OpenIDC/mod_auth_openidc/issues/331 # Setting this to 0 means unlimited, until the browser or server gives up which is the # behavior of mod_auth_openidc < 2.3.8, which did not have this configuration option. @@ -673,7 +673,7 @@ # When using OIDCCacheType "shm": # Specifies the maximum number of name/value pair entries that can be cached. -# When caching a large number of entries the cache size limit may be reached and the +# When caching a large number of entries, the cache size limit may be reached and the # least recently used entry will be overwritten. If this happens within 1 hour, # errors will be displayed in the error.log and the OIDCCacheShmMax value may be increased. # When not specified, a default of 10000 entries is used. @@ -729,8 +729,8 @@ #OIDCRedisCachePassword # Username to be used if the Redis/Valkey server requires authentication: http://redis.io/commands/auth -# NB: this can only used with Redis/Valkey 6 (ACLs) or later -# When not specified, the implicit user "default" is used +# NB: this can only be used with Redis/Valkey 6 (ACLs) or later. +# When not specified, the implicit user "default" is used. #OIDCRedisCacheUsername # Logical database to select on the Redis/Valkey server: https://redis.io/commands/select @@ -746,7 +746,7 @@ #OIDCRedisCacheConnectTimeout [0|] # Timeout waiting for a response of the Redis/Valkey server after a request was sent. -# When not defined the default timeout is 5 seconds. +# When not defined, the default timeout is 5 seconds. #OIDCRedisCacheTimeout ######################################################################################## @@ -757,7 +757,7 @@ # Defines an external OP Discovery page. That page will be called with: # ?oidc_callback= -# additional parameters may be added, a.o. `target_link_uri`, `x_csrf` and `method`. +# additional parameters may be added, i.e. `target_link_uri`, `x_csrf` and `method`. # # An Issuer selection can be passed back to the callback URL as in: # ?iss=[${issuer}|${domain}|${e-mail-style-account-name}][parameters][&login_hint=][&scopes=][&auth_request_params=] @@ -779,7 +779,7 @@ # When not defined and no URL was passed explicitly, a default internal page will be shown. #OIDCDefaultLoggedOutURL -# Define the OpenID Connect scope(s) that is requested from the OP (eg. "admin edit") +# Define the OpenID Connect scope(s) that is requested from the OP (e.g. "admin edit") # on a per-path basis in addition to the per-provider configured scopes (OIDCScope). # Multiple scope values must be enclosed in a single pair of double quotes. # Apache expressions can be used to pass dynamic runtime determined values. @@ -790,7 +790,7 @@ # These must be URL-query-encoded as in: "display=popup&prompt=consent". # This can be configured on a per-path basis across all configured Providers. # One can pass on query parameters from the request to the authorization request by adding -# e.g. "foo=#" which which will dynamically pull in the query parameter value from the +# e.g. "foo=#" which will dynamically pull in the query parameter value from the # request query parameter and add it to the authentication request to the OP. # Apache expressions can be used to pass dynamic runtime determined values. # The default is to not add extra parameters. @@ -811,8 +811,8 @@ #OIDCClaimDelimiter # The claim that is used when setting the REMOTE_USER variable on OpenID Connect protected paths. -# If the claim name is postfixed with a \"@\", the claim value will be post-fixed with the -# \"iss\" value value (with leading "https://" stripped) to make this value unique across different OPs. +# If the claim name is post-fixed with a \"@\", the claim value will be post-fixed with the +# \"iss\" value (with leading "https://" stripped) to make this value unique across different OPs. # When not defined the default "sub@" is used. # # An optional regular expression can be added as a 2nd parameter that will be applied to the @@ -820,7 +820,7 @@ # be set as the REMOTE_USER. E.g. to strip a domain from an e-mail style address you'd use ^(.*)@ # # An optional 3rd parameter can be added that would contain string with number backrefrences. -# Backrefrences must be in the form $1, $2.. etc. +# Backreferences must be in the form $1, $2.. etc. # E.g. to extract username in the form DOMAIN\userid from e-mail style address you may use # ^(.*)@([^.]+)\..+$ $2\\$1 #OIDCRemoteUserClaim [@] [] [substitution-string] @@ -847,7 +847,7 @@ # "signed_jwt[: header/environment variable -# - requires OIDCPrivateKeyFiles/OIDCPublicKeyFiles set with a RSA key (RS256) or a prime256v1 Elliptic Curve key(s) (ES256), +# - requires OIDCPrivateKeyFiles/OIDCPublicKeyFiles set with an RSA key (RS256) or a prime256v1 Elliptic Curve key(s) (ES256), # the first RSA/EC signing key in the configured list will be used # - the "expires_in" hint from the access_token is used in the "exp" claim; defaults to 60 seconds if not returned by the OP. # - caching of the signed JWT - use with care only - can be configured using: @@ -858,7 +858,7 @@ # Only when compiled in with libjq (https://stedolan.github.io/jq/manual/) support: process the claims # returned from the userinfo endpoint with a JQ-based expression before propagating them according -# to OIDCPassUserInfoAs claims|json|signed_jwt (ie. does not work for "OIDCPassUserInfoAs jwt") +# to OIDCPassUserInfoAs claims|json|signed_jwt (i.e. it does not work for "OIDCPassUserInfoAs jwt") # # Overwrite the default (provider) "iss" claim, and delete the default "aud" and "name" claims: # '. + { iss: "https://myissuer.com" } | del(.aud, .name)' @@ -876,7 +876,7 @@ # Only when compiled in with libjq (https://stedolan.github.io/jq/manual/) support: applies # a JQ filter to claims in the both the id_token and claims returned from the userinfo endpoint -# before storing them in the session after applying (optional) toplevel blacklisting/whitelisting +# before storing them in the session after applying (optional) top-level blacklisting/whitelisting # with OIDCBlackListedClaims/OIDCWhiteListedClaims, e.g.: # filter out all elements in the "groups" array of strings that match regular expression ^CN=test-.* # '. + { groups: (.groups - (.groups | map(select(match("^CN=test-.*"; "g"))))) }' @@ -893,7 +893,7 @@ # "headers": claims/tokens are passed in headers (also useful in reverse proxy scenario's) # "both": claims/tokens are passed as both headers as well as environment variables (default) # -# A second parameter can be specified that defines the encodong applied to all values passed in headers +# A second parameter can be specified that defines the encoding applied to all values passed in headers # and environment variables: # "latin1" applies ISO-8859-1 encoding: this may result in out of bound characters converted to the "?" character. # "base64url" applies base64url encoding @@ -927,7 +927,7 @@ # an interval of 500ms. #OIDCHTTPTimeoutShort [] [[:]] -# Time to live in seconds for state parameter i.e. the interval in which the authorization request +# Time to live in seconds for state parameter, i.e. the interval in which the authorization request # and the corresponding response need to be processed. When not defined the default of 300 seconds is used. #OIDCStateTimeout @@ -946,7 +946,7 @@ # # Useful in Location/Directory/Proxy path contexts that serve AJAX/Javascript calls and for "anonymous access" # -# When not defined the default is "auth" with auto-detection of requests that woult not be able to complete +# When not defined the default is "auth" with auto-detection of requests that would not be able to complete # an authentication round trip to the OpenID Connect Provider, which would receive a 401. # The default auto-detection algorithm looks for the "X-Requested-With: XMLHttpRequest" header/value, or # the presence of a Sec-Fetch-Mode header with a value that is not equal to "navigate", or the presence of @@ -957,10 +957,10 @@ # See: https://github.com/OpenIDC/mod_auth_openidc/wiki/Cookies#tldr # # Only for Apache >= 2.4.x: -# Since verson 2.4.4 a boolean Apache expression as the second parameter to specify which requests +# Since version 2.4.4 a boolean Apache expression as the second parameter to specify which requests # need to match to return the configured value in the first parameter to override the default "auth". # See also: https://httpd.apache.org/docs/2.4/expr.html. -# E.g to only return 401 for cURL based user agents and "auth" for any other browsers/user agents: +# E.g. to only return 401 for cURL-based user agents and "auth" for any other browsers/user agents: # OIDCUnAuthAction 401 "%{HTTP_USER_AGENT} =~ /curl/" # to effectively override the default XML request detection algorithm by ignoring the Sec-Fetch-Mode, # Sec-Fetch-Dest and Accept headers: @@ -976,20 +976,20 @@ # && ( %{HTTP_ACCEPT} !~ m#\*/\*# ) )" # To enable authentication in an iframe you need to change the Sec-Fetch-Dest part above in: # || ( -n %{HTTP:Sec-Fetch-Dest} && %{HTTP:Sec-Fetch-Dest} != 'iframe' && %{HTTP:Sec-Fetch-Dest} != 'document') \ -# To disable auto-detection of XML HTTP request altogether and uncondtionally return "auth" for all clients: +# To disable auto-detection of XML HTTP request altogether and unconditionally return "auth" for all clients: # OIDCUnAuthAction auth true # Note that actually *any* expression value in "OIDCUnAuthAction auth " will *always* render "auth" # (even when set to "false"...) because of the default, so using an value (other than "true") only # makes sense in combination with one of the values other than "auth". #OIDCUnAuthAction [auth|pass|401|407|410] [] -# Defines the action to be taken when an unauthorized request is made i.e. the user is authenticated but +# Defines the action to be taken when an unauthorized request is made, i.e. the user is authenticated but # does not meet the `Require claim <>` directives or similar. # "401" return HTTP 401 Unauthorized with optional text message if specified in # "403" return HTTP 403 Forbidden with optional text message; NB: for Apache 2.4 this is controlled by the AuthzSendForbiddenOnFailure directive! # "302" redirect to the URL specified in the parameter # "auth" redirect the user to the OpenID Connect Provider or Discovery page for authentication ( is unused) -# Useful in Location/Directory/Proxy path contexts that need to do stepup authentication +# Useful in Location/Directory/Proxy path contexts that need to do step-up authentication # Be aware that this will only work in combination with a single Require statement or RequireAll, # so using RequireAny and multiple Require statements is not supported. # Also for "auth", the expression argument for OIDCUnAuthAction is re-used here to detect XHR requests. @@ -1005,13 +1005,13 @@ # POST preserve and restore templates to be used with OIDCPreservePost # template needs to contain two "%s" characters -# the first for the JSON formattted POST data, the second for the URL to redirect to after preserving +# the first for the JSON formatted POST data, the second for the URL to redirect to after preserving # template needs to contain one "%s" # which contains the (original) URL to POST the restored data to # The default is to use internal templates #OIDCPreservePostTemplates -# Indicates whether the access token and access token expires will be passed to the application in a header/environment variable, according +# Indicates whether the access token and access token expiry will be passed to the application in a header/environment variable, according # to the OIDCPassClaimsAs directive. # Can be configured on a per Directory/Location basis. The default is "On". #OIDCPassAccessToken [On|Off] @@ -1057,9 +1057,9 @@ # timeout (int) : the session inactivity timeout (Unix timestamp in seconds) # remote_user (string) : the remote user name # session (object) : (for debugging) mod_auth_openidc specific session data such as "remote user", "session expiry", "session id" and a "state" object -# Note that when using ProxyPass / you may have to add a proxy exception for the Redirect URI -# for this to work, e.g. ProxyPass /redirect_uri ! -# When not defined the session hook will not return any data but a HTTP 404 +# Note that when using "ProxyPass /" you may have to add a proxy exception for the Redirect URI +# for this to work, e.g. "ProxyPass /redirect_uri !" +# When not defined the session hook will not return any data but a HTTP 404. #OIDCInfoHook [iat|access_token|access_token_expires|id_token|id_token_hint|userinfo|refresh_token|exp|timeout|remote_user|session]+ # Specify metrics that you wish to collect and keep in shared memory for retrieval. @@ -1080,10 +1080,10 @@ # The format parameter can be passed to specify the format in which the collected data is returned. # format=prometheus Prometheus text-based exporter # format=json (non-standard) JSON with descriptions and names -# format=status short text based status message "OK" plus optional counter (&vhost=&counter=) +# format=status short text-based status message "OK" plus optional counter (&vhost=&counter=) # format=internal internal terse JSON for debugging purposes # The default is "prometheus". -# Protect protect this path (e.g. Require host localhost) or serve it on an internal co-located vhost/port. +# Protect this path (e.g. Require host localhost) or serve it on an internal co-located vhost/port. # When not defined, no metrics will be published on the enclosing vhost. #OIDCMetricsPublish @@ -1119,7 +1119,7 @@ # Define one or more regular expressions that specify URLs (or domains) allowed for post logout and # other redirects such as the "return_to" value on refresh token requests, the "login_uri" value -# on session management based logins through the OP iframe, and the "target_link_uri" parameter in +# on session management-based logins through the OP iframe, and the "target_link_uri" parameter in # 3rd-party initiated logins, e.g.: # OIDCRedirectURLsAllowed ^https://www\.example\.com ^https://(\w+)\.example\.org ^https://example\.net/app # or: @@ -1137,7 +1137,7 @@ # When not defined the default is "DENY". #OIDCLogoutXFrameOptions -# Define the X-Forwarded-* or Forwarded headers that will be taken into account as set by a reverse proxy +# Define the X-Forwarded-* or Forwarded headers that will be considered as set by a reverse proxy # in front of mod_auth_openidc. Must be one or more of: # X-Forwarded-Host # X-Forwarded-Port