OIDCベースのSSOの設定

このページでは、OpenID Connect（OIDC）プロトコルに基づくシングルサインオン（SSO）の設定および利用方法について説明します。

前提条件

シングルサインオン（SSO）の基本概念に慣れていることを推奨します。

対応するOIDCプロバイダー

EMQXダッシュボードは、OIDCプロトコルをサポートするアイデンティティサービスと連携してOIDCベースのSSOを実現できます。主な対応プロバイダーは以下の通りです。

• Microsoft Entra ID
• Okta

Microsoft Entra IDとの連携によるSSOの設定

このセクションでは、Microsoft Entra IDをアイデンティティプロバイダー（IdP）として使用し、SSOを設定する手順を説明します。Microsoft側とEMQXダッシュボード側の両方で設定を完了する必要があります。

ステップ1：EMQXダッシュボードでOIDCを有効化

1. EMQXダッシュボードで、System -> SSO に移動します。
2. OIDCカードのEnableボタンをクリックします。

ステップ2：Microsoft Entra IDにアプリケーションを登録

1. 管理者としてMS Azureポータルにログインします。

2. Microsoft Entra ID -> Enterprise Applications -> New Applicationに進み、Create your own applicationをクリックします。

   

3. アプリケーション名（例：EMQX Dashboard）を入力し、**Microsoft Entra IDと連携するアプリケーションを登録（開発中のアプリ）**を選択して、Createをクリックします。

   

4. Register an applicationページで、サポートするアカウントタイプを選択し、EMQXダッシュボードのステップ1で提供された情報を使ってRedirect URLを設定します。

   • Redirect URL：Webを選択し、ダッシュボードで提供されたSign-in Redirect URI（例：http://localhost:18083/api/v5/sso/oidc/callback）を入力します。

5. Certificates and Secrets -> Client secretsタブに移動し、New client secretをクリックします。説明を入力し、有効期限を選択してAddをクリックします。生成されたシークレット値をコピーしてください。ステップ3で必要になります。

ステップ3：EMQXダッシュボードの設定を完了

1. 設定ページで以下の情報を入力します。

   • Provider：Genericのままにします。

   • Issuer URL：これはOpenID Connectメタデータドキュメントに対応し、ステップ2のアプリケーション概要ページのEndpointsタブで確認できます。ただし、/.well-known/openid-configurationの部分はEMQXが自動で追加するため含めません。例：https://login.microsoftonline.com/<tenant_id>/v2.0（<tenant_id>はディレクトリ（テナント）ID）。

   • Client ID：ステップ2のアプリケーション概要ページにあるApplication (client) ID。

     

   • Client Secret：ステップ2で生成したシークレット値。

   • Dashboard Address：ユーザーがダッシュボードにアクセスするためのベースURLを入力します（例：http://localhost:18083）。このアドレスはIdP側の設定で使用するSSO AddressおよびMetadata Addressの生成に自動で組み合わされます。

     

2. Updateをクリックして設定を完了します。

Oktaとの連携によるSSOの設定

このセクションでは、Oktaをアイデンティティプロバイダー（IdP）として使用し、SSOを設定する手順を説明します。Okta側とEMQXダッシュボード側の両方で設定を完了する必要があります。

ステップ1：EMQXダッシュボードでOIDCを有効化

1. EMQXダッシュボードで、System -> SSO に移動します。
2. OIDCカードのEnableボタンをクリックします。

ステップ2：OktaのアプリケーションカタログにOIDCアプリケーションを追加

1. 管理者としてOktaにログインし、Okta Admin Consoleにアクセスします。

2. Applications -> Applicationsページに移動し、Create App integrationボタンをクリックします。ポップアップでサインイン方法としてOIDC - OpenID Connectを選択します。

3. Application typeとしてWeb Applicationを選択し、Nextをクリックします。

4. General Settingsタブでアプリケーション名（例：EMQX Dashboard）を入力し、Nextをクリックします。

5. LOGINタブで、EMQXダッシュボードから提供された情報を使って設定します。

   • Sign-in redirect URIs：ダッシュボードのOIDC Settingsページで提供されるSign-in Redirect URI（例：http://localhost:18083/api/v5/sso/oidc/callback）を入力します。
   • その他の設定は任意で、要件に応じて構成可能です。

6. 設定内容を確認し、Saveをクリックします。

詳細な手順はOktaのドキュメントをご参照ください。

ステップ3：EMQXダッシュボードの設定を完了

1. OIDC Settingsページで以下の情報を入力します。

   • Force MFA：オプションで有効化すると、このバックエンドの全ユーザーにログイン時のTOTP認証を必須にします。デフォルトは無効です。詳細はSSOユーザーの強制MFAを参照してください。
   • Provider：Oktaを選択、または他のプロバイダーの場合はGenericを選択します。
   • Issuer URL：Okta認可サーバーのURL（例：https://example-org.okta.com）。
   • Client ID：ステップ2で作成したアプリケーションからコピーします。
   • Client Secret：ステップ2で作成したアプリケーションからコピーします。
   • Dashboard Address：ユーザーがダッシュボードにアクセスするためのベースURL（例：http://localhost:18083）。IdP側の設定で使用するSSO AddressおよびMetadata Addressの生成に自動で組み合わされます。

2. Updateをクリックして設定を完了します。

詳細設定

Advanced Settingsセクションでは、EMQXがOIDCプロバイダーからユーザー情報を取得する方法や認証の挙動を細かく調整できます。

フィールド名	説明	デフォルト値
Scopes	認証時に要求するOIDCスコープ。これらのスコープによりIdPが返すユーザー情報が決まります。OIDC認証には最低限openidスコープが必要です。	openid
Name Variable	OIDCユーザー属性をEMQXダッシュボードのユーザー名にマッピングするためのテンプレート。IdPから返されるクレームを参照可能です。	${sub}
Name Variable Source	ダッシュボードのユーザー名を構築するためにユーザー情報を抽出するソースを指定します。利用可能なオプション： User Info Endpoint：/userinfoエンドポイントから返されるユーザー情報を使用。 ID Token：認証時に返されるIDトークン内のクレームを使用。	User Info Endpoint
Role Source	ダッシュボードユーザーのロールを構築するためにユーザー情報を抽出するソースを指定します。利用可能なオプション： User Info Endpoint：/userinfoエンドポイントから返されるユーザー情報を使用。 ID Token：認証時に返されるIDトークン内のクレームを使用。	User Info Endpoint
Role Expression	jq式で、OIDCユーザー属性をEMQXダッシュボードのユーザーロールにマッピングします。IdPから返されるクレームを参照可能です。式は有効なロールを表す文字列を1つだけ返す必要があります。サポートされるロールは以下の通りです。 "viewer" "administrator" それ以外の結果の場合、ユーザーは作成されません。このフィールドが未設定の場合、EMQXは既存ユーザーのロールを保持するか、新規ユーザーをviewerロールで作成します。	未設定
Namespace Source	ダッシュボードユーザーのマルチテナンシーネームスペースを構築するためにユーザー情報を抽出するソースを指定します。利用可能なオプション： User Info Endpoint：/userinfoエンドポイントから返されるユーザー情報を使用。 ID Token：認証時に返されるIDトークン内のクレームを使用。	User Info Endpoint
Namespace Expression	jq式で、OIDCユーザー属性をEMQXダッシュボードのユーザーネームスペースにマッピングします。式は既存のネームスペース名を表す文字列か、グローバルネームスペースを示すnullのいずれかを1つだけ返す必要があります。その他の結果の場合、ユーザーは作成されません。このフィールドが未設定の場合、EMQXは既存ユーザーのネームスペースを保持するか、新規ユーザーをグローバルネームスペースに配置します。	未設定
Session Expiry	OIDCログイン後、ダッシュボードのセッションが有効な期間（秒単位）です。	30秒
Enable PKCE	認可コードフローのセキュリティを強化するためのProof Key for Code Exchange（PKCE）を有効にします。	無効
Preferred Authentication Methods	トークンエンドポイントとの通信時に使用するクライアント認証方法を定義します。複数の方法を設定でき、順に試行されます。	client_secret_post, client_secret_basic, none
Fallback Methods	プロバイダーメタデータに明示的な署名アルゴリズムがない場合にIDトークンの検証に使用するフォールバック署名アルゴリズムを指定します。	RS256
JSON Web Key (JWK)	IdPがJWKSエンドポイントを提供しない場合にトークン署名の検証に使用するオプションの静的JSON Web Key設定です。	None

ログインとユーザー管理

OIDC SSOを有効にすると、EMQXダッシュボードのログインページにSSOオプションが表示されます。OIDCボタンをクリックすると、OIDCプロバイダーのログインページに遷移し、ユーザーに割り当てられた認証情報でログインできます。

認証に成功すると、EMQXは自動的にダッシュボードユーザーを追加します。ユーザーはUsersで管理でき、ロールや権限の割り当てが可能です。OIDCユーザーにログイン時のTOTP二要素認証を必須にする場合は、SSOユーザーの強制MFAを参照してください。

ログアウト

ユーザーはダッシュボードの上部ナビゲーションバーにあるユーザー名をクリックし、ドロップダウンメニューのLogoutボタンをクリックしてログアウトできます。なお、この操作はダッシュボードからのログアウトのみであることにご注意ください。