SAMLベースのSSOの設定
このページでは、Security Assertion Markup Language（SAML）2.0標準プロトコルに基づくシングルサインオン（SSO）の設定および使用方法について説明します。
前提条件
シングルサインオン（SSO）の基本概念に慣れていることを推奨します。
対応しているSAMLサービス
EMQXダッシュボードは、SAML 2.0プロトコルをサポートするアイデンティティサービスと連携し、SAMLベースのSSOを実現できます。対応例は以下の通りです。
その他のアイデンティティプロバイダーも統合準備中で、今後のバージョンでサポート予定です。
Microsoft Entra IDとの連携によるSSO設定
このセクションでは、Microsoft Entra IDをアイデンティティプロバイダー（IdP）として使用し、SSOを設定する方法を案内します。Microsoft側とEMQXダッシュボード側の両方で設定を完了する必要があります。
ステップ1：EMQXダッシュボードでSAML SSOを有効化
ダッシュボードの System -> SSO に移動します。
SAML 2.0カードの Enable ボタンをクリックします。
設定ページで以下の情報を入力します：
- Dashboard Address：ユーザーがダッシュボードの実際のアクセスアドレスにアクセスできるようにします。特定のパスは指定しません。例：
http://localhost:18083。このアドレスは自動的に連結され、IdP側設定用の SSO Address と Metadata Address が生成されます。 - SAML Metadata URL：一時的に空欄のままにし、ステップ2の設定を待ちます。
- Signed Assertions from IdP：IdPによるSAMLアサーションの署名を要求します。
- Signed Response Envelopes from IdP：IdPによるSAMLレスポンスエンベロープの署名を要求します。
EMQX 6.3.0以降、両オプションはデフォルトで有効です。これらは独立して設定可能で、IdPの署名動作に合わせて有効化してください。両方を無効にするとSAML署名検証がすべてオフになりますが、これは安全ではなくテスト用途のみにしてください。
- Dashboard Address：ユーザーがダッシュボードの実際のアクセスアドレスにアクセスできるようにします。特定のパスは指定しません。例：
ステップ2：Microsoft Entra IDにアプリケーションを登録
管理者としてMS Azureポータルにログインします。
Microsoft Entra ID -> Enterprise Applications -> New Applicationに移動し、Create your own applicationをクリックします。
アプリケーション名を入力します（例：
EMQX Dashboard）。**Integrate any other application you don't find in the gallery (Non-gallery)**を選択し、Createをクリックします。
Assign users and groupsをクリックし、EMQXダッシュボードアプリケーションにアクセス可能なユーザーとグループを割り当てます。
Single sign-onタブに移動し、SAMLを選択、Basic SAML ConfigurationセクションのEditボタンをクリックします。
ステップ1のダッシュボードで提供された以下の情報を設定します：
- Identifier (Entity ID)：ダッシュボードで提供されたMetadata Addressを入力します。例：
http://localhost:18083/api/v5/sso/saml/metadata - Reply URL (Assertion Consumer Service URL)：ダッシュボードで提供されたSSO Addressを入力します。例：
http://localhost:18083/api/v5/sso/saml/acs
その他の情報は任意で、実際の要件に応じて設定してください。
- Identifier (Entity ID)：ダッシュボードで提供されたMetadata Addressを入力します。例：
Saveをクリックして設定を保存します。
ステップ3：EMQXダッシュボードの設定を完了
Microsoft Entra IDの作成したアプリケーションのSingle sign-onタブに移動し、Token Signing CertificateセクションのApp Federation Metadata Urlをコピーします。
ダッシュボードのステップ1にあるSAML Metadata URLにコピーしたURLを貼り付けます。
いずれかの署名検証オプションが有効な場合、ブラウザでメタデータURLを開きます。返されたXML内の
IDPSSODescriptorにuse="signing"のKeyDescriptorと空でないX509Certificateが含まれていることを確認してください。含まれていない場合は、IdP側で署名証明書を設定してから進めてください。そうしないとSAMLバックエンドが起動できません。Updateをクリックして設定を完了します。
Oktaとの連携によるSSO設定
このセクションでは、Oktaをアイデンティティプロバイダー（IdP）として使用し、SSOを設定する方法を案内します。Okta側とEMQXダッシュボード側の両方で設定を完了する必要があります。
ステップ1：EMQXダッシュボードでOktaを有効化
ダッシュボードの System -> SSO に移動します。
SAML 2.0カードの Enable ボタンをクリックします。
設定ページで以下の情報を入力します：
- Force MFA：このバックエンドのすべてのユーザーにログイン時のTOTP認証を要求する場合に有効化します。デフォルトは無効です。詳細はForced MFA for SSO Usersを参照してください。
- Dashboard Address：ユーザーがダッシュボードの実際のアクセスアドレスにアクセスできるようにします。特定のパスは指定しません。例：
http://localhost:18083。このアドレスは自動的に連結され、IdP側設定用の SSO Address と Metadata Address が生成されます。 - SAML Metadata URL：一時的に空欄のままにし、ステップ2の設定を待ちます。
- Signed Assertions from IDP：IdPによるSAMLアサーションの署名を要求します。
- Signed Response Envelopes from IdP：IdPによるSAMLレスポンスエンベロープの署名を要求します。
EMQX 6.3.0以降、両オプションはデフォルトで有効です。これらは独立して設定可能で、IdPの署名動作に合わせて有効化してください。両方を無効にするとSAML署名検証がすべてオフになりますが、これは安全ではなくテスト用途のみにしてください。
ステップ2：OktaのアプリケーションカタログにSAML 2.0アプリを追加
管理者としてOktaにログインし、Okta Admin Consoleにアクセスします。
Applications -> Applicationsページに移動し、Create App integrationボタンをクリックします。ポップアップでサインイン方法として
SAML 2.0を選択し、Nextをクリックします。General Settingsタブでアプリケーション名を入力します（例：
EMQX Dashboard）。Nextをクリックします。Configure SAMLタブでステップ1のダッシュボードで提供された情報を設定します：
- Single sign-on URL：ダッシュボードで提供されたSSO Addressを入力します。例：
http://localhost:18083/api/v5/sso/saml/acs - Audience URI (SP Entity ID)：ダッシュボードで提供されたMetadata Addressを入力します。例：
http://localhost:18083/api/v5/sso/saml/metadata
その他の情報は任意で、実際の要件に応じて設定してください。
- Single sign-on URL：ダッシュボードで提供されたSSO Addressを入力します。例：
設定内容を確認し、Nextをクリックします。
FeedbackタブでI'm an Okta customer adding an internal appを選択し、必要に応じて他の情報を入力して、Finishをクリックしアプリケーション作成を完了します。
ステップ3：Oktaで設定完了およびユーザー・グループの割り当て
- OktaのSign Onタブに移動し、Metadata URLをコピーします。
- ダッシュボードのステップ1にあるSAML Metadata URLにコピーしたURLを貼り付けます。
- いずれかの署名検証オプションが有効な場合、ブラウザでメタデータURLを開きます。返されたXML内の
IDPSSODescriptorにuse="signing"のKeyDescriptorと空でないX509Certificateが含まれていることを確認してください。含まれていない場合は、IdP側で署名証明書を設定してから進めてください。そうしないとSAMLバックエンドが起動できません。 - Updateをクリックして設定を完了します。
- Okta > Assignmentsタブで、EMQXダッシュボードアプリケーションに割り当てるユーザーとグループを設定できます。ここで割り当てられたユーザーのみがこのアプリケーションにログイン可能です。
ログインとユーザー管理
SAMLシングルサインオンを有効にすると、EMQXダッシュボードのログインページにSSOオプションが表示されます。SAMLボタンをクリックすると、IdPの事前設定されたログインページに遷移し、割り当てられたユーザー資格情報でログインできます。
SAML認証に成功すると、EMQXは自動的にダッシュボードユーザーを追加します。追加されたユーザーはUsersで管理でき、ロールや権限の割り当てが可能です。SAMLユーザーにログイン時のTOTP二要素認証を必須にする場合は、Forced MFA for SSO Usersを参照してください。
ログアウト
ユーザーはダッシュボードの上部ナビゲーションバーにあるユーザー名をクリックし、ドロップダウンメニューのLogoutボタンをクリックしてログアウトできます。これはダッシュボードからのログアウトのみであり、SAMLは現在シングルサインアウトをサポートしていないことにご注意ください。