Orchestrator reference
Protecting web servers
RP & IDP Orchestrators

RP & IDP Orchestrators

What is an RP Orchestrator?

A Relying Party (RP) Orchestrator is a like-for-like replacement of web server modules. It includes module-style configuration and an integration with the Orchestrator’s OIDC auth provider. It solves the problem of customers needing to make sure that unauthenticated side-channel traffic cannot reach a web server hosted application or having to change networking to accommodate Maverics as a proxy. This communication uses the OIDC protocol with custom claims for defining App Gateway policies.

How is it used?

In this configuration, authentication and authorization policies are defined on the IdP Orchestrator in App Gateways. These policies are enforced by the RP Orchestrator instances, which are often co-located with the web server they protect.

This scenario requires a fabric of connected orchestrators:

  • IdP Orchestrators are configured as a provider
  • RP Orchestrators are configured as a consumer

Prerequisites

  • Know the environment: Host and port of webserver, host and port of app, host and port of IdP orchestrator pool
  • Know where TLS is being used, which folder the certificates are located, and whether or not the Maverics user can access the folder
  • Ensure maverics IDP configuration is valid
  • Ensure proposed Maverics RP config is valid based on the IDP config

Provider (IdP) Configuration options

IdP Orchestrator configuration is defined in a providers block under fabric in maverics.yaml (see example).

The following options must be set:

authEndpoint The location where the Orchestrator will serve its authorization endpoint.

issuer Set the issuer to the FQDN of the Orchestrator.

clients A list of registered OIDC clients.

clientID A unique identifier issued to a given client.

clientSecret A unique secret issued to a given client.

redirectURLs A list of endpoints that a client can use to receive a redirect callback.

Provider Configuration Example 

fabric:
  providers:
    - authEndpoint: /auth
      issuer: https://maverics.sonarsystems.com
      clients:
        - clientID: rp-orchestrator-1
          clientSecret: <secret-from-vault>
          redirectURLs:
            - https://app.sonarsystems.com/oidc
            - https://www.sonarsystems.com/oidc

Consumer (RP) Configuration options

The Fabric consumers section contains settings for:

  • a simple proxy configuration
  • settings for a Relying Party (RP) OIDC client

Consumer Proxy Settings

  • upstream: (Required) The url of app that is being protected and proxied to. This could be an IP address or hostname and the port the application listens on. Required.

  • basePath: (Optional. Default is “/”) A path on the application. When combined with host this creates the listen address.

  • host: (Optional) A hostname or fully qualified domain name the RP Orchestrator is listening for. Use this to differentiate between multiple provider configurations that behave differently depending on the hostname in the HTTP request (i.e. if the Orchestrator receives requests on different virtual hostnames).

  • preserveHost: (Optional. Default is false) A boolean field used to determine if the Host header should be preserved on outbound requests. By default, the Orchestrator will set the host header to match the upstream’s host. This field is often used when the Orchestrator is forwarding traffic to another reverse proxy such as Apache.

Consumer OIDC Client Settings

  • authEndpoint: the registered auth endpoint exposed by the IdP Orchestrator.

  • clientID: the client identifier (OIDC client ID) for this RP orchestrator instance, matching a clientID in the IdP Orchestrator’s Fabric configuration.

  • clientSecret: a secret shared between the IdP Orchestrator and RP Orchestrator (OIDC client secret), matching a clientSecret in the Fabric configuration.

  • providerIssuer: the OIDC Provider issuer identifier. This should match the issuer in the Fabric configuration (if set).

  • redirectURL: the URL that the browser is redirected to in order to pass the authentication JWT back to the RP Orchestrator. This field is required and must be a full URL (e.g. https://app.sonarsystems.com/oidc).

  • unauthorizedPage is the URL a user is redirected to when a policy evaluation denies access to the app.

  • appgatewayMappings: a list of location paths on the protected applications with their corresponding appgatewayName.

    • location: a URL path (e.g. /assets/img) or a regular expression for matching paths (e.g. ~ ^/assets.*)
    • appgatewayName: the name of the corresponding App Gateway on the IdP Orchestrator.

  • ignoredPaths: a list of paths to ignore on the protected applications. The orchestrator will pass the connection through to the target web server without applying any policy or headers. Supports regular expressions (e.g. ~ ^/assets.*)

Consumer Configuration Example

A consumer configuration is typically used in a Web Server with Local Orchestrator deployment:

fabric:
  consumers:
      # Proxy Config
    - basePath: / # Optional. Defaults to "/"
      upstream: http://127.0.0.1:8080 # Required
      host: app.sonarsystems.com # Optional
      preserveHost: false # Optional
      # OIDC Config
      authEndpoint: https://maverics.sonarsystems.com:8443/auth
      clientID: rp-orchestrator-1
      clientSecret: hardcoded-secret (This is not pulled from the secret provider)
      providerIssuer: https://maverics.sonarsystems.com
      redirectURL: https://app.sonarsystems.com/oidc
      unauthorizedPage: https://app.sonarsystems.com/sonar/accessdenied
      appgatewayMappings:
        - location: /
          appgatewayName: sonar-app1
        - location: /resources
          appgatewayName: sonar-resources 
      ignoredPaths:
        - /api
Maverics WebSphere TAI Module