Search
K

Migrating to the Maverics UI

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.
New Config
Legacy Config
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.
New Config
Legacy Config
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.
New SAML Config
Legacy SAML AuthProvider Config
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
New OIDC Config
Legacy OIDC AuthProvider Config
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.
New Config
Legacy Config
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.
New Config
Legacy Config
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 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.
YAML
JSON
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
}