Migration à partir d’une configuration existante

Nous avons récemment repensé Maverics de manière à utiliser un modèle centré sur l’application afin de mieux satisfaire les objectifs des clients. Cette mise à jour apporte de nouvelles fonctionnalités à l’interface utilisateur et à la configuration de Maverics.

Bien que le langage de configuration de Maverics ait été mis à jour pour prendre en charge le nouveau modèle de domaine, l’orchestrateur reste rétrocompatible et continuera à prendre en charge les extensions de services et de configuration existantes. Cependant, les nouvelles fonctionnalités ne seront disponibles que pour le nouveau format de configuration.

Ce guide présente les caractéristiques de notre nouvelle configuration afin de vous aider à comprendre en quoi elle diffère de l’ancienne. Pour plus d’informations sur la migration des anciennes extensions de services, consultez notre Guide de migration des extensions de services.

Les AppGateways sont désormais des applications proxy

Les applications proxy sont déclarées sous apps, type: proxy.

Les applications proxy ont remplacé les AppGateways. Les applications proxy possèdent les mêmes fonctionnalités que les AppGateways mais sont implémentées différemment dans la configuration, en utilisant le même modèle que les applications OIDC et SAML.

apps:
  - name: ExampleCo
    type: proxy

appgateways:
  - name: ExampleCo
    host: example.com

Le chemin hôte et le chemin de base sont désormais déclarés en tant que routePatterns. Vous pouvez lister autant d’URL sous routePatterns que nécessaire.

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: /

Les fournisseurs d’authentification sont désormais déclarés en tant que fournisseurs OIDC ou SAML.

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

Les en-têtes sont déclarés sous forme de paires nom/valeur et il est désormais possible de spécifier des chaînes statiques.
Les doubles accolades sont utilisées pour créer une structure plus souple permettant de répondre aux exigences futures.

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

La politique inclut désormais de nouveaux opérateurs.
- notEquals et notContains ont remplacé l’opérateur « not » utilisé dans AppGateways.
Il est désormais possible de déclarer des URL de déconnexion spécifiques à l’application.

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"]

Applications proxy dans Maverics

Dans l’application Maverics, les applications proxy ont remplacé les applications basées sur les en-têtes.

Application proxy

Dans l’application Maverics, il est possible de spécifier l’URL en amont, les modèles de routage, le chemin de l’autorité de certification, l’URL de déconnexion spécifique à l’application et l’URL de redirection après la déconnexion.

Application proxy

Améliorations des extensions de services

Dans le cadre de cette mise à jour, nous avons apporté un certain nombre d’améliorations à nos extensions de services :

Nous disposons maintenant de la compilation du code et d’autres fonctionnalités IDE courantes afin de pouvoir les tester de manière programmatique au sein de l’application Maverics.
Nous avons amélioré la documentation et les exemples disponibles dans Godoc.
Nous avons rendu les interfaces plus cohérentes, ce qui permet de réutiliser les extensions dans différents types d’applications.

Éditeur de code d’extensions de services

La parité entre ce qui peut être fait avec une configuration YAML manuelle et la configuration générée dans l’application Maverics est maintenant de 1:1.

Les extensions de services ne prennent plus en charge les éléments suivants

AppGateways a été remplacé par l’orchestrateur.

Configuration JSON ou YAML

Les orchestrateurs prennent en charge les configurations dans les formats de sérialisation YAML et JSON. JSON est généralement utilisé dans un contexte programmatique (par exemple, dans les communications de machine à machine), il s’agit du format utilisé dans les paquets de configuration publiés par l’interface web de Maverics. YAML est un format plus lisible par les humains et est utilisé dans de nombreux exemples de configuration figurant dans la présente documentation.

La plateforme Maverics établit la configuration de l’orchestrateur au format JSON qui présente les valeurs dans l’ordre alphabétique. Les configurations YAML sont documentées ici dans un ordre cohérent pour l’orchestrateur. Notez les différences dans le code ci-dessous.

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
}

Affichage de la télémétrie de l’orchestrateur Recettes d’orchestration