SAML 認証によるログインの設定

2025年01月21日 Matomoの管理はじめるシングルサインオン(SSO)

Matomo SAML 認証モジュールは、ユーザが SAML アイデンティティプロバイダ (IdP) を使って Matomo にログインできるようにします。

SAML アイデンティティプロバイダ（OneLogin、Okta、Ping Identity、ADFS、Google、Salesforce、SharePoint…）と連携した環境を持っている場合、このプラグインを使用してそれと相互運用し、Matomo Analytics ユーザの SSO を有効にすることができます。

SAML は、クラウドホスティングのエンタープライズプランに含まれるプレミアム機能です。また、Matomo オンプレミスをセルフホストしている場合は、Matomoマーケットプレイスで購入することもできます。ログイン SAML の利点と機能の詳細については、こちらをご覧ください。

インストール

必要条件

PHP >= 5.5.9
Matomo >= 3.x
Marketplace SAML Pluginページからプラグインを購入する。
注：Matomo インスタンスに SAML を設定し、SAML を介してユーザを追加する場合、ユーザを代表してMatomo のプライバシーポリシーおよび利用規約に同意する必要があります。個々のユーザがこれらの条件に個別に同意するよう求められることはないことに注意してください。SAML を介して追加されたすべてのユーザが、Matomo のプライバシーポリシーおよび利用規約を認識し、遵守するようにすることは、あなたの責任です。

インストール

プラグイン・インストール・ガイドに従ってプラグインをインストールする。

構成

SAML 認証を構成するには、以下の手順に従う：

スーパーユーザーとしてログインする
管理 > プラグインページで、LoginSamlプラグインを有効にします。
システム > SAMLページに移動する。
SAML の設定を入力し、保存する。Identity Provider 情報を追加し、属性マッピングを設定し、必要に応じてその他のオプションを構成する。
サービスプロバイダのメタデータをIdP管理者と共有する
SAML 認証を有効にする
新しいブラウザセッションを開き、SAML ID プロバイダでログインを試みることができる。

SAML 構成のサポート

SAML 認証を適切に設定することは難しい場合があります。そのため、Matomo Analytics を SAML で正常に動作させ、SSO の大きなメリットを享受するためのサービスを提供しています。詳しくはSAML サポートページ.

SAML プラグインの設定

主な構成手順がわかったところで、SAML 構成の詳細を説明する。

ステータス設定

SAML プラグインを有効にすると、設定パネルにアクセスできるようになる。

「Status Settings」セクションに、「Enable SAML authenticationis disabled」と表示されます。無効にすると、すべての SAML アクションが無効になり、ユーザがそれらを実行しようとすると、SAML 機能が無効であることを通知するエラーが表示されます。

この設定を有効にできるのは、残りの SAML 設定が適切に構成されている場合だけである。

SAML には、2 種類のエンティティがある：
1. ID プロバイダ IdP（ユーザが認証されるサードパーティのエンティティ）、および
2. サービスプロバイダーSP（アプリを保護するサービス、この場合はMatomo）。

IdP と SP の間に信頼の輪が定義され、一部の条件下で、すべての IdP ユーザが SP にアクセスできるようになる。この信頼の輪は、エンティティ ID、エンティティのエンドポイント、および公開証明書（署名/暗号化された SAML メッセージの検証を可能にする）を記述する、メタデータと名付けられた XML の交換に基づいている。

アイデンティティ・プロバイダの設定

Identity Provider Settings」セクションで、Identity Provider メタデータを登録する。

フォームに直接記入してください：

またはIdPメタデータから値をインポートするリンクをクリックします：

このリンクは、Identity Provider メタデータをインポートするための 2 つの方法が提供されるフォームにリダイレクトする：

メタデータのURL
文字列XMLで

インポートされたメタデータに 1 つ以上の ID プロバイダエンティティ記述が含まれている場合はIdPエンティティIDを使用して、目的のエンティティを特定する：

オプション設定

Option settingsセクションで、Matomo SAML インテグレーションがどのように動作するかを定義します。

シナリオによってはジャスト・イン・タイム・プロビジョニングSAMLR レスポンスで ID プロバイダから提供されたデータに基づいて、ユーザ・アカウントを自動的に作成する場合。

ジャストインタイムプロビジョニングが無効になっているか、必要なユーザデータが提供されていない場合、Matomoアカウントを開始できないため、SSOプロセス中にエラーが発生します。
ジャストインタイムプロビジョニングが有効な場合、デフォルトでは（ジャストインタイムプロビジョニングで作成された）新規ユーザは Matomo にアクセスできません。一部の Matomo ウェブサイトに対してデフォルトのview権限を設定することができます。(Matomo の ‘view’ 権限とは何ですか？）新規ユーザの閲覧権限を持つ初期サイト] を使用して、ユーザがデフォルトで閲覧できる Matomo ウェブサイト ID のリストを設定します (カンマ区切りのウェブサイト ID リスト)。
スーパーユーザのジャストインタイムプロビジョニングを使用する場合、プラグインのインストール/アクティベーションやユーザ管理など、スーパーユーザアカウントのすべての機能を使用するには、ローカルのスーパーユーザアカウント（またはローカルの Matomo パスワードがすでに設定されているスーパーユーザ）を使用して作成したユーザのパスワードを設定する必要があります。
これは、Settings>Users へ進み、Edit ボタンをクリック > [Password] フィールドに新しいパスワードを入力 > [Save Basic Info] をクリックすることで行えます。

Matomo ユーザアカウントを識別するには、ユーザーを識別するためのフィールドに値を設定する必要があります。デフォルトではemailフィールドが使用されますが、usernameを選択するとMatomoのusernameフィールドが使用されます。

また、シングルログアウト機能を有効または無効にすることもできます。無効にした場合、シングルログアウトサービスのデータはサービスプロバイダのメタデータに公開されないことに注意してください。

Force SAML Login” 設定を有効にすると、ユーザに SAML 認証を使用させることもできます。これを行うと、すべてのユーザが直接 Identity Provider にリダイレクトされるため、Matomo のログイン画面が表示されることはありません。スーパーユーザは、例えば SAML プラグインを設定するために、通常通りログインする必要があります。スーパーユーザは、Matomo にアクセスする際に URL に?normalを追加することで、Matomo のログイン画面からログインできます。注意: 他のユーザは、この方法ではログインできません。

属性マッピング設定

Field to identify userandjust-in-time provisioningの値によって、Attribute Mapping Settingsセクションのフィールドは必須またはオプションになります。

ジャスト・イン・タイムが有効な場合、すべてのマッピング・フィールドが必須となる。
ジャストインタイム・プロビジョニングが無効の場合、ユーザーを識別するためのFieldの値に関連するフィールドのみが必要となる。

Identity Providers はカスタム属性名を持つユーザデータを Service Provider に送信するので、IdP と Matomo の間で名前を対応付けるには、前のフォームを使用します。

アクセス同期設定

アクセス同期設定セクションで、SAML 属性からのユーザ・アクセスの同期を有効にできます。

LoginSAML は、Identity プロバイダが提供する SAMLR レスポンスにある属性を使用して、アクセス・レベルを同期することをサポートしている。この機能を使用するには、IdP が 3 種類の SAML 属性でアクセスデータを提供していることを確認する：

ユーザーがviewできるサイトを指定する属性（閲覧許可とは？
ユーザーがwriteできるサイトを指定する属性（書き込み許可とは？
ユーザーがadmin権限を持つサイトを指定する属性（superuserであるかどうか(管理者権限とは？）
ユーザがsuperuserかどうかを指定するための属性（Matomoのスーパーユーザとは？）

注釈これらの属性には、好きな名前を付けることができる。これらの名前は、SAML 設定ページで LoginSaml に通知します。

アイデンティティ・プロバイダのアクセス・データの例：

<saml:Attribute Name="view" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xsi:type="xs:string">all</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="admin" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xsi:type="xs:string">1,2,3</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="superuser" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xsi:type="xs:string">1</saml:AttributeValue>
</saml:Attribute>

次に、SAML 設定ページで、「Enable User Access Synchronization from SAML」チェックボックスをオンにし、その下に表示される設定を入力する。
ユーザーアクセスの同期は、ユーザーがログインする前に行われる。

複数のMatomoインスタンスのアクセス管理

LoginSaml は、単一の IdP SAML サーバを使用して、複数の Matomo インスタンスのアクセスを管理することをサポートしています。この機能を使用するには、SAML アクセス属性に特別な値を指定する必要があります。例えば

view: myMatomoserver.whatever.com:1,2,3;myotherserver.com:all
admin: myMatomoserver.whatever.com:all;mythirdserver.com:3,4
superuser: myotherserver.com;myotherserver.com/otherMatomo

アクセス属性に URL を使用したくない場合は、[Special Name For This Matomo Instance (この Matomo インスタンスの特別な名前)] 設定を使用して、Matomo インスタンスごとに特別な名前を指定できます。例えば、ある Matomo でMatomoServerA、別の Matomo でMatomoServerBと設定した場合、SAML 属性は以下のようになります：

view: MatomoServerA:1,2,3;MatomoServerB:all
admin: MatomoServerA:4,5,6
superuser: MatomoServerC

カスタム・アクセス属性フォーマットの使用

User Access Attribute Server Specification Delimiterと User Access Attribute Server & Site List Separatorを設定することで、アクセス属性で使用されるセパレータをカスタマイズできます。

User Access Attribute Server Specification Delimiterオプションを#に設定すると、アクセス属性を以下のように指定できる：

view: MatomoServerA:1,2,3#MatomoServerB:all

User Access Attribute Server & Site List Separatorオプションを#に設定すると、アクセス属性を以下のように指定することができる：

view: MatomoServerA#1,2,3;MatomoServerB#all

詳細設定

「詳細設定」セクションでは、デバッグ・モードの有効化/無効化を設定し、高度な SAML およびセキュリティ・パラメータを設定することができる。

これらの設定は、php-saml の設定 (SAML プラグインで使用されている PHP ライブラリで、OneLogin inc. が提供している) と一致しているため、詳細については、php-samlのドキュメントを参照してください。

Matomo 用 SAML プラグインはどのように機能するのか？

このプラグインは、SAML シングルサインオン（SSO）とシングルログアウト（SLO）をサービスプロバイダ側だけでなく ID プロバイダ側でも実行する機能を追加する。このセクションでは、SAML 認証フローについて説明する。

SP主導のSSO認証プロセス

ID プロバイダへのリダイレクト（ログイン画面の「SAML ログイン」ボタンがクリックされた場合）：
- ログメッセージ:シングルサインオンの開始、IdPへのリダイレクト(ログレベル情報)
Identity Provider からの応答が Assertion Consumer Service エンドポイントに来たとき：
- ログメッセージ:アサーション・コンシューマー・サービスの開始ログレベル情報)
SAML 検証に成功しました：
- ログメッセージ:SAMLResponse validated (ログレベル情報)
- ログメッセージ:属性 + NameId + NameIDFormat + SessionIndex (ログレベルデバッグ)
または、SAML 検証によって ID プロバイダからの応答でエラーが返された：
- ログメッセージ:SAMLResponse が拒否されました。+ 原因ログレベルエラー)
- ログメッセージ:SAML レスポンス XML (ログレベルデバッグ)
ユーザー作成（アカウントが見つからなかった場合のオプションステップ）：
- ユーザが存在しないが、Just-In-Timeプロビジョニングが有効で、必要な属性が提供されている場合：ログメッセージ:ユーザーを追加ログレベル情報)
- ユーザーがデフォルトのサイトにアクセスできない場合：ログメッセージ:SAML 設定では、’Options’ セクションで新規ユーザーにアクセスを提供するデフォルトのサイトが定義されていない (ログレベル警告)
- ユーザーがデフォルトのサイトにアクセスできる場合：ログメッセージ:サイトへのユーザーUSERアクセスへの追加: SITES (ログレベル情報)
- ユーザーが存在せず、Just-In-Timeプロビジョニングが有効になっているが、処理が失敗した場合：ログメッセージ:ジャストインタイム・プロビジョニング・エラー // Xのマッピングが必要 // Xが提供されていない (ログレベルエラー)
- ユーザーが存在せず、Just-In-Timeプロビジョニングが無効になっている場合：ログメッセージ:ユーザーが存在せず、ジャストインタイム・プロビジョニングが無効になっている (ログレベルエラー)
同期アクセス（同期アクセスが有効になっている場合は、オプションのステップ）：
- ユーザーがデータにアクセスできない場合：ログメッセージ:ユーザーは SAML ではアクセスできませんが、アクセス同期は有効です。(ログレベル警告)
- アクセス・データが、そのユーザーをスーパー・ユーザーとして割り当てることを定義している場合：ログメッセージ:MatomoAccessが同期しました。ユーザーがスーパーユーザー(ログレベル情報)
- アクセスデータがサイト上のユーザーアクセスを定義している場合：*ログメッセージ**：MatomoAccess が同期されました。ユーザのアクセスを更新した。ログレベル情報)
ログインに成功しました：
- ログメッセージ:ログインユーザーMatomoで認証された(ログレベル情報)

IdP主導のSSO認証プロセス

SPが開始するSSOと似ているが、ステップ1はない。

SP主導のシングル・ログアウト認証プロセス（SLO有効）

ID プロバイダにリダイレクトします。(ログアウト要求の送信)。ログアウト」リンクがクリックされ、SAML フローでユーザ・セッションが開始された場合：
- ログメッセージ:ログインUSER (ログレベル情報)
Identity Provider からのログアウト応答が Single Logout Service エンドポイントに来たとき：
- ログメッセージ:ログインUSERのユーザーに対してシングル・ログアウト・サービスを開始した(ログレベル情報 )
SAML 検証：
- SAML ログアウト・レスポンスが有効な場合：ログメッセージ:シングルログアウトサービスが実行されました。ログイン USER を持つユーザがログアウト (ログレベル情報 )
- ID プロバイダからのログアウト応答にエラーがある場合：ログメッセージ:シングルログアウトサービスのエンドポイントでエラーが発生しました。ログインUSERのユーザー。+ エラー理由 (ログレベルエラー)

IdP主導のシングル・ログアウト認証プロセス（SLO有効）

ID プロバイダからのログアウト要求がシングルログアウトサービスのエンドポイントに来た場合：
- ログメッセージ:ログインUSERのユーザーに対してシングル・ログアウト・サービスを開始した(ログレベル情報)
SAML 検証：
- ID プロバイダからのログアウト要求にエラーがある場合：ログメッセージ:シングルログアウトサービスのエンドポイントでエラーが発生しました。ログインUSERのユーザー。+ エラー理由 (ログレベルエラー)
ID プロバイダへのリダイレクト（ログアウト応答の送信）
Identity Provider からのログアウト応答が Single Logout Service エンドポイントに来たとき：
- ログメッセージ:ログインUSERのユーザーに対してシングル・ログアウト・サービスを開始した(ログレベル情報 )
SAML 検証に成功した：
- ログメッセージ:シングルログアウトサービスが実行されました。ログイン USER を持つユーザがログアウト (ログレベル情報 )
または SAML 検証に失敗しました: ID プロバイダからのログアウト応答で返されたエラー：
- ログメッセージ:シングルログアウトサービスのエンドポイントでエラーが発生しました。ログインUSERのユーザー。+ エラー理由 (ログレベルエラー)

SAML フローの仕組みの詳細については、以下を参照されたい：

セキュリティへの配慮

ユーザーパスワード

LoginSAML は、ジャストインタイム・プロビジョニングを使用する場合、ユーザーに対してランダムなハッシュ付きパスワードを生成する。これらのユーザが通常のログインプロセスを使用する場合は、SAML 経由で認証された後、スーパーユーザがそのユーザに有効なパスワードを割り当てる必要があります。

トークン認証の生成や、パスワード認証を促す設定の変更など、特定の機能を使用するためには、Matomoのパスワードを設定する必要があります。

パスワードの確認

プラグインの設定を変更したり、プラグインを有効化/無効化する場合、Matomoは変更を続行するためにパスワードの入力を要求します。

Matomo は、ジャストインタイム・プロビジョニングを使用しているユーザに対してランダムなハッシュ化パスワードを生成するため、SAML を使用してログインしている場合に問題が発生する可能性があります。このようなユーザが設定を変更したり、パスワード確認を必要とするアクションを実行できるようにするために、バージョン 4.3.0 の SAML プラグインではパスワード確認を無効にする方法を提供しています。

パスワード確認を無効にするには、SAML UI オプション設定で設定を更新する。

注：プラグインバージョン4.3.0以降、パスワード確認はデフォルトで無効になっています。

トークン・オーサー

SAMLには認証トークンの概念がないため、ユーザのtoken_authはMatomoデータベースにのみ保存されます。もしtoken_authが漏洩した場合は、Matomo > Administration > Personal Settings でトークンを生成し直すことができます。

ロギング

LoginSAML はデバッグログを多用するので、問題を迅速に診断することができます。ログの中には機密情報を含むものがあります、本番環境ではDEBUGロギングを無効にしてください。また、SAML 設定パネルの詳細設定セクションの「デバッグ」モードをオフにする。

詳しくはLoginSaml for Matomo Analytics – SAML 認証プラグインページを参照されたい。

トラブルシューティング

デバッグ

LoginSAML はデバッグログを広範囲に使用するため、問題を迅速に診断できます。一部のログエントリには機密情報が含まれるため、本番環境では DEBUG ロギングを無効にし、SAML 設定パネルの詳細設定セクションでDebug Modeをオフにしてください。

デフォルトでは、SAML 関連のログは Matomo のtmp/logs/saml.logフォルダに保存されますが、config/config.ini.phpの[LoginSaml]セクションのlogger_file_path設定に新しい値を定義することで変更できます。

ログレベルは「log_level」パラメータで設定でき、設定可能な値は以下のとおり：

ERROR
WARN
INFO
DEBUG

レベルが高いほど、ログのエントリ数は少なくなる。最高レベルはERRORレベル（最低はDEBUG).

[LoginSaml]セクションでlog_levelパラメータが定義されていない場合、デフォルトの Matomolog_level値 (WARN) が使用されます。

ジャストインタイム・プロビジョニングを使用すると、”Username was not provided by IdP and is required in order to execute SAML ジャストインタイム・プロビジョニング “というメッセージが表示される。

問題は、サービスプロバイダ（Matomo）が、IdP から送信された SAMLResponse からユーザ名の値を抽出できないことである。考えられる理由は 2 つある：

Matomo の SAML 設定にある Attribute Mapping セクションが間違っています。そこでは、ユーザ名フィールドを SAMLResponse に付属する属性の正確な名前に設定する必要があるかもしれない。
IdPはユーザー名をまったく送信しないので、Identity Provider管理者に連絡して、そのユーザー情報を提供するようにIdPを設定するよう依頼する必要があるかもしれない。

電子メール・アドレスによってユーザを識別する場合でも、Just-in-time プロビジョニングを使用する場合は、ユーザ名は必須フィールドであることに注意する。SAML Tracer ツール（下記を参照）を使用して、SAML レスポンスの詳細を調べることができる。

シングル・サインオンおよびシングル・ログアウト中にブラウザを介して送信される SAML および WS-Federation メッセージを表示する方法

Firefox の拡張機能には SAMLTracer という名前があり、IdP から送信される SAMLResponse を記録して検査するために使用できます。https://www.youtube.com/watch?v=DLEif7nuNxg のビデオでその使用方法をご覧ください。

技術情報

インストール

必要条件

インストール

構成

SAML 構成のサポート

SAML プラグインの設定

ステータス設定

アイデンティティ・プロバイダの設定

オプション設定

属性マッピング設定

アクセス同期設定

複数のMatomoインスタンスのアクセス管理

カスタム・アクセス属性フォーマットの使用

詳細設定

Matomo 用 SAML プラグインはどのように機能するのか？

SP主導のSSO認証プロセス

IdP主導のSSO認証プロセス

SP主導のシングル・ログアウト認証プロセス（SLO有効）

IdP主導のシングル・ログアウト認証プロセス（SLO有効）

セキュリティへの配慮

トラブルシューティング

デバッグ

ジャストインタイム・プロビジョニングを使用すると、”Username was not provided by IdP and is required in order to execute SAML ジャストインタイム・プロビジョニング “というメッセージが表示される。

シングル・サインオンおよびシングル・ログアウト中にブラウザを介して送信される SAML および WS-Federation メッセージを表示する方法