メールテンプレートをカスタマイズする

テンプレート言語Liquidの構文を使ってメールをカスタマイズする方法について説明します。

カスタマイズしたメールを送信するには、プロバイダーまたはテンプレートレベルで差出人のアドレスを構成する必要があります。詳細については、「テンプレートのフィールドを構成する」の「 差出人のアドレスを構成する 」セクションをお読みください。

メールをカスタマイズできるようにするには、サードパーティサービス（Amazon SES、Mandrill、SendGrid、SparkPost、Mailgun、またはカスタムSMTPプロバイダーなど）を使って、自分のメールプロバイダーを構成する必要があります。詳細については、「外部SMTPプロバイダーを構成する」をお読みください。

Auth0では、DashboardでHTMLベースのメールをカスタマイズするほか、Liquidを使って一部のコンテキスト属性を含むテンプレートを作成することができます。詳細については、「メールテンプレートでのLiquid構文の使用」をお読みください。これには、現在のアプリケーションまたはユーザーのコンテキストへの参照を含むことができます。

テンプレートタイプごとに使用できるテンプレートは1つのみです。プレーンテキスト/テキストベースのメールはサポートされていません。

メールテンプレートごとに ［From Address（差出人アドレス）］ 、 ［Subject（件名）］ 、 ［Message（メッセージ）］ 本文をカスタマイズできます。Liquid構文を使ってコンテンツを動的に生成し、多数のコンテキスト変数にアクセスすることができます。メールメッセージの作成時に、これらの変数は関連する値に置き換えられます。

［Try（テスト）］ ボタンをクリックすると、Auth0から、テナントの（フレンドリー名ではない）生の名前を基にしたデフォルトのアプリ名がメールで届きます。異なるアプリに対してテンプレートをテストするには、フローの実行に使うサンプルユーザーを作成します。

ただし、特定のアプリケーションやユーザーに対しては、Auth0 Management APIのメールアドレスの確認メール送信エンドポイントを使って手動で確認メールをトリガーできます。

​

共通変数

［From Address（差出人アドレス）］ 、 ［Subject（件名）］ 、 ［Message（メッセージ）］ フィールドでLiquid構文を使用する場合、以下の共通変数にアクセスできます。

• applicationオブジェクト。以下に挙げた標準クライアントプロパティにアクセスできます。

  • application.name
  • application.clientID
  • application.metadata

• connection.name（ ［Multi-factor Enrollment Email（多要素登録メール）］ の場合を除く）

• userオブジェクト。以下に挙げたプロパティにアクセスできます。

  • user.email
  • user.email_verified
  • user.picture
  • user.nickname
  • user.given_name
  • user.family_name
  • user.name
  • user.app_metadata - ユーザーのサポートプランやセキュリティロール、アクセス制御グループといった情報を格納します。これらの情報は、アプリケーションの機能の仕組みやユーザーがアクセスできる対象など、ユーザーのコア機能に影響を与える可能性があります。
  • user.user_metadata - ユーザーのコア機能に影響しないユーザー属性（ユーザー設定など）を格納します。

• テナント関連情報（［Tenant Settings（テナント設定）］で定義）

  • tenant - 未加工のテナント名
  • friendly_name
  • support_email
  • support_url

以下のユーザープロパティは信頼できないため、Liquidのescape関数をパイプでつなげなければなりません（{{ user.name | escape }}）：

• user.picture
• user.nickname
• user.given_name
• user.family_name
• user.name

また、ユーザーが提供した情報を含むuser.user_metadataプロパティは、エスケープしなければなりません。

以下のメールテンプレートは、組織のためにさらにカスタマイズすることができます。

• Welcome（ようこそ） ：エンドユーザーのメールアドレスが検証された後、またはメール検証が無効の場合にはサインアップ（または初めてログイン）したときに、エンドユーザーが受信します。
• Password Change（パスワード変更） ：エンドユーザーがパスワードの変更を要求した際に受信します。パスワードリセットページにリダイレクトするリンクが含まれています。
• Blocked Account（アカウントのブロック） ：ユーザーが同じIPアドレスから10回以上ログインしようとして失敗したときに、エンドユーザーが受信します。
• Breached Password Alerts（侵害されたパスワードアラート） ：サードパーティーによって漏洩したパスワードを使ってアプリケーションにアクセスしようとしていることがAuth0で検出されるときに、エンドユーザーが受信します。
• Invite User（ユーザー招待） ：エンドユーザーが組織に招待された際に受信します。カスタム招待ページにリダイレクトするリンクが含まれています。詳細については、「組織メンバーを招待する」を参照してください。

ユーザーが組織からログインするときは、このほかにも以下に挙げた変数を使用することができます。

• organization.id
• organization.display_name
• organization.name
• organization.metadata
• organization.branding.logo_url
• organization.branding.colors.primary
• organization.branding.colors.page_background

変数はLiquidの{{ variable_name }}構文を使って参照されます。例：

Hello {{ user.name }}.Welcome to {{ application.name }} from {{ friendly_name }}.

userオブジェクトに使用できる属性は、使用される接続のタイプによって異なります。各メールテンプレートは、特定のテンプレートに適した追加の変数を定義します。

ユーザーがリンクをクリックしてアクションを実行する必要があるメールでは、アクションを実行した後に、 ［URL Lifetime（URLライフタイム）］ と ［Redirect To（リダイレクト先）］ URLの宛先も構成することができます。Liquid構文は ［Redirect To（リダイレクト先）］ URLフィールドでもサポートされていますが、サポートされている変数は以下の3つのみです。

• application.name
• application.clientID
• application.callback_domain

​

テンプレートフィールドを構成する

以下のフィールドを構成する必要があります。

accordion.expand_all/accordion.collapse_all

1 送信元アドレス

Auth0からメールを受信すると、送信者として 送信元アドレス フィールドにメールアドレスが表示されます。メールテンプレートの 送信元アドレス フィールドを設定しない場合、Auth0はお使いの メールプロバイダーに設定された 送信元 フィールドのメールアドレスを使用します。

セキュリティ上の理由で、カスタマイズしたメールは@auth0.comを含まない送信元ア​ドレスからしか送信できません。@auth0.comのメールアドレスを入力すると、デフォルトのメールが引き続き送信され​、カスタマイズした内容は無視されます。プライベートクラウドをご利用の場合は、類似のドメイン拒否リストを構成できます。

送信元アドレス フィールドはテンプレートの共通変数すべてに対応していますが、以下が最も一般的に使用されています。

• application.name
• friendly_name（テナントが定義したフレンドリー名）

これらの変数を使用して、 差出人アドレス の表示名を、ユーザーがサインアップしたアプリケーションに関連するものに設定することができます。たとえば、フィールドには<[e-mail]>ではなく、{{ application.name }} <[e-mail]>と表示されます。

Auth0から送信者に代わってデジタル署名済みのメールを送れるようにするには、Sender Policy Framework（SPF）（詳しくは、Wikipediaで「Sender Policy Framework (SPF)」をお読みください）とDomainKeys Identified Mail （詳しくは、Wikipediaで「DomainKeys Identified Mail (DKIM)」をお読みください）のDNSレコードをドメインのゾーンファイルに追加する必要があります。これらのレコードがないと、メールがユーザーの迷惑メールフォルダに振り分けられてしまう可能性があります。さらに、次のような 差出人アドレス がユーザーに表示される場合があります。

MyApp [e-mail] on behalf of MyApp [e-mail]

SPFの構成

SPFを構成するには、ドメインのゾーンファイルにTXTレコードを追加します。プロバイダーによっては、ホスト名を@に設定するか、空のままにする必要があります。レコードの値は次のようにします。

"v=spf1 include:spf.mandrillapp.com -all"

既にSPFレコードがある場合は、単にinclude:spf.mandrillapp.comを既存のレコードに追加することができます。

DKIMの構成

DKIMを構成するには、ドメインのゾーンファイルにTXTレコードを追加します。このドメインはメールの送信に使用するものにしてください。たとえば、Mandrillを使用している場合、このレコードのホスト名はmandrill._domainkeyに、値は次のように設定します。

v=DKIM1; k=rsa; 
p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCrLHiExVd55zd/IQ/J/mRwSRMAocV/hMB3jXwaHH36d9NaVynQFYV8NaWi69c1veUtRzGt7yAioXqLj7Z4TeEUoOLgrKsn8YnckGs9i3B3tVFB+Ch/4mPhXWiNfNdynHWBcPcbJ8kjEQ2U8y78dHZj1YeRXXVvWob2OaKynO8/lQIDAQAB;

2 件名

Subject（件名） フィールドは、テンプレートに共通する次を含むすべての変数に対応しています。

• application.name
• user.email（およびuserオブジェクトのその他のプロパティ）

Subject（件名） フィールドが空の場合、Auth0は送信するメールの種類に応じてこのテキストを自動入力します。たとえば、ある件名行が「メールを確認してください。」であるとします。

多言語の件名行

ユーザーが選択した言語は、user.user_metadataと、Subject（件名）フィールドに使用されるLiquid構文に格納することができます。

例：

{% assign language = request_language %}
  {% if language %}
    {% assign language = request_language | slice: 0,2 %}
  {% endif%}
{% if language == 'es' %}
  Cuenta de Example: bloqueada
{% elsif language == 'de' %}
  Ihr Example wurde gesperrt
{% elsif language == 'fr' %}
  Compte Example bloqué
{% elsif language == 'ja' %}
  Example アカウントがブロックされました
{% elsif language == 'pt' %}
  Conta da Example bloqueada
{% elsif language == 'zh' %}
  Example　帐户被阻止
{% else %}
  Example account blocked
{% endif %}

3 URLライフタイム

検証メール 、 パスワード変更 、 ブロックされたアカウントのメール には、ユーザーがサインアップ時にメールアドレスを確認したり、パスワードの変更を確認したり、ブロックされたアカウントのブロックを解除したりできるリンクが含まれています。

セキュリティ上の理由から、このリンクのライフタイムは変更が可能です。デフォルトのライフタイムは432,000秒（5日）です。

期限切れリンクがクリックされたときに リダイレクト先 URLが設定されていると、ユーザーは設定された リダイレクト先 URLにリダイレクトされます。クエリ文字列に次のテキストが追加されます。

http://myapplication.com/my_page/?email=john%contoso.com&message=Access%20expired.&success=false

4 リダイレクト先URL

リダイレクト先 URLは、関連アクション（アカウントの確認、パスワードのリセット、アカウントのブロック解除）が実行された後にユーザーをリダイレクトする任意の移動先です。

ユニバーサルログインクラシックエクスペリエンスでは、パスワードのリセット後にリダイレクトされるURLを指定できます。Auth0はそのURLにsuccessインジケーターとmessageを送信します。これら2つのパラメーターの詳細については、メールテンプレートの説明をご覧ください。

New Universal Loginエクスペリエンスでは、ユーザーがパスワードのリセットに成功した場合、Auth0はユーザーをデフォルトのログインルートにリダイレクトします。そうでない場合、Auth0はユニバーサルログインフローの一部としてエラーを処理し、メールテンプレートに入力されたリダイレクトURLを無視します。

リダイレクト先 URLでは、次の3つの変数のみが使用できます。

• application.name（またはその同義語のclient.name）
• application.clientID
• application.callback_domain（またはその同義語のclient.callback_domain）

application.callback_domain変数には、アプリケーションの Allowed Callback URL（許可されているコールバックURL） リストに記載されている 最初の URLのオリジンが含まれます。これにより、次のような構文を使用して、アクションをトリガーしたアプリケーションのパスにユーザーをリダイレクトすることができます。

{{ application.callback_domain }}/result_page

この変数はcallback_domainと呼ばれますが、実際にはオリジンであるため、ドメイン（例：https://myapp.com）に加えてプロトコルが含まれていることに注意してください。

アプリケーションに複数の Allowed Callback URL（許可されているコールバックURL） が設定されている場合、Auth0はリストに載っている最初のURLを使用します。Liquid構文を使用して、デフォルトのオリジンを指定することもできます。

{{ application.callback_domain | default: "https://my-default-domain.com" }}/result_page

URLへの動的リダイレクト

アプリケーション名に基づいて、別のリダイレクト先URLをセットアップできます。例：

{% if application.name == 'JWT.io' %} https://jwt.io {% else %} https://auth0.com {% endif %}

アプリケーション名はセキュリティ上エンコードされているため、常にエンコードされた値を使用してください（特に、アプリケーション名にエンコード後に変更される文字が含まれている場合）。たとえば、My Appの場合は、代わりにMy%20Appを使用します。

シングルページアプリケーション（SPA）の場合、 リダイレクト先 URLには、アプリ内の特定の状態/ビューのハッシュとルート、それに続くルートパラメーターを含めることができます。その場合、 リダイレクト先 URLで次の問題が発生する可能性があります。

http://localhost:3000/#/register

これにより、ユーザは次のURLにリダイレクトされます：

http://localhost:3000/?supportSignUp=true
  &supportForgotPassword=true
  &email=john.doe%40exampleco.com
  &message=Your%20email%20was%20verified.%20You%20can%20continue%20using%20the%20application.
  &success=true#/register

これは、期待されるURLの順序をscheme|authority|path|query|fragmentとして定義している、インターネット標準（詳細はインターネット技術特別調査委員会（IETF、Internet Engineering Task Force）作成の「RFC 3986」仕様をお読みください）に記述されています。ただし、SPAフレームワーク（Angularなど）では通常、scheme|authority|path|fragment|query形式（末尾にクエリ文字列パラメータ付き）のURLが期待されます。これにより、アプリケーションは正常な状態に入りません。たとえば、上記のURLでは、アプリは/#/registerではなく/にルーティングされます。

SPAフレームワークのこの制限を回避するには、リダイレクトのためのSPAアプリルートを保持するrouteパラメーターを含んだサーバー側のCallback URLを、 リダイレクト先 URLとして使用することが推奨されます。このサーバー側のURLに入ったら、残りのクエリ文字列とともにrouteパラメーターに保存されているSPAルートにリダイレクトします。

1. サーバー側のURLを、リダイレクトのSPAルートを記録するrouteパラメーター付きの リダイレクト先 URLとして追加します。 http://localhost:3001/register?route=register

2. URLからrouteやその他のパラメーターを読み取り、routeパラメーターで指定されたSPAルートにリダイレクトするサーバ側のルートコントローラーを作成します。Auth0から受け取った他のパラメーターを忘れずに追加します。

   var express = require('express');
   var router = express.Router();
   var qs = require('qs'); // to read query string params and stringify them
   
   router.get('/register', function(req, res, next) {
     var route = req.query.route; // retrieve the route param that contains the SPA client side route user needs to be redirected to.
   
     delete req.query.route; // remove it from query params.
     res.redirect('http://localhost:3000/#/' + route + '?' +  qs.stringify(req.query)); // Send a 302 redirect for the expected route
   });
   
   module.exports = router;
   

5 メッセージ本文

メッセージ本文にはHTMLコンテンツがありますが、現在サポートされているテンプレート構文はLiquid構文です。すべての共通変数と個々のテンプレートで定義された変数が使用できます。

多言語メールテンプレート

Liquid構文をユーザーオブジェクトのuser_metadata.langプロパティと併用すると、ユーザーが希望する言語に基づいてコンテンツを変更できます。たとえば、イタリア語の場合は、アクションを使用してuser_metadata.langプロパティをitに設定することができます。その言語プロパティにアクションなどを設定する必要があります。

Liquidテンプレート変数のデバッグ

テンプレートの開発を支援するために、カスタム{% debug %} liquidタグが追加されました。このタグは、テンプレートが表示されたときにテンプレートで使用できるテンプレート変数の概要を出力します。このタグは、「ライブ」のテンプレートから必ず削除してください。

​

もっと詳しく

• メールテンプレートの説明
• アカウントのブロック通知メールをカスタマイズする
• メールのハンドリングをカスタマイズする
• MFA用メール通知を構成する
• 電子メールテンプレートでLiquid構文を使用