Migrating from legacy configuration

We have recently redesigned Maverics to use an app-centric model to better support customer goals. This update brings some exciting new features to the Maverics UI and configuration.

While the Maverics configuration language has been updated to support the new domain model, the orchestrator remains backward-compatible and will still support legacy configuration and service extensions. However, new features will only be available to the new configuration format.

This guide summarizes the features of our new configuration to help you understand how it differs from our legacy configuration. For information on migrating legacy service extensions, see our service extension migration guide.

AppGateways are now proxy apps

Proxy apps are declared under apps, type: proxy.

Proxied apps have replaced AppGateways. Proxied apps have the same functionality as AppGateways but are implemented differently in the configuration, using the same model as OIDC and SAML apps.

apps:
  - name: ExampleCo 
    type: proxy

appgateways:
  - name: ExampleCo
    host: example.com

Host and base path are now declared as routePatterns. You can list as many URLs under routePatterns as needed.

apps:
  - name: ExampleCo 
    type: proxy
    routePatterns:
    # combines host and basePath, and you can specify multiple 
      - example.com
      - example.org

appgateways:
  - name: ExampleCo
    host: example.com 
    basePath: /

Auth providers are now declared as OIDC or SAML providers.

samlProvider:
  - name: ExampleIDP
    type: saml
    metadataEndpoint: https://maverics.example.com/idp/saml/metadata.xml
    singleSignOnServiceEndpoint: https://maverics.example.com/sso
    singleLogoutServiceEndpoint: https://maverics.example.com/slo
    issuer: https://maverics.example.com

apps:
  # Service Providers (SPs) are now defined as SAML apps 
  - name: exampleSAMLApp
    type: saml
    audience: https://sp.example.com/
    consumerServiceURL: https://example.com/saml/acs
    requestVerification:
      certificate: <appSigningCertificate>
    authentication:
      idps:
        - azure
    claimsMapping:
      id: azure.name
      email: azure.email
      lastName: azure.surname

authproviders:
  - name: ExampleIDP
    type: saml
    metadataEndpoint: https://maverics.example.com/idp/saml/metadata.xml
    singleSignOnServiceEndpoint: https://maverics.example.com/sso
    singleLogoutServiceEndpoint: https://maverics.example.com/slo
    issuer: https://maverics.example.com
    # Service Providers (SPs) were defined under the SAML provider
    clients:
      - name: ExampleSP 
        audience: https://sp.example.com/
        consumerServiceURL: https://example.com/saml/acs
        duration: 60
        requestVerification:
          certificate: <appSigningCertificate>
        authentication:
          idps:
            - azure
        claimsMapping:
          id: azure.name
          email: azure.email
          lastName: azure.surname

oidcProvider:
  discovery:
    issuer: https://orchestrator.example.com
    endpoints:
      wellKnown: https://orchestrator.example.com/.well-known/openid-config
      jwks: https://orchestrator.example.com/.well-known/jwks.json
      auth: https://orchestrator.example.com/oauth2/auth
      token: https://orchestrator.example.com/oauth2/token
      userinfo: https://orchestrator.example.com/userinfo
      introspect: https://orchestrator.example.com/introspect
      revoke: https://orchestrator.example.com/revoke
  jwks:
    # Previously under tokenSigning
    - algorithm: RSA256
      privateKey: <oidcRSATestPrivateKey>

apps:
  # Clients are now defined as OIDC apps
  - name: exampleOIDCApp
    type: oidc
    clientID: exampleClient
    clientSecret: <exampleSecret>
    redirectURLs:
      - https://app.example.com/oidc
    allowedAudiences:
      - https://app.sonarsystems.com
    allowOfflineAccess: true
    authentication:
      idps:
        - azure
    claimsMapping:
      email: azure.email
      family_name: azure.surname
      given_name: azure.givenname

authproviders:
  - name: ExampleIDP
    type: oidc
    wellKnownEndpoint: https://orchestrator.example.com/.well-known/openid-configuration
    jwksEndpoint: https://orchestrator.example.com/.well-known/jwks.json
    authorizationEndpoint: https://orchestrator.example.com/authorize
    tokenEndpoint: https://orchestrator.example.com/token
    userInfoEndpoint: https://orchestrator.example.com/userinfo
    introspectEndpoint: https://orchestrator.example.com/introspect
    issuer: https://orchestrator.example.com
    tokenSigning:
      - algorithm: RSA256
        privateKey: <oidcRSATestPrivateKey>

    clients:
      - clientID: exampleClient
        clientSecret: <exampleSecret>
        redirects:
          - https://app.sonarsystems.com/oidc/callback
        allowedAudiences:
          - https://app.sonarsystems.com
        allowOfflineAccess: true
        authentication:
          idps:
            - azure
        claimsMapping:
          email: azure.email
          family_name: azure.surname
          given_name: azure.givenname

Headers are declared as name/value pairs, and you can now specify static strings.
Double curly braces are used as a more flexible structure to accommodate future needs.

apps:
  - name: ExampleCo 
    type: proxy
    routePatterns:
    # combines host and basePath, and you can specify multiple 
      - example.com
      - example.org
    upstream: https://app.example.net:8443
    headers:
    # header name and value now declared separately
    # same "{{ templating syntax }}" as authorization policy
      # Example of  static string header
      - name: organization
        value: Example
      - name: firstname 
        value: "{{ keycloak.given_name }}"
      - name: lastname
        value: "{{ keycloak.family_name }}"

appgateways:
  - name: ExampleCo
    host: example.com 
    basePath: /
    upstream: https://app.example.net:8443
    headers:
      firstname: keycloak.given_name 
      lastname: keycloak.family_name

Policy now includes some new operators.
- notEquals and notContains have replaced the “not” operator used in AppGateways.
You can now declare app-specific logout URLs.

apps:
  - name: ExampleCo 
    type: proxy
    routePatterns:
    # combines host and basePath, and you can specify multiple 
      - example.com
      - example.org
    upstream: https://app.example.net:8443
    headers:
    # header name and value now declared separately
    # same "{{ templating syntax }}" as authorization policy
      - name: firstname 
        value: "{{ keycloak.given_name}}"
      - name: lastname
        value: "{{ keycloak.family_name}}"
    policies:  # policies are the same
      - location: /
        authentication:
          idps:
            - keycloak
        authorization:
          allowAll: false
          rules:
            - and:
                - equals: ["{{ ldap.department }}", "Engineering"]
                - notEquals: ["{{ ldap.title }}", "Junior Software Engineer"]
                - contains: ["{{ ldap.memberOf }}", "cn=admins,ou=groups,ou=example,ou=com"]
            - or:
                - contains: ["{{ keycloak.emailaddress }}", "@example.com"]
                - contains: ["{{ keycloak.emailaddress }}", "@example.io"]
                - notContains: ["{{ keycloak.emailaddress }}", "@example.org"]

appgateways:
  - name: ExampleCo
    host: example.com 
    basePath: /
    upstream: https://app.example.net:8443
    headers:
      firstname: keycloak.given_name 
      lastname: keycloak.family_name
    policies:
      - location: /
        authentication:
          idps:
            - keycloak
        authorization:
        authorization:
          allowAll: false
          rules:
            - and:
                - equals: ["{{ ldap.department }}", "Engineering"]
                - not:
                     equals: ["{{ ldap.title }}", "Junior Software Engineer"]
                - contains: ["{{ ldap.memberOf }}", "cn=admins,ou=groups,ou=example,ou=com"]
            - or:
                - contains: ["{{ azure.emailaddress }}", "@example.com"]
                - contains: ["{{ azure.emailaddress }}", "@example.io"]
                - not:
                  contains: ["{{ azure.emailaddress }}", "@example.org"]

Proxied apps in Maverics

In the Maverics app, proxied apps have replaced header-based apps.

Proxied App

In the Maverics app, you can specify the upstream URL, route patterns, CA path, app-specific logout URL, and post logout redirect URL.

Proxied App

Service extension enhancements

As part of this update, we’ve made a number of enhancements to our service extensions:

We now have code compilation and other common IDE features so they can be programmatically tested within the Maverics app.
We’ve improved documentation and examples available in Godoc.
We’ve made interfaces more consistent, thus enabling the reuse of extensions across different app types.

Service extension code editor

There’s now 1:1 parity between what can be done with manual YAML configuration and the configuration generated in the Maverics app.

What is no longer supported in service extensions

AppGateways has been replaced by orchestrator.

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
}

View orchestrator telemetry Orchestration recipes