クライアント認証用に Microsoft Entra ID をセットアップする

  • [アーティクル]

警告

現在、Microsoft Entra クライアント認証とマネージド ID トークン サービスは、Linux 上で相互に互換性がありません。

Azure で実行されているクラスターの場合は、Microsoft Entra ID を使って管理エンドポイントへのアクセスをセキュリティで保護することをお勧めします。 この記事では、Service Fabric クラスターのクライアントを認証するための Microsoft Entra ID の設定方法について説明します。

Linux 上では、クラスターを作成する前に次の手順を完了する必要があります。 Windows では、既存のクラスターの Microsoft Entra 認証を構成することもできます。

この記事の "アプリケーション" という用語は、Service Fabric アプリケーションではなく、Microsoft Entra アプリケーションを指し、必要に応じて区別されます。 組織 ("テナント" と呼ばれます) では、Microsoft Entra ID を使ってアプリケーションへのユーザー アクセスを管理できます。

Service Fabric クラスターでは、Web ベースの Service Fabric Explorer や Visual Studio など、いくつかのエントリ ポイントから管理機能にアクセスできます。 そのため、クラスターへのアクセスを制御するには、2 つの Microsoft Entra アプリケーション (Web アプリケーションとネイティブ アプリケーション) を作成することになります。 アプリケーションを作成したら、ユーザーを読み取り専用ロールおよび管理者ロールに割り当てます。

Note

現時点では、Service Fabric ではストレージに対する Microsoft Entra 認証をサポートしていません。

Note

Linux Microsoft Entra ID 対応クラスター上のアプリケーションとノードを Azure portal で表示できないという既知の問題があります。

Note

現在、Microsoft Entra ID では、アプリケーション (アプリ登録) の発行元ドメインを検証するか、既定のスキームを使う必要があります。 詳細については、「アプリの発行元ドメインを構成する」と「シングル テナント アプリケーションの AppId URI には、既定のスキームまたは検証済みドメインを使用する必要があります」を参照してください。

Note

Service Fabric 11.0 以降、Service Fabric Explorer には、Web リダイレクト URI ではなくシングルページ アプリケーションのリダイレクト URI が必要になります。

前提条件

この記事では、既にテナントを作成していることを前提としています。 まだ作成していない場合は、まず、Microsoft Entra テナントを取得する方法に関するページをお読みください。 Microsoft Entra ID で Service Fabric クラスターを構成する際の手順の一部を簡略化するために、一連の Windows PowerShell スクリプトが用意されています。 一部のアクションでは、Microsoft Entra ID への管理レベルのアクセスが必要です。 スクリプトで 401 または 403 の "Authorization_RequestDenied" エラーが発生する場合は、管理者がスクリプトを実行する必要があります。

  1. Azure の管理アクセス許可を使用して認証します。
  2. コンピューターにリポジトリをクローンします。
  3. インストールされたスクリプトのためのすべての前提条件が満たされていることを確認してください。

Microsoft Entra アプリケーションを作成し、ユーザーをロールに割り当てる

クラスターへのアクセスを制御するために、2 つの Microsoft Entra アプリケーション (Web アプリケーションとネイティブ アプリケーション) を作成するスクリプトを使います。 クラスターを表すアプリケーションを作成したら、Service Fabric によってサポートされるロール (読み取り専用と管理者) 用にユーザーを作成します。

SetupApplications.ps1

SetupApplications.ps1 を実行します。パラメーターとして、テナント ID、クラスター名、Web アプリケーション URI、および Web アプリケーション応答 URL を指定します。 -remove を使用して、アプリ登録を削除します。 -logFile <log file path> を使用すると、トランスクリプト ログが生成されます。 詳細については、スクリプトのヘルプ (help .\setupApplications.ps1 -full) を参照してください。 スクリプトは、Service Fabric クラスターを表す Web アプリケーションとネイティブ アプリケーションを作成します。 2 つの新しいアプリ登録エントリの形式は、次のとおりです。

  • ClusterName_Cluster
  • ClusterName_Client

注意

ナショナル クラウド (たとえば Azure Government、21Vianet が運営する Microsoft Azure) については、-Location パラメーターを指定します。

パラメーター

  • tenantId:TenantId は、PowerShell コマンド Get-AzureSubscription を実行することで検索できます。 このコマンドを実行すると、すべてのサブスクリプションの TenantId が表示されます。

  • clusterName:ClusterName は、スクリプトによって作成される Microsoft Entra アプリケーションのプレフィックスとして使われます。 実際のクラスター名と完全に一致している必要はありません。 これは、一緒に使われる Service Fabric クラスターに対して、Microsoft Entra のアーティファクトのマッピングを簡単にすることだけが目的です。

  • SpaApplicationReplyUrl:SpaApplicationReplyUrl は、サインインの完了後に Microsoft Entra ID によってユーザーに返される既定のエンドポイントです。 このエンドポイントをクラスターの Service Fabric Explorer エンドポイントとして設定します。 既存のクラスターを表す Microsoft Entra アプリケーションを作成する場合は、この URL が既存のクラスターのエンドポイントと一致することを確認してください。 新しいクラスター用のアプリケーションを作成する場合は、クラスターに使用するエンドポイントを計画し、既存のクラスターのエンドポイントを使用しないように留意してください。 既定では、Service Fabric Explorer エンドポイントは次のとおりです。https://<cluster_domain>:19080/Explorer/index.html

  • webApplicationUri:WebApplicationUri は、"検証済みドメイン" の URI と、API://{{テナント ID}}/{{クラスター名}} の API スキーム形式を使用する URI のいずれかです。 詳細については、「シングル テナント アプリケーションの AppId URI には、既定のスキームまたは検証済みドメインを使用する必要があります」を参照してください。

    API スキームの例: API://0e3d2646-78b3-4711-b8be-74a381d9890c/mysftestcluster

SetupApplications.ps1 の例

# if using cloud shell
# cd clouddrive 
# git clone https://github.com/Azure-Samples/service-fabric-aad-helpers
# cd service-fabric-aad-helpers
# code .

$tenantId = '0e3d2646-78b3-4711-b8be-74a381d9890c'
$clusterName = 'mysftestcluster'
$spaApplicationReplyUrl = 'https://mysftestcluster.eastus.cloudapp.azure.com:19080/Explorer/index.html' # <--- client browser redirect url
#$webApplicationUri = 'https://mysftestcluster.contoso.com' # <--- must be verified domain due to AAD changes
$webApplicationUri = "API://$tenantId/$clusterName" # <--- doesn't have to be verified domain

$configObj = .\SetupApplications.ps1 -TenantId $tenantId `
  -ClusterName $clusterName `
  -SpaApplicationReplyUrl $spaApplicationReplyUrl `
  -AddResourceAccess `
  -WebApplicationUri $webApplicationUri `
  -Verbose

このスクリプトは、後続のコマンドのために $configObj 変数を出力し、Azure Resource Manager テンプレートに必要な JSON を出力します。 JSON 出力をコピーし、クラスターを作成するかまたは既存のクラスターを変更するときに使って、Microsoft Entra ID 対応クラスターを作成します。

SetupApplications.ps1 の出力例

Name                           Value
----                           -----
WebAppId                       f263fd84-ec9e-44c0-a419-673b1b9fd345
TenantId                       0e3d2646-78b3-4711-b8be-74a381d9890c
ServicePrincipalId             3d10f55b-1876-4a62-87db-189bfc54a9f2
NativeClientAppId              b22cc0e2-7c4e-480c-89f5-25f768ecb439

-----ARM template-----
"azureActiveDirectory": {
  "tenantId":"0e3d2646-78b3-4711-b8be-74a381d9890c",
  "clusterApplication":"f263fd84-ec9e-44c0-a419-673b1b9fd345",
  "clientApplication":"b22cc0e2-7c4e-480c-89f5-25f768ecb439"
},

azureActiveDirectory パラメーター オブジェクト JSON

"azureActiveDirectory": {
  "tenantId":"<guid>",
  "clusterApplication":"<guid>",
  "clientApplication":"<guid>"
},

SetupUser.ps1

SetupUser.ps1 は、上記で返された $configObj 出力変数を使用して、新しく作成されたアプリ登録にユーザー アカウントを追加するために使用されます。 アプリ登録で構成されるユーザー アカウントのユーザー名を指定し、管理アクセス許可に 'isAdmin' を指定します。 新しいユーザー アカウントの場合は、新しいユーザーの一時パスワードも指定します。 パスワードは、最初のログオン時に変更する必要があります。 '-remove' を使用すると、アプリ登録だけでなく、ユーザー アカウントも削除されます。

SetupUser.ps1 ユーザー (読み取り) の例

.\SetupUser.ps1 -ConfigObj $configobj `
  -UserName 'TestUser' `
  -Password 'P@ssword!123' `
  -Verbose

SetupUser.ps1 管理者 (読み取り/書き込み) の例

.\SetupUser.ps1 -ConfigObj $configobj `
  -UserName 'TestAdmin' `
  -Password 'P@ssword!123' `
  -IsAdmin `
  -Verbose

SetupClusterResource.ps1

SetupClusterResource.ps1 は、必要に応じて、既存のクラスター リソース ARM テンプレートをエクスポートし、'azureActiveDirectory' 構成を追加または変更し、テンプレートを再デプロイするために使用できます。 '-Whatif' は、テンプレートのエクスポートと変更にのみ使用しますが、構成変更の再デプロイには使用しません。 このスクリプトには、Azure 'Az' モジュールとクラスターのリソース グループの名前が必要です。

SetupClusterResource.ps1 -whatIf の例

# requires azure module 'az'
# install-module az
$resourceGroupName = 'mysftestcluster'
.\SetupClusterResource.ps1 -configObj $configObj `
  -resourceGroupName $resourceGroupName `
  -WhatIf

テンプレートが検証され、処理の準備ができたら、'-WhatIf' なしでスクリプトを再実行するか、PowerShell コマンドレット 'New-AzResourceGroupDeployment' を使用して、テンプレートをデプロイします。

SetupClusterResource.ps1 の例

$resourceGroupName = 'mysftestcluster'
.\SetupClusterResource.ps1 -configObj $configObj `
  -resourceGroupName $resourceGroupName

Note

新しいクラスター リソース Microsoft Entra 構成変更を使って、クラスター プロビジョニング ARM テンプレートまたはスクリプトを更新します。

[API のアクセス許可] の構成で [管理者の同意の付与] が必要になることがあります。 Azure の [アプリの登録] ブレードに移動し、クラスターの名前をフィルターに追加します。 両方の登録について、[API のアクセス許可] を開き、使用可能な場合は [管理者の同意の付与] を選択します。

Screenshot that shows Grant admin consent selected on the Azure App registrations blade.

Screenshot that shows the Grant admin consent confirmation with Yes highlighted.

Microsoft Entra 構成の確認

Service Fabric Explorer (SFX) URL に移動します。 これは、パラメーター spaApplicationReplyUrl と同じにする必要があります。 Azure 認証ダイアログが表示されます。 新しい Microsoft Entra 構成で構成されたアカウントを使ってログオンします。 管理者アカウントに読み取り/書き込みアクセス権があり、ユーザーに読み取りアクセス権があることを検証します。 クラスターに対する変更 (アクションの実行など) は管理アクションです。

Microsoft Entra ID の設定に関するトラブルシューティング ヘルプ

Microsoft Entra ID の設定時や使用時には問題が発生することがあります。そこで、問題のデバッグに役立つポインターをいくつか紹介します。 'SetupApplications.ps1' スクリプトと 'SetupUser.ps1' スクリプトで '-logFile' 引数を使用すると、PowerShell トランスクリプト ログを有効にして、出力を確認できます。

注意

ID プラットフォームを (ADAL から MSAL に) 移行したり、Azure AZ を優先して AzureRM を廃止したり、複数のバージョンの PowerShell をサポートしたりすると、依存関係を常に正しく最新に維持することができないために、スクリプトの実行でエラーが発生する可能性があります。 Azure Cloud Shell から PowerShell コマンドとスクリプトを実行すると、セッション自動認証とマネージド ID に関するエラーの可能性が低くなります。

Button to launch the Azure Cloud Shell.

Request_BadRequest

問題

有効な参照更新ではありません。 HTTP 状態コード: 400。

VERBOSE: POST with 157-byte payload
VERBOSE: received -byte response of content type application/json
>> TerminatingError(Invoke-WebRequest): "{"error":{"code":"Request_BadRequest","message":"Not a valid reference update.","innerError":{"date":"2022-09-11T22:17:16","request-id":"61fadb2a-478b-4483-8f23-d17e13732104","client-request-id":"61fadb2a-478b-4483-8f23-d17e13732104"}}}"
confirm-graphApiRetry returning:True
VERBOSE: invoke-graphApiCall status: 400
exception:
Response status code doesn't indicate success: 400 (Bad Request).

Invoke-WebRequest: /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1:239
Line |
 239 |  …   $result = Invoke-WebRequest $uri -Method $method -Headers $headers  …
     |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | {"error":{"code":"Request_BadRequest","message":"Not a valid reference update.","innerError":{"date":"2022-09-11T22:17:16","request-id":"61fadb2a-478b-4483-8f23-d17e13732104","client-request-id":"61fadb2a-478b-4483-8f23-d17e13732104"}}}

at invoke-graphApiCall, /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1: line 239
at invoke-graphApi, /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1: line 275
at add-roleAssignment, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 193
at add-user, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 244
at enable-AADUser, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 178
at main, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 136
at <ScriptBlock>, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 378
at <ScriptBlock>, /home/<user>/clouddrive/aad-test.ps1: line 43
at <ScriptBlock>, <No file>: line 1
WARNING: invoke-graphApiCall response status: 400
invoke-graphApi count:0 statuscode:400 -uri https://graph.microsoft.com/v1.0/0e3d2646-78b3-4711-b8be-74a381d9890c/servicePrincipals/3d10f55b-1876-4a62-87db-189bfc54a9f2/appRoleAssignedTo -headers System.Collections.Hashtable -body System.Collections.Hashtable -method post
confirm-graphApiRetry returning:True

理由

構成変更が反映されていません。 スクリプトは特定の要求について、HTTP 状態コード 400 と 404 の場合に再試行します。

ソリューション

スクリプトは特定の要求について、HTTP 状態コード 400 と 404 の場合に、指定された '-timeoutMin' (既定では 5 分) まで再試行します。 スクリプトは、必要に応じて再実行できます。

Service Fabric Explorer に、証明書の選択を求めるメッセージが表示される

問題

Service Fabric Explorer で Microsoft Entra ID に正常にサインインすると、ブラウザーはホーム ページに戻りますが、証明書の選択を求めるメッセージが表示されます。

SFX certificate dialog

理由

ユーザーに、Microsoft Entra ID クラスター アプリケーションのロールが割り当てられていません。 そのため、Service Fabric クラスター上の Microsoft Entra 認証は失敗します。 Service Fabric エクスプローラーは、証明書認証にフォールバックします。

解決方法

次の説明に従って Microsoft Entra ID を設定してユーザー ロールを割り当てます。 また、SetupApplications.ps1 のように [アプリにアクセスするにはユーザー割り当てが必要] をオンにすることをお勧めします。

PowerShell を使用した接続が失敗し、次のエラーが返される:"指定した資格情報が無効です"

問題

"AzureActiveDirectory" セキュリティ モードで PowerShell を使ってクラスターに接続すると、Microsoft Entra ID に正常にサインインした後で接続に失敗し、"指定した資格情報が無効です" というエラーが返されます。

解決方法

前の問題の解決策と同じです。

サインインするときに Service Fabric Explorer で次のエラーが返される:"AADSTS50011"

問題

Service Fabric Explorer で Microsoft Entra ID へのサインインを試行すると、ページが "AADSTS50011: 返信先アドレス <url> が、アプリケーション用に構成された返信先アドレス <guid> と一致しません" というエラーを返します。

SFX reply address doesn't match

理由

Service Fabric Explorer に相当するクラスター (Web) アプリケーションは Microsoft Entra ID に対する認証を試み、要求の一部として、戻り先のリダイレクト URL を指定しています。 しかし、その URL が Microsoft Entra アプリケーションの [応答 URL] の一覧にありません。

ソリューション

クラスターの Microsoft Entra アプリ登録ページで [認証] を選び、[リダイレクト URI] セクションでリストに Service Fabric Explorer URL を追加します。 変更内容を保存します。

Web application reply URL

PowerShell から Microsoft Entra の認証を使ってクラスターに接続すると、サインイン時にエラーが発生します: "AADSTS50011"

問題

PowerShell から Microsoft Entra ID を使って Service Fabric クラスターに接続しようとすると、サインイン ページがエラー "AADSTS50011: The reply url specified in the request doesn't match the reply urls configured for the application: <guid>" (AADSTS50011: 要求で指定された応答 URL が、アプリケーションに対して構成された応答 URL と一致しません: ) を返します。

理由

前の問題と同様に、PowerShell では Microsoft Entra ID に対して認証を試みます。これにより、Microsoft Entra アプリケーションの応答 URL リストに一覧表示されていないリダイレクト URL が提供されます。

解決方法

前の問題と同じプロセスを使用しますが、URL に urn:ietf:wg:oauth:2.0:oob を設定する必要があります。これは、コマンド ライン認証用の特別なリダイレクトです。

スクリプトの実行の結果として承認エラーが発生する

問題

PowerShell スクリプトは、エラー "Authorization_RequestDenied"、"この操作を完了するのに十分な特権がありません" のために、Microsoft Entra 構成を完了するために必要なすべての REST コマンドを実行できない場合があります。 エラーの例:

Invoke-WebRequest: /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1:239
Line |
 239 |  …   $result = Invoke-WebRequest $uri -Method $method -Headers $headers  …
     |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | {"error":{"code":"Authorization_RequestDenied","message":"Insufficient privileges to complete the
     | operation.","innerError":{"date":"2022-08-29T14:46:37","request-id":"c4fd3acc-1558-4950-8028-68bb058f7bf0","client-request-id":"c4fd3acc-1558-4950-8028-68bb058f7bf0"}}}
...
invoke-graphApi count:0 statuscode:403 -uri https://graph.microsoft.com/v1.0/72f988bf-86f1-41af-91ab-2d7cd011db47/oauth2PermissionGrants -headers System.Collections.Hashtable -body System.Collections.Hashtable -method post
Write-Error: /home/<user>/clouddrive/service-fabric-aad-helpers/SetupApplications.ps1:364
Line |
 364 |      assert-notNull $result "aad app service principal oauth permissio …
     |      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | aad app service principal oauth permissions User.Read configuration failed

Write-Error: /home/<user>/clouddrive/service-fabric-aad-helpers/SetupApplications.ps1:656
Line |
 656 |  main
     |  ~~~~
     | exception:  exception: assertion failure: object: message:aad app service principal oauth permissions User.Read configuration failed  Exception:
     | /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1:22 Line |   22 |          throw "assertion failure: object:$obj message:$msg"      |         
     | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      | assertion failure: object: message:aad app service principal oauth permissions User.Read configuration failed  
...

理由

このエラーは、スクリプトを実行しているユーザー アカウントに、REST 呼び出しを実行するアクセス許可がない場合に返されます。 これは、作成または変更されるオブジェクトに対する管理者/管理/書き込みの各アクセス許可をユーザーが持っていない場合に発生する可能性があります。

ソリューション

Azure テナントまたは Microsoft Entra ID の管理者と連携して、残りのすべてのアクションを完了します。 指定されたスクリプトはべき等であるため、プロセスを完了するために再実行できます。

PowerShell で Microsoft Entra 認証を使用してクラスターに接続する

Service Fabric クラスターに接続するには、次の PowerShell コマンド例を使用します。

Connect-ServiceFabricCluster -ConnectionEndpoint <endpoint> -KeepAliveIntervalInSec 10 -AzureActiveDirectory -ServerCertThumbprint <thumbprint>

詳細については、Connect-ServiceFabricCluster コマンドレットに関するページを参照してください。

同じ Microsoft Entra テナントを複数のクラスターで再利用できますか?

はい。 ただし、Service Fabric Explorer の URL をクラスター (Web) アプリケーションに追加することを忘れないでください。 そうしないと、Service Fabric Explorer は動作しません。

Microsoft Entra ID が有効であってもサーバー証明書が必要なのはなぜですか?

FabricClient と FabricGateway では、相互認証が実行されます。 Microsoft Entra の認証中に、Microsoft Entra 統合からサーバーにクライアント ID が提供されます。また、サーバー証明書は、クライアントによってサーバーの ID を検証するために使用されます。 Service Fabric の証明書の詳細については、「X.509 証明書と Service Fabric」を参照してください。

次のステップ

Microsoft Entra アプリケーションを設定し、ユーザーのロールを設定したら、クラスターを構成してデプロイします。