Maverics Apache Module (Legacy)

ℹ️

Maverics Web Server Modules have been replaced by RP Orchestrators. This model should be used in all new deployments where a web server is protected by a local Orchestrator.

The Maverics Apache Module is a plug-in for Apache HTTP Server (Apache), IBM HTTP Server (IHS), or Oracle HTTP Server (OHS). The Maverics Apache Module is primarily used for policy enforcement and sending headers to protected resources.

Server requirements

Apache 2.4, IHS 8.5, or OHS 12c
Centos/RHEL 7 or 8
Sudo rights for installation and administrative tasks

Install

To install the Maverics Apache Module, obtain a copy of the appropriate RPM package for your version of Linux and your web server distribution. For example:

Apache & OHS:
- Centos/RHEL 7: mod_maverics_apache2_4.v0.1.7.el7.x86_64.rpm
- Centos/RHEL 8: mod_maverics_apache2_4.v0.1.7.el8.x86_64.rpm
IHS:
- Centos/RHEL 7: mod_maverics_ihs.v0.1.7.el7.x86_64.rpm
- Centos/RHEL 8: mod_maverics_ihs.v0.1.7.el8.x86_64.rpm

Copy the RPM package to the server and install using rpm. For example:

sudo rpm -ivh mod_maverics_ihs.v0.1.7.el8.x86_64.rpm

Upgrade

To upgrade an existing installation to the latest version, use the -U or --upgrade option:

sudo rpm -Uvh mod_maverics_ihs.v0.1.8.el8.x86_64.rpm

Configure

Top-Level Directives

# MavericsOrchestratorAuthEndpoint
# The registered auth endpoint that is set in the Maverics Orchestrator 
# configuration file.
MavericsOrchestratorAuthEndpoint https://maverics.enterprise.com/auth

# MavericsResponseType
# The response type (or OpenID Connect Flow) used.   
# This is an optional field and when not defined the "code" response type is used. Currently, only 
# id_token is supported when using the Orchestrator as an IdP.
# MavericsResponseType [ "id_token" | "code" | "id_token token" | "code id_token" | "code token" | "code id_token token" ]`   
MavericsResponseType id_token

# MavericsClientID
# OpenID Connect client ID.
MavericsClientID oidc-id

# MavericsClientSecret
# OpenID Connect client secret.
MavericsClientSecret 0123456789

# MavericsRedirectURI  
# The redirect_uri for this OpenID Connect client; this is a vanity URL
# that must ONLY point to a path on your server protected by this module   
# but it must NOT point to any actual content that needs to be served.
# You can use a relative URL like /protected/redirect_uri if you want to   
# support multiple vhosts that belong to the same security domain in a dynamic way.
MavericsRedirectURI https://org.enterprise.com/sonar/oidc

# MavericsResponseMode  
# The response mode used (this serves as default value for discovered OPs too).
# This is an optional field and when not defined the default response mode is form_post.
# MavericsResponseMode [form_post|query|fragment]
MavericsResponseMode form_post

# MavericsProviderIssuer   
# OpenID Connect Provider issuer identifier (e.g. https://maverics.enterprise.com).  
MavericsProviderIssuer  https://maverics.enterprise.com   

# MavericsPathAuthRequestParams
# Additional query parameters that will be sent during the Authorization Request. 
# These must be URL-query-encoded as in: "display=popup&prompt=consent".
# This is an optional field and when not defined the default is to add no additional parameters.   
MavericsPathAuthRequestParams tos=true&newsletter=false

# MavericsSessionCount
# The total number of sessions to keep in memory.
# This is an optional field and when not defined a default of 500 sessions will be used.
MavericsSessionCount: 500

# MavericsSessionSize
# The size of each session that is stored in memory in bytes. 
# This is an optional field and when not defined default of 16913 bytes will be used.
MavericsSessionSize: 16913

# MavericsCookieDomain   
# The domain to be used when session and state cookies are created.
# This is an optional field and when not defined the currently accessed hostname is used.   
MavericsCookieDomain example.com

# MavericsCookiePath
# The path to be used when session and state cookies are created.
# This is an optional field and when not defined will default to `/`
MavericsCookiePath /app

`Location`-Level Directives

# MavericsAppGateway
# The App Gateway that will be used for the location. This is a unique identifier that should match 
# the name of the corresponding App Gateway defined in the Orchestrator.
MavericsAppGateway sonar

Cookie Settings

`SameSite`

By default, the SameSite=None attribute is set on cookies. In modern browsers, SameSite=None must be paired with the Secure attribute, and therefore cookies will only be set when a server is using HTTPS. For servers that use HTTP, define SetEnvIf User-Agent ".*" OIDC_SET_COOKIE_APPEND=; to ensure cookies are successfully set in the browser.

Enable the Maverics Apache Module

To enable the Maverics Apache Module module, add the directive AuthType maverics and Require valid-user to the location block. You can see an example of it below.

MavericsOrchestratorAuthEndpoint https://maverics.enterprise.com/auth
MavericsResponseType id_token
MavericsClientID test-client
MavericsClientSecret 0123456789
MavericsRedirectURI https://org.enterprise.com/sonar/oidc
MavericsCryptoPassphrase none
MavericsResponseMode form_post
MavericsProviderIssuer https://maverics.enterprise.com

LoadFile /usr/lib64/libz.so.1
LoadModule ibm_ssl_module modules/mod_ibm_ssl.so
LoadModule maverics_module /usr/lib64/httpd/modules/mod_maverics.so
<VirtualHost *:443>
	SSLEnable
	KeyFile /opt/IBM/HTTPServer/conf/ihsserverkey.kdb
	<Location /sonar>
		AuthType maverics
		Require valid-user
		MavericsAppGateway sonar
	</Location>
</VirtualHost>

Disable the Maverics Apache Module

To disable the Maverics Apache Module module, delete or comment out the directive AuthType maverics and Require valid-user in the location block(s). Also remove all Maverics Apache Module related directives. You can see an example of it below.

LoadModule ibm_ssl_module modules/mod_ibm_ssl.so
<VirtualHost *:443>
	SSLEnable
	KeyFile /opt/IBM/HTTPServer/conf/ihsserverkey.kdb
	<Location /sonar>
	</Location>
</VirtualHost>

Recommended way to define multiple App Gateways

Below you will see our recommended way to configure your Apache Module for multiple app gateways. We use /maverics as the location to handle the OIDC redirect.

MavericsOrchestratorAuthEndpoint https://maverics.enterprise.com/auth
MavericsResponseType id_token
MavericsClientID test-client
MavericsClientSecret 0123456789
MavericsRedirectURI https://org.enterprise.com/maverics/oidc
MavericsCryptoPassphrase none
MavericsResponseMode form_post
MavericsProviderIssuer https://maverics.enterprise.com

LoadFile /usr/lib64/libz.so.1
LoadModule ibm_ssl_module modules/mod_ibm_ssl.so
LoadModule maverics_module /usr/lib64/httpd/modules/mod_maverics.so
<VirtualHost *:443>
       SSLEnable
       KeyFile /opt/IBM/HTTPServer/conf/ihsserverkey.kdb
       KeepAliveTimeout 1
        <Location /sonar>
                AuthType maverics
                Require valid-user
                MavericsAppGateway Sonar
        </Location>
        <Location /crm>
                AuthType maverics
                Require valid-user
                MavericsAppGateway crm
        </Location>
        <Location /maverics>
                AuthType maverics
                Require valid-user
        </Location>
</VirtualHost>

Below is the matching fabric configuration for the Orchestrator.

fabric:
  providers:
    - authEndpoint: /auth
      issuer: https://maverics.enterprise.com
      clients:
        - clientID: test-client
          clientSecret: 0123456789
          redirectURLs:
            - https://org.enterprise.com/maverics/oidc

Maverics IIS Module (Legacy)