キーワード置換

キーワード置換を使用して、Auth0 Deploy CLI でマルチテナントのワークフローを管理する方法を学習します。

Deploy CLI は、環境固有の値を使用した動的なキーワード置換をサポートしています。これにより、すべてのテナントで同じリソース設定ファイルを共有しながら、微妙に異なる値を挿入できる、スケーラブルなマルチテナント ワークフローを実現できます。

キーワード置換を使用するには、AUTH0_KEYWORD_REPLACE_MAPPINGS 設定プロパティに適切なマッピングを含める必要があります。次に、リソース設定ファイルでは、次の 2 つの方法のいずれかでキーワードを埋め込むことができます。

1. @@EXAMPLE_KEY@@: @ 記号を使用すると、ツールは置換前に値に対して JSON.stringify を実行します。そのため、値が文字列の場合は引用符が追加され、値が配列またはオブジェクトの場合は波かっこが追加されます。
2. ##EXAMPLE_KEY##: # 記号を使用すると、ツールはリテラル置換を実行し、引用符や波かっこは追加されません。

​

config.json の例

{
  "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.yaml の例

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@@

​

tenant.json の例

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

​

配列の連結

キーワード置換を使って、静的な配列に値を連結したい場合があります。このケースをサポートする特別な構文はありませんが、必要な値を含む 1 つの文字列内で二重引用符をエスケープし、## キーワード構文で挿入することで実現できます。この手法は、YAML 形式とディレクトリ形式の両方で使用できます。

​

config.json の例

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

​

tenant.yaml の例

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

​

エクスポート時にキーワードを保持する

一般に、Deploy CLI は、下位環境 (例: dev、test) から本番環境へ進む一方向のワークフローで使用する場合に最も効果を発揮します。ただし、上位環境の設定をローカルの設定ディレクトリにエクスポートする必要が生じることもあります。デフォルトでは、リモートの値がローカルの値を上書きするため、キーワードマーカーが削除されます。ただし、キーワード置換の保持機能は、AUTH0_PRESERVE_KEYWORDS ブール値の設定プロパティで有効にできます。この設定を有効にすると、Deploy CLI はエクスポート時に、ローカルの設定ファイルで定義されたキーワードマーカーを保持しようとします。

キーワード保持機能は、リソース設定ファイルの正確性を維持しながら、できるだけ多くのキーワードを保持しようとします。また、ほとんどの場合はユーザーが介入しなくても機能します。ただし、いくつかの重要な制限があります。

• キーワード置換された設定フィールドでローカルとリモートの値が異なる場合、常にローカルの設定値が優先されます。つまり、リソース定義ファイル内でそのフィールドの値のどこかにキーワード置換マーカーが存在する場合、リモート側で直接行われた変更はすべて消去されます。この動作に「賢い」調整処理はありません。
• 特定の識別子がない配列は保持の対象になりません。例: ["http://site.com/logout", "localhost:3000/logout", "##LOGOUT_URL##"]。これは、これらの値の順序が一定でないためです。これらの値を保持するには、代わりに値全体に対して @@ARRAY_REPLACE@@ キーワード置換構文を使用することを推奨します。

キーワード保持の経緯や技術的な課題の詳細については、RFC: エクスポート時のキーワード保持 を参照してください。