OIDCベースのSSOの設定

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

前提条件

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

対応するOIDCプロバイダー

EMQXダッシュボードは、OIDCプロトコルをサポートするIDサービスと連携して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）を入力し、Register an application to integrate with Microsoft Entra ID (App you're developing) を選択して、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 metadata documentに対応し、ステップ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
Role Expression	jq式でOIDCユーザー属性をEMQXダッシュボードのユーザー役割にマッピングします。IdPが返すクレームを参照可能です。式は有効な役割を表す文字列を1つだけ返す必要があります。サポートされる役割は： "viewer" "administrator" 結果がこれ以外の場合、ユーザーは作成されません。このフィールドが未設定の場合、EMQXはユーザーをviewer役割で作成するか、既存ユーザーなら役割を維持します。	未設定
Namespace Source	ダッシュボードのユーザーのマルチテナンシーネームスペースを構築するためにユーザー情報を抽出するソースを指定します。選択肢は上記と同様です。	User Info Endpoint
Namespace Expression	jq式でOIDCユーザー属性をEMQXダッシュボードのユーザーネームスペースにマッピングします。IdPが返すクレームを参照可能で、既存のネームスペース名の文字列かグローバルネームスペースを示すnullを1つだけ返す必要があります。その他の結果はユーザー作成を妨げます。このフィールドが未設定の場合、EMQXはユーザーをグローバルネームスペースに配置するか、既存ユーザーならネームスペースを維持します。	未設定
Session Expiry	OIDC経由でログインした後、ダッシュボードセッションが有効な期間（秒単位）です。	30秒
Enable PKCE	認可コードフローのセキュリティを強化するためにPKCE（Proof Key for Code Exchange）を有効にします。	無効
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ボタンをクリックしてログアウトできます。これはダッシュボードからのログアウトのみであることにご注意ください。