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タブで確認できます。ただし、EMQXが自動的に/.well-known/openid-configurationを追加するため、この部分は含めず、例として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	OIDCユーザー属性をEMQXダッシュボードのユーザーロールにマッピングするためのjq式。IdPから返されるクレームを参照可能。式は有効なロールを表す文字列を1つだけ返す必要があります。対応ロールは以下： "viewer" "administrator" その他の結果の場合、ユーザーは作成されません。このフィールドが未設定の場合、EMQXはユーザーをviewerロールで作成するか、既存ユーザーの場合はロールを維持します。	未設定
Namespace Source	ダッシュボードユーザーのマルチテナンシーネームスペースを構築するためにユーザー情報を抽出するソースを指定します。選択肢は上記と同様。	User Info Endpoint
Namespace Expression	OIDCユーザー属性をEMQXダッシュボードのユーザーネームスペースにマッピングするためのjq式。IdPから返されるクレームを参照可能。式は既存のネームスペース名の文字列か、グローバルネームスペースを示す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ボタンをクリックしてログアウトできます。なお、これはダッシュボードからのログアウトのみであることにご注意ください。