キーワード置換

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

​

配列の連結

キーワード置換を使って、固定の配列に値を追加したい場面があるかもしれません。このケースを直接サポートする特別な構文はありませんが、適切な値を含む単一の文字列内で二重引用符をエスケープし、## キーワード構文で挿入することで実現できます。この手法は、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: Keyword Preservation During Export を参照してください。