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の生成に自動的に組み合わされます。

     

   • Enable TLS：Issuer URLがhttpsスキームの場合はこのトグルをオンにし、httpの場合はオフにします。EMQX 6.3.0以降では、Issuer URLのスキームとTLS設定が一致しないOIDC設定は作成・更新時に拒否されます。

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の生成に自動的に組み合わされます。
   • Enable TLS：Issuer URLがhttpsスキームの場合はこのトグルをオンにし、httpの場合はオフにします。EMQX 6.3.0以降では、Issuer URLのスキームとTLS設定が一致しないOIDC設定は作成・更新時に拒否されます。
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が返すクレームを参照可能で、正確に1つの値を返す必要があります。値は既存のネームスペース名の文字列か、グローバルネームスペースを示すnullでなければなりません。それ以外の結果はユーザー作成を阻止します。このフィールドが未設定の場合、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ボタンをクリックしてログアウトできます。なお、これはダッシュボードからのログアウトのみであることにご注意ください。