Maverics IIS Module (Legacy)

The Maverics IIS Module is a plug-in for Microsoft’s Internet Information Services web server. It is is primarily used for policy enforcement and sending headers to protected resources.

Server Requirements

• IIS version >= 7
• Windows Server 2012, 2016, or 2019

Install

To install the Maverics IIS Module, obtain a copy of the Microsoft Windows Installer (MSI) file from Strata, transfer it to the Windows server, and double-click the file to begin the install process.

First, you will be prompted to accept the End User License Agreement.

Next you will be prompted to choose the location of where you want the Module to be installed. A default location of C:\Program Files\Strata Identity\Maverics Module\ will be pre-populated in the dialog box.

After choosing where the Module will be installed, you will be asked to configure the secret provider and log verbosity level. The values can be changed later by updating the registry values if you are not immediately ready to configure them.

As a final step, press the “Install” button.

Configure

Maverics Config File

By default, the IIS Module will look for its configuration in:

C:\Program Files\Strata Identity\Maverics Module\maverics.yaml

Settings are grouped into orchestrator and appgateway sections:

orchestrator

The orchestrator section defines how the IIS Module connects to the Orchestrator and sets global parameters. It has the following settings:

• authEndpoint: the registered auth endpoint that is set in the Maverics Orchestrator configuration file.

• clientID: the client identifier (OIDC client ID).

• responseType: the response type used (OIDC flow). When this optional setting is not defined, the code response type is used. Supports id_token, code, id_token token, code id_token, code token, and code id_token token. When using the Orchestrator as an IdP, only id_token is supported.

• clientSecret: a secret shared between the Orchestrator and IIS Module (OIDC client secret). This should match the Orchestrator’s fabric.providers.clients.clientSecret setting.

• responseMode: the response mode used (form_post, query, or fragment). This serves as default value for discovered OIDC Provders (OPs). This is an optional field and when not defined the default response mode is form_post.

• providerIssuer: the OIDC Provider issuer identifier. If not specified, it will default to the base URL of AuthEndpoint. This should match the Orchestrator setting for fabric.providers.issuer if it is set there.

• redirectURI: the URI that the Orchestrator redirects the browser to in order to pass the authentication JWT back to the IIS Module. This parameter can also be set at the App Gateway level. If set in both places, the App Gateway value will be used. If unset, the default is to append /oidc to the base URL.

• sessionCount: the maximum number of user sessions cached by the IIS module.

• unauthorizedPage: a page that the user will be redirected to if they do not have permissions to view the requested URL.

• cookieDomain: used when setting the Domain= for the cookies being stored by the IIS Module. If unspecified, the domain is not set.

• cookiePath: used to set the Path= for the cookies stored by the IIS Module. If unspecified, the path is not set.

appgateways

The appgateways section sets the specific behavior of named App Gateways in conjunction with the Orchestrator.

• name: a descriptive and unique name that corresponds to the app being protected. Each named App Gateway should be preceded by a “-” (see YAML list format in the example below).

• basePath: the URL prefix (i.e. application path) being protected by this App Gateway. Patterns name fixed, rooted paths ("/favicon.ico") or rooted subtrees ("/images/" - note the trailing slash). Longer patterns take precedence over shorter ones, and “/” matches all paths not matched by other registered patterns (not just the root).

  Requests for the subtree root without a trailing slash will be redirected to the subtree root (i.e. adding the trailing slash) unless overridden with another patter without the trailing slash (e.g. a request for “/images” redirects to “/images/” unless another App Gateway is defined for “/images” specifically).

  Patterns can begin with a hostname, restricting matches to URLs on that host only. These patterns take precedence over patterns without hostnames.

  To use a Regular Expression, preceed the pattern with ~ (e.g. basePath: ~ ^/dept-[0-9]{2,4}/). If the pattern starts with http, the matching will take place on the entire URL. If not, it is compared against the path plus and query params portion of the URL. The one exception to this rule is for regex expressions, where the comparison also takes place agains the full URL. The comparison against the full URL allows expressions such as ~ ([\\da-zA-Z_\\.-]+)\\.randomcompany.com/development for matching particular domains as well as paths.

• redirectURL: a URL hosted on IIS that the user will be redirected to after authentication.

• policies: used to identify pages that do not require authentication. Policies are normally defined in the Orchestrator config, but simple allowUnauthenticated policies can be defined directly here:

  • location: an application URL path identifying a resource (i.e. a web page or part of a hosted application). Supports regular expressions.

  • allowUnauthenticated: set to false to allow unauthenticated access to a resource.

Example

orchestrator:
  authEndpoint: https://maverics.sonarsystems.com/auth
  responseType: id_token
  clientID: iis-module-55 
  clientSecret: axTZ3lweFRic65ynQ3aEIip6l1sgQXjp
  cryptoPassphrase: ojPqw6LoMuKl4KGKeVuX1RHdmVK7G0Q6
  responseMode: form_post
  providerIssuer: https://maverics.sonarsystems.com
  sessionCount: 50
appgateways:
  - name: sonar
    basePath: /sonar/
    redirectURI: https://app.sonarsystems.com/sonar/oidc
  - name: SecurityApp
    basePath: /securityapp/
    redirectURI: https://app.sonarsystems.com/securityapp/oidc
    policies:
      - location: /securityapp/noauth
        allowUnauthenticated: true

Allow Unauthenticated Traffic

In the following examples, we assume an application named “Sonar” is installed on your IIS machine and all request paths prefixed with /sonar/ should be routed through the defined App Gateways.

When installing the Maverics IIS Module for the first time, it can be helpful to confirm that traffic can still reach your applications. To do this, we configure unauthenticated traffic to flow through the Module.

appgateways:
  - name: Sonar
    basePath: /sonar/
    policies:
      - location: /
        allowUnauthenticated: true

Require Authentication and Enforce Policy

After proving out that the installation was successful, the next step is to require authentication and to start enforcing policy. In this configuration, we assume a remote Orchestrator pool is deployed that is responsible for handling user login.

orchestrator:
  authEndpoint: https://maverics.enterprise.com/auth
  clientID: iis-module
  clientSecret: clientSecret
  
appgateways:
  - name: IIS Protected Resources
    basePath: /sonar/

Update Log Verbosity or Secret Provider

To change the log verbosity or secret provider, you can either rerun the installer or use the Registry Editor. When using the Registry Editor, navigate to Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Strata Identity\Maverics Module in order to update the values.

NOTE: Enabling debug mode results in a decrease in performance. Debug logging is typically disabled in production environments.

Enable the IIS Module

Admins can enable the Maverics IIS Module for either all sites in a given site hierarchy or for sites individually. Typically, the module will be enabled for all sites in order to protect all resources by default. After selecting the appropriate site, click on “Modules”, then click “Configure Native Modules…”, select the “MavericsModule”, and press “OK”. After installing the IIS Module, it is necessary to restart the site and refresh the app pool in which the Maverics IIS Module is running.