Set up Microsoft Entra ID for client authentication in the Azure portal

For clusters running on Azure, you can use Microsoft Entra ID to help secure access to management endpoints. This article describes how to set up Microsoft Entra ID to authenticate clients for an Azure Service Fabric cluster in the Azure portal.

In this article, the term application generally refers to Microsoft Entra applications, not Service Fabric applications. 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 you create the applications, you'll assign users to read-only and admin roles.

This article assumes that you've already created a tenant. If you haven't, start by reading Quickstart: Set up a tenant.

Open the Microsoft Entra ID App registrations pane in the Azure portal and select + New registration.

On the Register an application pane, enter the following information, and then select Register:

• Name: Enter a descriptive name. It's helpful to define a registration type in the name, as in this example: {{cluster name}}_Cluster.

• Supported account types: Select Accounts in this organizational directory only.

• Redirect URI: Select Web and enter the URL that the client will redirect to. This example uses the Service Fabric Explorer URL: https://{{cluster name}}.{{location}}.cloudapp.chinacloudapi.cn:19080/Explorer/index.html.

  After registration is complete, you can add more redirect URIs by selecting Authentication > Add URI.

After you register the cluster app, select Branding & properties and populate any additional information. For Home page URL, enter the Service Fabric Explorer URL.

Select Authentication. Under Implicit grant and hybrid flows, select the ID tokens (used for implicit and hybrid flows) checkbox.

Select Expose an API and then the Set link to enter a value for Application ID URI. Enter either the URI of a verified domain or a URI that uses an API scheme format of api://{{tenant Id}}/{{cluster name}}. For example: api://0e3d2646-78b3-4711-b8be-74a381d9890c/mysftestcluster.

For more information, see AppId URI in single-tenant applications will require use of default scheme or verified domains.

Select + Add a scope, and then enter the following information:

• Scope name: Enter user_impersonation.
• Who can consent?: Select Admins and users.
• Admin consent display name: Enter a descriptive name. It's helpful to define the cluster name and authentication type, as in this example: Access mysftestcluster_Cluster.
• Admin consent description: Enter a description like this example: Allow the application to access mysftestcluster_Cluster on behalf of the signed-in user.
• User consent display name: Enter a descriptive name. It's helpful to define the cluster name and authentication type, as in this example: Access mysftestcluster_Cluster.
• User consent description: Enter a description like this example: Allow the application to access mysftestcluster_Cluster on your behalf.
• State: Select Enabled.

Select App roles > + Create app role to add admin and read-only user roles.

Enter the following information for an admin user, and then select Apply:

• Display name: Enter Admin.
• Allowed member types: Select Users/Groups.
• Value: Enter Admin.
• Description: Enter Admins can manage roles and perform all task actions.

Enter the following information for a read-only user, and then select Apply:

• Display name: Enter ReadOnly.
• Allowed member types: Select Users/Groups.
• Value: Enter User.
• Description: Enter ReadOnly roles have limited query access.

Open the Microsoft Entra ID App registrations pane in the Azure portal, and then select + New registration.

Enter the following information, and then select Register:

• Name: Enter a descriptive name. It's helpful to define the registration type in the name, as in the following example: {{cluster name}}_Client.
• Supported account types: Select Accounts in this organizational directory only.
• Redirect URI: Select Public client/native and enter urn:ietf:wg:oauth:2.0:oob.

After you register the client app, select Authentication. Under Advanced Settings, select Yes for Allow public client flows, and then select Save.

Select API permissions > + Add a permission.

Select Delegated Permissions, select user_impersonation permissions, and then select Add permissions.

In the API permissions list, select Grant admin consent for Default Directory.

Select Yes to confirm that you want to grant admin consent.

For the client app registration only, go to the Enterprise Applications pane.

Select Properties, and then select No for Assignment required?.

For the cluster app registration only, go to the Enterprise Applications pane.

Select Properties, and then select Yes for Assignment required?.

After you create Microsoft Entra app registrations for Service Fabric, you can modify Microsoft Entra users to use app registrations to connect to a cluster by using Microsoft Entra ID.

For both the read-only and admin roles, you use Microsoft Entra ID cluster app registration. You don't use Microsoft Entra client app registration for role assignments. Instead, you assign roles from the Enterprise applications pane.

To view the enterprise applications that you created during the app registration process, you must remove the default filters for Application type and Application ID starts with from the All applications pane in the portal. Optionally, you can view enterprise applications by opening the Enterprise applications link from the API permissions pane for app registration.

The following screenshot shows default filters to be removed.

The following screenshot shows the enterprise apps with the filters removed.

To add applications to existing Microsoft Entra users, go to Enterprise Applications and find the Microsoft Entra ID cluster app registration that you created.

Select Users and groups > + Add user/group to add an existing Microsoft Entra user role assignment.

Under Users, select the None Selected link.

For users who need read-only (view) access, find each user, and then under Select a role, choose the None Selected link. Then on the Select a role pane, add the ReadOnly role.

For users who need full read/write access, find each user, and then under Select a role, choose the None Selected link. Then on the Select a role pane, add the Admin role.

In the Azure portal, open the Service Fabric Clusters pane.

Open the managed cluster resource and select Security. Select the Enable Microsoft Entra ID checkbox.

Enter the following information, and then select Apply:

• Tenant ID: Enter the tenant ID.
• Cluster application: Enter the ID for the Microsoft Entra ID cluster app registration. This is also known as the web application.
• Client application: Enter the ID for the Microsoft Entra client app registration. This is also known as the native application.

Open the cluster resource and select Security. Then select + Add.

Enter the following information, and then select Add:

• Authentication type: Select Microsoft Entra ID.
• TenantID: Enter the tenant ID.
• Cluster application: Enter the ID for the Microsoft Entra ID cluster app registration. This is also known as the web application.
• Client application: Enter the ID for the Microsoft Entra client app registration. This is also known as the native application.

To learn more about the code in the following examples, see Connect-ServiceFabricCluster cmdlet.

To use PowerShell to connect to a Service Fabric cluster, you must run the commands from a machine that has the Service Fabric SDK installed. The SDK includes nodes currently in a cluster.

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

Import-Module servicefabric

$clusterEndpoint = 'sftestcluster.chinaeast.cloudapp.chinacloudapi.cn'
$serverCertThumbprint = ''
Connect-ServiceFabricCluster -ConnectionEndpoint $clusterEndpoint `
  -AzureActiveDirectory `
  -ServerCertThumbprint $serverCertThumbprint `
  -Verbose

To connect to a managed cluster, the Az.Resources PowerShell module is also required to query the dynamic cluster server certificate thumbprint that needs to be enumerated and used.

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

Import-Module servicefabric
Import-Module Az.Resources

$clusterEndpoint = 'mysftestcluster.chinaeast.cloudapp.chinacloudapi.cn'
$clusterName = 'mysftestcluster'

$clusterResource = Get-AzResource -Name $clusterName -ResourceType 'Microsoft.ServiceFabric/managedclusters'
$serverCertThumbprint = $clusterResource.Properties.clusterCertificateThumbprints

Connect-ServiceFabricCluster -ConnectionEndpoint $clusterEndpoint `
  -AzureActiveDirectory `
  -ServerCertThumbprint $serverCertThumbprint `
  -Verbose

Setting up Microsoft Entra ID and using it can be challenging. Here are some pointers on what you can do to debug problems.

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.

The user is not assigned a role in the Microsoft Entra ID cluster application, so Microsoft Entra authentication fails on the Service Fabric cluster. Service Fabric Explorer falls back to certificate authentication.

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.

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."

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.

When you try to sign in to Microsoft Entra ID in Service Fabric Explorer, the page returns an error: "AADSTS50011: The reply address <url> does not match the reply addresses configured for the application: <guid>."

The cluster (web) application that represents Service Fabric Explorer tries to authenticate against Microsoft Entra ID. As part of the request, it provides the redirect return URL. But the URL isn't listed in the Redirect URIs list for the Microsoft Entra application.

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

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

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

On the Microsoft Entra app registration page for your cluster, select Authentication. In the Redirect URIs section, set the URL to urn:ietf:wg:oauth:2.0:oob. This URL is a special redirect for command-line authentication.

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

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

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