Remplacement de mots-clés

L’outil Deploy CLI prend en charge le remplacement dynamique des mots clés par des valeurs propres à l’environnement. Cela permet un flux de production multi-locataires évolutif où tous les locataires partagent les mêmes fichiers de configuration des ressources mais injectent des valeurs subtilement différentes.

Pour utiliser le remplacement de mots clés, la propriété de configuration AUTH0_KEYWORD_REPLACEMENT_MAPPINGS doit contenir les mappages appropriés. Les mots-clés peuvent ensuite être injectés dans les fichiers de configuration des ressources de deux manières :

1. @@EXAMPLE_KEY@@: L’utilisation du symbole @ permet à l’outil d’effectuer la méthode JSON.stringify sur votre valeur avant de la remplacer. Ainsi, si votre valeur est une chaîne de caractères, l’outil ajoutera des guillemets; si votre valeur est un tableau ou un objet, l’outil ajoutera des accolades.

2. ##EXAMPLE_KEY##: L’utilisation du symbole # permet à l’outil d’effectuer un remplacement littéral; l’outil n’ajoute pas de guillemets ni d’accolades.

{
  "AUTH0_DOMAIN": "test-tenant.us.auth0.com",
  "AUTH0_CLIENT_ID": "FOO",
  "AUTH0_CLIENT_SECRET": "BAR",
  "AUTH0_KEYWORD_REPLACE_MAPPINGS": {
    "ENVIRONMENT": "dev",
    "ALLOWED_LOGOUT_URLS": ["https://dev-test-site.com/logout", "localhost:3000/logout"],
    "ALLOWED_ORIGINS": ["https://dev-test-site.com", "localhost:3000"]
  }
}

tenant:
  friendly_name: "##ENVIRONMENT## tenant"
  allowed_logout_urls: @@ALLOWED_LOGOUT_URLS@@
  enabled_locales:
    - en
clients:
  - name: Test App
    allowed_origins: @@ALLOWED_ORIGINS@@
    allowed_logout_urls: @@ALLOWED_LOGOUT_URLS@@

{
  "friendly_name": "##ENVIRONMENT## tenant",
  "allowed_logout_urls": "@@ALLOWED_LOGOUT_URLS@@"
}

Vous pouvez rencontrer des situations où vous souhaitez concaténer des valeurs dans un tableau statique par remplacement de mots-clés. Il n’existe pas de syntaxe spéciale pour ce cas, mais il est possible d’y parvenir en échappant les guillemets doubles dans une chaîne unique contenant les valeurs appropriées et en injectant avec la syntaxe de mot-clé ##. Cette technique fonctionne à la fois pour les formats YAML que répertoire.

{
  "AUTH0_KEYWORD_REPLACE_MAPPINGS": {
    "GLOBAL_WEB_ORIGINS": "\"http://local.me:8080\", \"http://localhost\", \"http://localhost:3000\""
  }
}

clients:
  - name: Test App
    web_origins: [ "http://production-app.com", "https://production-app.com", ##GLOBAL_WEB_ORIGINS## ]

Généralement, l’outil Deploy CLI fonctionne mieux lorsqu’il s’agit d’opérer dans un flux de production unidirectionnel depuis vos environnements de niveau inférieur (p. ex., dev, test) jusqu’à vos environnements de production. Cependant, il peut arriver qu’il soit nécessaire d’exporter la configuration d’un environnement de niveau supérieur vers votre répertoire de configuration local. Par défaut, les valeurs distantes écraseront vos valeurs locales, entraînant la suppression de vos marqueurs de mots-clés. Toutefois, la préservation du remplacement de mots-clés peut être activée grâce à la propriété de configuration booléenne AUTH0_PRESERVE_KEYWORDS. En activant cette configuration, l’outil Deploy CLI tentera de préserver les marqueurs de mots-clés définis dans vos fichiers de configuration locaux lors de l’exportation.

La fonctionnalité de préservation des mots-clés tentera de préserver autant de mots-clés que possible tout en maintenant l’exactitude de vos fichiers de configuration des ressources. Dans la majorité des cas, elle fonctionnera sans aucune intervention de l’utilisateur. Cependant, il existe certaines limitations importantes :

• Dans le cas d’un champ de configuration remplacé par un mot-clé dont les valeurs diffèrent entre le local et le distant, la valeur de la configuration locale sera toujours privilégiée. Cela entraînera l’effacement de toute modification hors bande à distance si un marqueur de remplacement de mot-clé existe n’importe où dans la valeur de ce champ dans le fichier de définition de la ressource; la réconciliation « intelligente » est impossible.

• Les tableaux sans identifiant particuliers ne sont pas admissibles à la préservation. Exemple : ["http://site.com/logout", "localhost:3000/logout", "##LOGOUT_URL##"]. En effet, l’ordre de ces valeurs n’est pas déterministe. Pour préserver ces valeurs, il est recommandé d’utiliser la syntaxe de remplacement du mot-clé @@ARRAY_REPLACE@@ avec la valeur entière.

Pour en savoir plus sur l’histoire et les défis techniques de la préservation des mots-clés, consulterRFC : Préservation des mots clés lors de l’exportation.