ドメイン上でカスタムマトリックスルームエイリアスを設定する方法

Matrix ルームエイリアスは、ルームに のような人間が読みやすいアドレスを割り当てます#support:example.org。コロンの後の部分は、ホームサーバーのサーバー名、つまりエイリアス名前空間を所有するドメインです。これは、DNS レコードを追加することで変更できる任意のドメインラベルではありません。独自のドメインを使用するには、ホームサーバーをそのドメインをサーバー名として構成する必要があります。その後、フェデレーションを別のホストに委任できます。

このガイドではexample.org、ドメインとして、matrix.example.orgSynapse ホストとして、#support:example.orgターゲットエイリアスとして を使用します。これらのプレースホルダーを、ご自身の値に置き換えてください。このガイドは、セルフホスト型の Synapse に焦点を当てています。ホスト型の Matrix プロバイダを使用する場合は、カスタムサーバー名の使用が許可されているかどうかを確認してください。多くのホスト型アカウントでは、プロバイダのドメインでのみエイリアスを作成できます。

マトリックスルームエイリアスが何をするか

ホームサーバーは、ユーザーのルームデータを保存し、他のサーバーに接続するMatrixサーバーです。ルームID（例：）は!opaqueid:example.org、技術的にルームを識別します。ルームエイリアス（例：）は、#support:example.orgルームIDと、ユーザーが参加する際に役立つサーバーのリストに解決される、読み取り可能なディレクトリエントリです。

エイリアスは、ルーム名を変更したり、プライバシー設定を変更したり、公開ルームディレクトリに表示されることを保証したりするものではありません。これらは個別のルーム設定です。ルームには複数のエイリアスを設定できます。正規エイリアスは、クライアントが表示または共有する優先アドレスです。これはルームの状態として公開され、ホームサーバーはエイリアスとルームのマッピングを維持します。Matrix仕様では、エイリアスマッピングは変更される可能性があるため、エイリアスを使用する前にアドレスを解決しておくよう注意喚起しています。

始める前に

• 使用したいドメイン（例：）を制御し、example.orgそのドメインでHTTPSコンテンツを提供する機能を含めることができます。
• Synapseなどのホームサーバーを、マトリックスserver_nameを に設定して実行しますexample.org。この値はサーバーの設定時に選択され、後で安易に変更すべきではありません。ユーザーIDとエイリアスは、この値を名前空間として使用します。
• 有効なTLS証明書とフェデレーションルートが必要です。委任されたMatrixホスト（例：）はmatrix.example.org、有効な証明書を提示する必要があります。
• ルームに参加し、アドレス変更に必要なルーム権限を持っている必要があります。Synapseには、エイリアスの作成を許可または拒否できるサーバー側のルールもあります。

サーバーが既に別のサーバー名で実行されている場合（例：）provider.net、 の作成は#support:example.orgドメインマッピングのショートカットにはなりません。プロバイダーにカスタムドメインのサポートについて問い合わせるか、ホームサーバーの別の展開と移行を計画してください。Matrix では、あるホームサーバーが別のサーバーの名前空間にエイリアスを作成するプロセスは定義されていません。

ステップ1：サーバー名とフェデレーションルートを選択します

ホームサーバーを設定する前に、コロンの後に表示する名前を決定してください。この例では、Synapse はexample.orgサーバー名として を使用し、クライアントおよびフェデレーションサービスは で実行されますmatrix.example.org。DNS レコードは へのトラフィックをmatrix.example.orgホストまたはリバースプロキシに送信します。DNS レコード自体はエイリアス名前空間を確立しません。Synapse のサーバー名がそれを確立します。

ホームサーバーがデフォルトのフェデレーションポート8448で直接アクセスできない場合example.org、Matrixはフェデレーションエンドポイントを検出する方法が必要です。一般的な方法の1つは、.well-known委任です。サーバー名ドメインの小さなHTTPS JSONレスポンスが、フェデレーショントラフィックを実際のMatrixホストに誘導します。これを次の場所で提供してくださいhttps://example.org/.well-known/matrix/server。

{
  "m.server": "matrix.example.org:443"
}

レスポンスが有効な JSON 形式であり、HTTPS 経由で配信され、ターゲット ホストが有効な証明書を持ち、フェデレーション リクエストを Synapse にルーティングしていることを確認してください。フェデレーション エンドポイントが 8448 を使用する場合は、ポートを省略できます。この例では、ポート 443 が明示的に指定されています。Synapse が既に server-name ドメインのポート 8448 でフェデレーションを提供している場合は、委任は不要かもしれません。クライアント側の/.well-known/matrix/clientファイルは別の検出メカニズムであり、サーバー委任の代替にはなりません。

Synapseの現在の設定ドキュメントには、serve_server_wellknownポート443のserver-nameドメインへのリクエストがSynapseにルーティングされる場合のオプションが含まれています。このオプションは、プロキシとドメインルーティングがドキュメントに記載されている要件を満たしている場合にのみ使用してください。そうでない場合は、WebサーバーまたはプロキシでJSONレスポンスを設定してください。

ステップ2：Synapseのエイリアスポリシーを確認する

Synapse では、エイリアスを作成できるユーザーと許可されるルーム アドレスを制限できます。 ではhomeserver.yaml、alias_creation_rulesエイリアス作成要求が拒否されたかどうかを確認します。Synapse は設定されたルールを順番に評価します。最初に一致したルールが要求を決定し、一致するルールがない場合は要求が拒否されます。空のリストは、すべてのエイリアス作成要求を拒否します。null または省略されたリストは、他のチェックに従って、デフォルトでエイリアスの作成を許可します。

またrequire_membership_for_aliases、デフォルトではユーザーがルーム内にいることが必須となる設定も確認してください。Synapseの設定を変更する場合は、デプロイメントの通常の検証および再起動プロセスに従い、必要以上にポリシーを緩めないようにしてください。ルームの電力レベルとクライアントで使用可能なコントロールも、一般メンバーが優先エイリアスを設定できるかどうかに影響する場合があります。

ステップ3：ルームのエイリアスを作成する

Matrixクライアントで目的のルームに参加し、ルーム設定を開きます。アドレスまたはエイリアスセクションを探します。クライアントの表記やレイアウトはバージョンによって異なる場合があります。先頭のドメイン名#とホームサーバーのドメインを含む完全なアドレスを入力します（例：）#support:example.org。これをルームアドレスとして追加し、クライアントにオプションがある場合は、正規エイリアスまたは優先エイリアスとして設定します。変更を保存します。

クライアントがエイリアス制御を提供しない場合、クライアント/サーバーAPIリクエストでマッピングを作成できます。認証済みPUT /_matrix/client/v3/directory/room/{roomAlias}エンドポイントでは、リクエスト本文にルームIDが必要です。たとえば、承認されたルームメンバーまたはサーバーアカウントは、次のルームを所有するホームサーバーにリクエストを送信できますexample.org。

curl -X PUT \
  "https://matrix.example.org/_matrix/client/v3/directory/room/%23support%3Aexample.org" \
  -H "Authorization: Bearer $MATRIX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"room_id":"!yourRoomId:example.org"}'

サンプルルームIDを実際のルームIDに置き換え、必要な認証情報を含む有効なアクセストークンを使用してください。トークンはパスワードと同様に扱い、公開したり、サポート投稿に貼り付けたり、ソース管理にコミットしたりしないでください。URLエンコード#と:HTTPパスにはパーセント記号によるエスケープ処理が必要です。応答が成功した場合は、マッピングが作成されたことを示します。「既に存在します」という応答は、その名前が既に使用されていることを意味します。変更や削除を行う前に、所有者を確認してください。

ステップ4：住所を確認して共有する

公開されているクライアント/サーバーAPIを使用してエイリアスを解決します。このルックアップには認証は不要です。

curl -i \
  "https://matrix.example.org/_matrix/client/v3/directory/room/%23support%3Aexample.org"

正常な応答には、期待される情報room_idとserversリストが含まれているはずです。返されたルーム ID を目的のルームと比較してください。404 は、その名前空間を処理するサーバーにエイリアスのマッピングがないことを意味します。400 は、無効な形式のアドレスを示しています。次に、2 番目の Matrix アカウントまたはクライアントで完全なエイリアスをテストして、ルームが解決され、参加ルールに従って参加できることを確認してください。

正規エイリアスを設定する場合は、ルームの詳細を再度確認し、優先アドレスが公開予定のアドレスであることを確認してください。エイリアスまたはMatrixパーマリンクは、正しいルームに解決されることを確認してから共有してください。公開エイリアスを設定しても、プライベートルームが公開されるわけではないことに注意してください。ユーザーは参加するために許可を得る必要があります。

避けるべき一般的な問題

• ホームサーバーが所有していないドメインを使用する場合：エイリアス内のサーバー名は、それを作成するホームサーバーの名前空間と一致している必要があります。DNS CNAMEだけでは、他のサーバーのドメインを認証することはできません。
• ドメインとホストを混同しないでください。 は example.orgエイリアス名前空間である一方、matrix.example.orgはサービスホストである可能性があります。Synapseサーバー名と委任を意図的に設定してください。
• クライアント検出ファイルを間違った場所に配置しています:フェデレーション委任では を使用します/.well-known/matrix/server。クライアント検出ファイルはパスと目的が異なります。
• エイリアスがルームを公開する場合：エイリアスの解決とルームディレクトリの公開は、それぞれ別のポリシーによって管理される別々の操作です。
• 既存のデプロイメントでサーバー名を変更する場合：既存のMatrix IDはその名前空間に依存しています。ドメインの変更は、簡単なエイリアス設定ではなく、アーキテクチャの移行として扱ってください。
• マッピングを確認せずに共有する場合：公開する前に、エイリアスを解決し、返されたルームIDを比較してください。読みやすいアドレスは便利ですが、それがどこに繋がるかはサーバーのマッピングによって決まります。

プロトコルの詳細については、Matrix識別子とエイリアス形式、およびMatrix room-alias APIを参照してください。Synapseの設定については、Elementのフェデレーション委任ガイドと構成マニュアルを参照してください。Synapseのオプションとクライアント画面はリリースごとに変更される場合がありますので、使用しているバージョンのドキュメントを確認してください。