Orchestrator reference

The developer documentation in this section provides code examples in YAML, a human-readable format. Please note that the Maverics Cloud Console writes configuration in JSON, and that the YAML provided in this section is for informational purposes only.

An orchestrator is a lightweight service that runs on a Linux or Window Server host and is responsible for coordinating identity and access management user flows. This service can be configured by the Maverics Platform using remote configuration providers.

The orchestrator can be configured as a universal adaptor for identity services and applications in a number of ways:

• To sit “in front” of an application (or many applications) as an identity-aware reverse proxy, controlling user access directly after authenticating the user with an identity provider
• To act as a SAML and/or OIDC identity provider, creating assertions and tokens which the apps can consume, even when the protocol the app requires is different from what the chosen IDP provides
• To act as a SAML and/or OIDC client, connecting to any IdP supporting those standards and using them as the backing identity provider for apps
• To combine identity attributes from multiple sources into a single login experience, fetching user details from whatever system or directory they reside in, without having to synchronize the sources with each other.

Versioning

The Orchestrator follows SemVer Versioning. For more information, see Orchestrator Versioning.

Configuration components

Connectors

Orchestrators use Connectors (Identity Services in Maverics Platform) to integrate with legacy and cloud identity providers as either authentication providers or attribute providers. Some can act as both.

See the list of available Connectors for additional information.

Attributes, Attribute Providers, and Namespacing

Some applications require attributes that are not provided through claims from the IDP. Orchestrators use Connectors to provide attributes that are stored outside of the identity system configured as the authentication provider. These attribute providers are LDAP directories, databases, and other identity stores. When an Orchestrator retrieves attributes from a provider, those attributes are namespaced according to the Connector that retrieves them. For example, a username provided by Azure Active Directory would be defined as azure.username where an email attribute provided by a LDAP directory would be defined as ldap.mail. Namespaced attributes are used when mapping those attributes into HTTP headers that are sent to proxied upstream applications.

Proxy Apps

An orchestrator instance can act as a proxy between a user agent (e.g., a browser) and upstream applications. Orchestrators support multiple deployment models, including centralized proxying with a smaller number of consolidated instances or distributed proxying with many distributed instances.

When configured as a proxy, the orchestrator can rewrite URLs, modify request and response headers, use conditions such as session state to redirect users to an IdP to login, and use policy evaluations to route users to specified URLs such as error or access denied pages.

Proxy apps determine which identity systems should be used to authenticate users or provide attributes, extend those identity systems by managing sessions or evaluating and enforcing policies, and map attributes to headers that legacy on-premises or cloud-hosted apps need to allow access.

See the Proxy apps reference for more details.

Policy

Orchestrators use the policies configuration in apps to define and control access to applications. Policies determine what conditions must be met for a request to succeed. Success is based on the authentication state of the user, attributes she may carry in claims from one or more IDPs, membership in a group stored in an attribute provider, or arbitrary conditions specified in Golang service extensions.

Headers

Some upstream applications require specific values in HTTP headers before allowing user access. Headers defined in apps determine how to set these headers, which values to provide, and which authentication provider or attribute provider to get the attributes from. Header configuration is a mapping of the HTTP header’s name to the value declared in a namespace such as SM_USER: azure.username or firstname: ldap.givenName.

OIDC and SAML Apps

The orchestrator itself can function as an OIDC or SAML authentication provider. When configured with one or more Connectors to provide authentication and user attributes, this configuration allows OIDC or SAML apps to treat the orchestrator as their IDP, effectively federating the upstream IDP and translating between OIDC and SAML as required for the application.

See the OIDC app reference and SAML app reference for configuration details.

Sessions & User State

Orchestrators use an in-memory store to manage sessions. Sessions hold information about the authentication state of the user, policies and evaluation outcomes, attributes, and headers.

See the sessions and user state reference for configuration details.

Service Extensions

Service extensions can provide custom policy evaluation, perform sophisticated attribute mappings, call out to other services or APIs for additional data or logic, and generally extend the functionality of the orchestrator. These service extensions are written in Golang which provides great power and flexibility.

See the Service Extension section for detailed usage and configuration information.

JSON versus YAML configuration

Orchestrators support configurations in either YAML and JSON serialization formats. JSON is usually used programmatically (for example, in machine-to-machine communications), and is the format used in configuration bundles published by the Maverics web interface. YAML is a more human-readable format and is used in many configuration examples in this documentation.

The Maverics platform creates orchestrator configuration in JSON where values are presented in alphabetical order. YAML configurations are documented here in an order that is logical to the orchestrator. Note the differences in the code below.

version: 8
​
tls:
maverics:
  certFile: /etc/maverics/certs/example_com.crt
  keyFile: /etc/maverics/certs/example_com.key
​
http:
address: :443
tls: maverics
​
apps:
- name: ExampleCo 
  type: proxy
  routePatterns:
    - /
  upstream: https://example.net:8443
  policies:
    - location: /
      authentication:
        idps:
        - keycloak
      authorization:
        allowAll: true
​
connectors:
- name: keycloak
  type: oidc
  oauthClientID: Client-09824357
  oauthClientSecret: <9824357-secret>
  oauthRedirectURL: https://example.com/oidc
  oidcLogoutCallbackURL: https://example.com/oidc/logout
  oidcWellKnownURL: https://keycloak.example.com/realms/int/.well-known/openid-configuration

{
"apps": [
  {
    "name": "ExampleCo",
    "policies": [
      {
        "authentication": {
          "idps": [
            "keycloak"
          ]
        },
        "authorization": {
          "allowAll": true
        },
        "location": "/"
      }
    ],
    "routePatterns": [
      "/"
    ],
    "type": "proxy",
    "upstream": "https://example.net:8443"
  }
],
"connectors": [
  {
    "name": "keycloak",
    "oauthClientID": "Client-09824357",
    "oauthClientSecret": "<9824357-secret>",
    "oauthRedirectURL": "https://example.com/oidc",
    "oidcLogoutCallbackURL": "https://example.com/oidc/logout",
    "oidcWellKnownURL": "https://keycloak.example.com/realms/int/.well-known/openid-configuration",
    "type": "oidc"
  }
],
"http": {
  "address": ":443",
  "tls": "maverics"
},
"tls": {
  "maverics": {
    "certFile": "/etc/maverics/certs/example_com.crt",
    "keyFile": "/etc/maverics/certs/example_com.key"
  }
},
"version": 8
}