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認証を要求します。デフォルトは無効です。詳細はSSOユーザーの強制MFAを参照してください。
- 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は自動的にダッシュボードユーザーを追加します。追加されたユーザーはユーザー管理で管理でき、役割や権限の割り当ても可能です。SAMLユーザーにログイン時のTOTP二要素認証を必須にする場合は、SSOユーザーの強制MFAを参照してください。
ログアウト
ユーザーはダッシュボードの上部ナビゲーションバーにあるユーザー名をクリックし、ドロップダウンメニューの Logout ボタンをクリックしてログアウトできます。これはダッシュボードからのログアウトのみであり、SAMLは現時点でシングルサインアウトをサポートしていないことにご注意ください。