Set up Microsoft Entra ID for client authentication

For clusters running on Azure, Microsoft Entra ID is recommended to secure access to management endpoints. This article describes how to set up Microsoft Entra ID to authenticate clients for a Service Fabric cluster.

On Linux, you must complete the following steps before you create the cluster. On Windows, you also have the option to configure Microsoft Entra authentication for an existing cluster.

In this article, the term "application" refers to Microsoft Entra applications, not Service Fabric applications; the distinction is made where necessary. Microsoft Entra ID enables organizations (known as tenants) to manage user access to applications.

A Service Fabric cluster offers several entry points to its management functionality, including the web-based Service Fabric Explorer and Visual Studio. As a result, you'll create two Microsoft Entra applications to control access to the cluster: one web application and one native application. After the applications are created, you'll assign users to read-only and admin roles.

Prerequisites

In this article, we assume that you have already created a tenant. If you haven't, start by reading How to get a Microsoft Entra tenant. To simplify some of the steps involved in configuring Microsoft Entra ID with a Service Fabric cluster, we have created a set of Windows PowerShell scripts. Some actions require administrative level access to Microsoft Entra ID. If the script experiences a 401 or 403 'Authorization_RequestDenied' error, an administrator needs to execute script.

1. Authenticate with Azure administrative permissions.
2. Clone the repo to your computer.
3. Ensure you have all prerequisites for the scripts installed.

Create Microsoft Entra applications and assign users to roles

We'll use the scripts to create two Microsoft Entra applications to control access to the cluster: one web application and one native application. After you create applications to represent your cluster, you'll create users for the roles supported by Service Fabric: read-only and admin.

SetupApplications.ps1

Run SetupApplications.ps1 and provide the tenant ID, cluster name, web application URI, and web application reply URL as parameters. Use -remove to remove the app registrations. Using -logFile <log file path> generates a transcript log. See script help (help .\setupApplications.ps1 -full) for additional information. The script creates the web and native applications to represent your Service Fabric cluster. The two new app registration entries are in the following format:

• ClusterName_Cluster
• ClusterName_Client

Parameters

• tenantId: You can find your TenantId by executing the PowerShell command Get-AzureSubscription. Executing this command displays the TenantId for every subscription.

• clusterName: ClusterName is used to prefix the Microsoft Entra applications that are created by the script. It doesn't need to match the actual cluster name exactly. It's intended only to make it easier to map Microsoft Entra artifacts to the Service Fabric cluster that they're being used with.

• SpaApplicationReplyUrl: SpaApplicationReplyUrl is the default endpoint that Microsoft Entra ID returns to your users after they finish signing in. Set this endpoint as the Service Fabric Explorer endpoint for your cluster. If you're creating Microsoft Entra applications to represent an existing cluster, make sure this URL matches your existing cluster's endpoint. If you're creating applications for a new cluster, plan the endpoint for your cluster and make sure not to use the endpoint of an existing cluster. By default the Service Fabric Explorer endpoint is: https://<cluster_domain>:19080/Explorer/index.html

• webApplicationUri: WebApplicationUri is either the URI of a 'verified domain' or URI using API scheme format of API://{{tenant Id}}/{{cluster name}}. See AppId Uri in single tenant applications requires use of default scheme or verified domains for additional information.

  Example API scheme: API://0e3d2646-78b3-4711-b8be-74a381d9890c/mysftestcluster

SetupApplications.ps1 example

# if using local 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.chinaeast.cloudapp.chinacloudapi.cn: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

The script outputs $configObj variable for subsequent commands and prints the JSON required by the Azure Resource Manager template. Copy the JSON output and use when creating or modifying existing cluster create your Microsoft Entra ID enabled cluster.

SetupApplications.ps1 example output

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 parameters object JSON

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

SetupUser.ps1

SetupUser.ps1 is used to add user accounts to the newly created app registration using $configObj output variable from above. Specify username for user account to be configured with app registration and specify 'isAdmin' for administrative permissions. If the user account is new, provide the temporary password for the new user as well. The password needs to be changed on first logon. If you use '-remove', you'll remove the user account, not just the app registration.

SetupUser.ps1 user (read) example

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

SetupUser.ps1 admin (read/write) example

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

SetupClusterResource.ps1

SetupClusterResource.ps1 can optionally be used to export existing cluster resource ARM template, add / modify 'azureActiveDirectory' configuration, and redeploy template. Use '-Whatif' to only export and modify template but not redeploy configuration change. This script does require Azure 'Az' module and name of the resource group for cluster.

SetupClusterResource.ps1 -whatIf example

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

Once template has been verified and is ready to process, either rerun script without '-WhatIf' or use powershell commandlet 'New-AzResourceGroupDeployment' to deploy template.

SetupClusterResource.ps1 example

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

Granting admin consent

It may be necessary to 'Grant admin consent' for the 'API permissions' being configured. Navigate to Azure App registrations blade and add name of cluster to the filter. For both registrations, open 'API permissions', and select 'Grant admin consent for' if available.

Verifying Microsoft Entra Configuration

Navigate to the Service Fabric Explorer (SFX) URL. This should be the same as the parameter spaApplicationReplyUrl. An Azure authentication dialog should be displayed. Log on with an account configured with the new Microsoft Entra configuration. Verify that the administrator account has read/write access and that the user has read access. Any modification to the cluster, for example, performing an action, is an administrative action.

Troubleshooting help in setting up Microsoft Entra ID

Setting up Microsoft Entra ID and using it can be challenging, so here are some pointers on what you can do to debug the issue. PowerShell transcript logging can be enabled by using the '-logFile' argument on 'SetupApplications.ps1' and 'SetupUser.ps1' scripts to review output.

Request_BadRequest

Problem

Not a valid reference update. Http status code: 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.chinacloudapi.cn/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

Reason

Configuration changes haven't propagated. Scripts retry on certain requests with HTTP status codes 400 and 404.

Solution

Scripts retry on certain requests with HTTP status codes 400 and 404 upto provided '-timeoutMin' which is by default 5 minutes. Script can be re-executed as needed.

Service Fabric Explorer prompts you to select a certificate

Problem

After you sign in successfully to Microsoft Entra ID in Service Fabric Explorer, the browser returns to the home page but a message prompts you to select a certificate.

Reason

The user isn't assigned a role in the Microsoft Entra ID cluster application. Thus, Microsoft Entra authentication fails on Service Fabric cluster. Service Fabric Explorer falls back to certificate authentication.

Solution

Follow the instructions for setting up Microsoft Entra ID, and assign user roles. Also, we recommend that you turn on "User assignment required to access app," as SetupApplications.ps1 does.

Connection with PowerShell fails with an error: "The specified credentials are invalid"

Problem

When you use PowerShell to connect to the cluster by using "AzureActiveDirectory" security mode, after you sign in successfully to Microsoft Entra ID, the connection fails with an error: "The specified credentials are invalid."

Solution

This solution is the same as the preceding one.

Service Fabric Explorer returns a failure when you sign in: "AADSTS50011"

Problem

When you try to sign in to Microsoft Entra ID in Service Fabric Explorer, the page returns a failure: "AADSTS50011: The reply address <url> doesn't match the reply addresses configured for the application: <guid>."

Reason

The cluster (web) application that represents Service Fabric Explorer attempts to authenticate against Microsoft Entra ID, and as part of the request it provides the redirect return URL. But the URL isn't listed in the Microsoft Entra application REPLY URL list.

Solution

On the Microsoft Entra app registration page for your cluster, select Authentication, and under the Redirect URIs section, add the Service Fabric Explorer URL to the list. Save your change.

Connecting to the cluster using Microsoft Entra authentication via PowerShell gives an error when you sign in: "AADSTS50011"

Problem

When you try to connect to a Service Fabric cluster using Microsoft Entra ID via PowerShell, the sign-in page returns a failure: "AADSTS50011: The reply url specified in the request doesn't match the reply urls configured for the application: <guid>."

Reason

Similar to the preceding issue, PowerShell attempts to authenticate against Microsoft Entra ID, which provides a redirect URL that isn't listed in the Microsoft Entra application Reply URLs list.

Solution

Use the same process as in the preceding issue, but the URL must be set to urn:ietf:wg:oauth:2.0:oob, a special redirect for command-line authentication.

Execution of script results in error in Authorization error

Problem

PowerShell script may fail to perform all of the REST commands required to complete Microsoft Entra configuration with error "Authorization_RequestDenied","Insufficient privileges to complete the operation". Example error:

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.chinacloudapi.cn/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  
...

Reason

This error is returned when the user account executing the script doesn't have the permissions to perform the REST call. This can occur if the user doesn't have Administrator/Manage/Write permissions for the objects being created or modified.

Solution

Work with an Administrator of Azure tenant or Microsoft Entra ID to complete all remaining actions. The scripts provided are idempotent, so they can be re-executed to complete the process.

Connect the cluster by using Microsoft Entra authentication via PowerShell

To connect the Service Fabric cluster, use the following PowerShell command example:

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

To learn more, see Connect-ServiceFabricCluster cmdlet.

Can I reuse the same Microsoft Entra tenant in multiple clusters?

Yes. But remember to add the URL of Service Fabric Explorer to your cluster (web) application. Otherwise, Service Fabric Explorer doesn't work.

Why do I still need a server certificate while Microsoft Entra ID is enabled?

FabricClient and FabricGateway perform a mutual authentication. During Microsoft Entra authentication, Microsoft Entra integration provides a client identity to the server, and the server certificate is used by the client to verify the server's identity. For more information about Service Fabric certificates, see X.509 certificates and Service Fabric.

Next steps

After setting up Microsoft Entra applications and setting roles for users, configure and deploy a cluster.