Powered by Algolia

    mod_openiam Directive Reference

    The OpenIAM rProxy is implemented as a custom Apache module (mod_openiam.so). All OPENIAM_ directives listed here are proprietary to this module — they are not standard Apache httpd directives. They are loaded into Apache via:

    LoadModule openiam_module modules/mod_openiam.so

    Scope note: Some directives are global (outside any <VirtualHost> or <Location> block), some belong inside <Location> blocks. See the examples in rProxy Installation and the category notes below.

    Core / ESB Connectivity

    DirectiveTypeDescription
    OPENIAM_ESBPathURLESB endpoint. Use http://esb:9080 for Docker or http://localhost:9080 for standalone. Must be set outside <VirtualHost>.
    OPENIAM_ConfigureBackendURLBackend UI endpoint for the setup wizard. Use http://ui:8080 for Docker or http://localhost:8080 for standalone.
    OPENIAM_ConfigureHostPathRedirect target when the content provider is not yet configured (e.g. /webconsole/setup).
    OPENIAM_ConfigureUrlsPath (repeatable)Paths accessible without authentication during initial setup. Can be specified multiple times.

    Authentication & Session

    DirectiveTypeDescription
    OPENIAM_AuthProviderStringName of the authentication provider to use.
    OPENIAM_AuthAuthoritativeFlag (on/off)Whether OpenIAM auth is the authoritative authentication mechanism.
    OPENIAM_AuthCookieNameStringOverride the default OPENIAM_AUTH_TOKEN session cookie name.
    OPENIAM_SetCookiesSecureFlag (on/off)Force the Secure attribute on all cookies set by the module.
    OPENIAM_ReadCookiesFromStringRead cookies from a header other than Cookie.
    OPENIAM_LogoutRedirectURL (repeatable)One or more URLs to redirect through before reaching /idp/logout.

    URL Routing & Redirects

    DirectiveTypeDescription
    OPENIAM_DefaultUrlURLDefault redirect URL after login (e.g. /selfservice/). Used inside <Location />.
    OPENIAM_DefaultPostbackUrlURLDefault postback URL to return to after authentication.
    OPENIAM_DefaultTimeoutIntegerDefault request timeout in seconds.
    OPENIAM_DefaultUrlForLangURLRedirect from / to this URL when a language cookie is present.
    OPENIAM_NoAuthPath (repeatable)Paths that bypass authentication. Can be specified multiple times.
    OPENIAM_NoAuthOnPathPathSkip authentication for this specific path.
    OPENIAM_RedirectURLUnconditionally redirect to this URL.
    OPENIAM_RedirectWithAuthURLRedirect to this URL when the user is authenticated.
    OPENIAM_RedirectWithoutAuthURLRedirect to this URL when the user is not authenticated.
    OPENIAM_RedirectBackUrlURLURL to return the user to after completing authentication.
    OPENIAM_RedirectBackForLangStringSet the OPENIAM_REDIRECT_BACK cookie for a specific language for / and /idp/login.
    OPENIAM_FixRedirectForLangFlag (on/off)Enable or disable language-cookie-based redirects for / and /idp/login.
    OPENIAM_FixLocationListString (repeatable)List of Location response headers to rewrite.
    OPENIAM_ProxyPassReverseURLAdjust Location headers in proxied responses (equivalent to Apache's ProxyPassReverse).
    OPENIAM_OutHeadersRedirectNameStringName of a response header to inspect for conditional redirects.
    OPENIAM_OutHeadersRedirectValuesStringTwo-argument value: if the header named by OPENIAM_OutHeadersRedirectName contains this value, redirect to the given URL.

    Security Headers

    DirectiveTypeDescription
    OPENIAM_CSPEnabledFlag (on/off)Enable automatic Content-Security-Policy header generation.
    OPENIAM_CSPOverrideStringFully replace the default CSP header value with this string.
    OPENIAM_CSPOverrideWithCorsStringReplace the CSP header value and also add CORS headers. Useful when OPENIAM_CORSAllowAll on is insufficient.
    OPENIAM_CSPReportEnalbedFlag (on/off)Enable CSP violation reporting. (Note: directive name contains a typo — Enalbed — use exactly as written.)
    OPENIAM_CSPReportOnlyFlag (on/off)Set CSP header in Report-Only mode (logs violations without blocking).
    OPENIAM_CORSAllowAllFlag (on/off)Add Access-Control-Allow-Origin: * and related CORS headers to responses.
    OPENIAM_AddHSTSHeadersFlag (on/off)Add Strict-Transport-Security (HSTS) headers.
    OPENIAM_DefaultRespHeaderString (repeatable)Set a default response header if it has not already been set by the upstream. Format: OPENIAM_DefaultRespHeader Header-Name value. Example: OPENIAM_DefaultRespHeader Referrer-Policy strict-origin.
    OPENIAM_RandomIVFlag (on/off)Use a random initialization vector for encryption. Default: off.

    CSP Example

    # Simple — use built-in CSP generation
    OPENIAM_CSPEnabled on
    

    # Override with a custom policy
    OPENIAM_CSPOverride "default-src 'self' blob: data: 'unsafe-inline' 'unsafe-eval'; \
        script-src 'self' 'unsafe-inline' 'unsafe-eval' apis.google.com; \
        style-src 'self' 'unsafe-inline' 'unsafe-eval' *; \
        img-src 'self' data:; \
        font-src 'self' *;"
    

    # Override CSP and add CORS headers at the same time
    OPENIAM_CSPOverrideWithCors "default-src 'self' blob: data: 'unsafe-inline' 'unsafe-eval'; \
        script-src 'self' 'unsafe-inline' 'unsafe-eval' apis.google.com; \
        style-src 'self' 'unsafe-inline' 'unsafe-eval' *; \
        form-action 'self' 'unsafe-inline' 'unsafe-eval' *; \
        img-src 'self' data:; \
        font-src 'self' *;"

    Client Certificate Authentication

    DirectiveTypeDescription
    OPENIAM_CertPromptUrlURLURL that triggers the certificate selection prompt (e.g. /idp/auth-cert).
    OPENIAM_ClientCertHeaderNameStringName of the HTTP header that contains the client certificate (used with OPENIAM_ReadClientCertFromHeader). Default: x-openiam-client-cert.
    OPENIAM_ReadClientCertFromHeaderFlag (on/off)Read the client certificate from the header specified by OPENIAM_ClientCertHeaderName rather than from the TLS handshake.
    OPENIAM_NoAuthHeaderForCertAuthStringSkip setting the auth header when cert-based auth is used.
    OPENIAM_NoAuthHeaderForCertFromHeaderStringSkip setting the auth header when the cert is read from a header.
    OPENIAM_NoCookieForCertAuthFlag (on/off)Do not set the session cookie when cert-based auth is used.
    OPENIAM_NoCookieForCertFromHeaderFlag (on/off)Do not set the session cookie when the cert is read from a header.
    OPENIAM_DebugCertAuthFlag (on/off)Enable verbose debug logging for certificate authentication.

    Kerberos Authentication

    DirectiveTypeDescription
    OPENIAM_KerberosFlag (on/off)Enable Kerberos (SPNEGO) authentication handling.
    OPENIAM_KrbPrincipalOnlyFlag (on/off)Strip the realm from the Kerberos principal and use only the username portion.
    OPENIAM_KrbPrincipalPrefixStringPrefix to prepend to the Kerberos principal before passing it to OpenIAM.
    OPENIAM_KrbPrincipalSuffixStringSuffix to append to the Kerberos principal before passing it to OpenIAM.

    See also: Kerberos configuration guide.

    Forwarded Headers / Client IP

    DirectiveTypeDescription
    OPENIAM_Client_Ip_HeaderStringName of the header from which to read the originating client IP address.
    OPENIAM_Forwarded_For_HeaderStringHeader name to use for forwarding the client IP (X-Forwarded-For).
    OPENIAM_Forwarded_By_HeaderStringHeader name to use for the proxy identity (X-Forwarded-By).

    SOAP / Header-Based Authentication

    DirectiveTypeDescription
    OPENIAM_SoapHeaderStringSet a SOAP header on backend requests.
    OPENIAM_SoapAuthHeadersFlag (on/off)Include authentication headers in SOAP requests to the backend.
    OPENIAM_AuthHeaderUsernameStringHeader name for the username in header-based authentication flows.
    OPENIAM_AutnHeaderPasswordStringHeader name for the password in header-based authentication flows. (Note: directive name contains a typo — Autn — use exactly as written.)
    OPENIAM_UserParamStringURL query parameter name for the username.
    OPENIAM_PasswordParamStringURL query parameter name for the password.

    cURL Backend Transport

    By default the module uses Apache's internal HTTP client. To use libcurl instead:

    DirectiveTypeDescription
    OPENIAM_UseCurlFlag (on/off)Use libcurl for all backend HTTP requests. Default: off.
    OPENIAM_CurlPoolEnableFlag (on/off)Enable a persistent cURL connection pool.
    OPENIAM_CurlPoolSizeIntegerNumber of connections in the cURL pool. Default: 32.
    OPENIAM_CurlConnectTimeoutIntegerTCP connection timeout in seconds. Default: 2.
    OPENIAM_CurlTimeoutIntegerTotal request timeout in seconds. Default: 10.

    Worker Pool

    The worker pool manages a set of persistent backend connections. These directives are set globally (outside <VirtualHost>):

    DirectiveTypeDescription
    OPENIAM_WorkerPooEnabledFlag (On/Off)Enable the worker pool. (Note: directive name contains a typo — Poo — use exactly as written.)
    OPENIAM_WorkerPoolMinIntegerMinimum number of workers to keep alive.
    OPENIAM_WorkerPoolMaxIntegerMaximum number of workers.
    OPENIAM_WorkerPoolSoftMaxIntegerSoft maximum — workers above this value are eligible for idle reaping.
    OPENIAM_WorkerPoolTTLIntegerTime-to-live for an idle worker connection, in seconds.
    OPENIAM_WorkerPoolTimeoutIntegerTimeout for a worker request, in seconds.
    OPENIAM_WorkerPoolKeepAliveFlag (On/Off)Keep backend connections alive between requests.
    OPENIAM_WorkerPoolRetryIntegerNumber of times to retry a failed backend request.

    Recommended worker pool settings (Docker deployment)

    OPENIAM_WorkerPooEnabled On
    OPENIAM_WorkerPoolMin 25
    OPENIAM_WorkerPoolMax 100
    OPENIAM_WorkerPoolSoftMax 100
    OPENIAM_WorkerPoolTTL 600
    OPENIAM_WorkerPoolTimeout 300
    OPENIAM_WorkerPoolKeepAlive On
    OPENIAM_WorkerPoolRetry 0
    

    OPENIAM_CurlPoolEnable On
    OPENIAM_CurlPoolSize 32
    OPENIAM_CurlConnectTimeout 2
    OPENIAM_CurlTimeout 10

    Debug & Logging

    All debug directives default to off. Enable only as needed for troubleshooting — they produce significant log volume.

    DirectiveTypeDescription
    OPENIAM_VerboseFlag (on/off)Enable verbose module logging.
    OPENIAM_DebugESBFlag (on/off)Log all ESB request/response details.
    OPENIAM_DebugCookiesFlag (on/off)Log cookie inspection and manipulation.
    OPENIAM_DebugRespHeadersFlag (on/off)Log outgoing response headers.
    OPENIAM_DebugPatternsFlag (on/off)Log URL pattern matching decisions.
    OPENIAM_PrintTimingsFlag (on/off)Log request timing information (useful for latency diagnosis).
    OPENIAM_AllowDumpHeadersFlag (on/off)Enable header dumping (required for the Dump* directives below to show headers).
    OPENIAM_DumpRequestsFlag (on/off)Dump incoming request metadata to the error log.
    OPENIAM_DumpRequestsBodyFlag (on/off)Dump incoming request bodies.
    OPENIAM_DumpRequestBody_filterStringOnly dump request bodies matching this pattern.
    OPENIAM_DumpNoAuthFlag (on/off)Also dump requests that do not require authentication.
    OPENIAM_DumpResponsesFlag (on/off)Dump outgoing response metadata.
    OPENIAM_DumpResponsesBodyFlag (on/off)Dump outgoing response bodies.

    Full debug configuration example

    LogLevel debug
    

    OPENIAM_Verbose on
    OPENIAM_DebugESB on
    OPENIAM_DebugCookies on
    OPENIAM_DebugCertAuth on
    OPENIAM_PrintTimings on
    OPENIAM_AllowDumpHeaders on
    OPENIAM_DumpRequests on
    OPENIAM_DumpRequestsBody on
    OPENIAM_DumpResponses on
    OPENIAM_DumpResponsesBody on
    OPENIAM_DebugRespHeaders on
    Previous
    Setting up Kerberos via rProxy
    Next
    Developer Guide