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.

Note

• 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.
• It's a known issue that applications and nodes on Linux Microsoft Entra ID-enabled clusters can't be viewed in the Azure portal.
• Microsoft Entra ID now requires an application's (app registration) publisher domain to be verified or use a default scheme. For more information, see Configure an application's publisher domain and AppId URI in single-tenant applications will require use of default scheme or verified domains.

Prerequisites

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

Register a Microsoft Entra ID cluster app

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.azure.com:19080/Explorer/index.html.

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

Note

Add more redirect URIs if you're planning to access Service Fabric Explorer by using a shortened URL, such as https://{{cluster name}}.{{location}}.cloudapp.azure.com:19080/Explorer. An exact URL is required to avoid this AADSTS50011 error: "The redirect URI specified in the request does not match the redirect URIs configured for the application. Make sure the redirect URI sent in the request matches one added to the application in the Azure portal." Learn more about troubleshooting this error.

Branding & properties

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

Authentication

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

Expose an API

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.

App roles

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.

Register a Microsoft Entra client app

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.

Authentication

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

API permissions

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.

Properties

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

Assign application roles to users

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.

Remove filters

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.

Add role assignments to Microsoft Entra users

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.

Configure clusters with Microsoft Entra registrations

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

Service Fabric managed cluster configuration

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.

Service Fabric cluster configuration

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.

Connect to a cluster with Microsoft Entra ID

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

Connect to a Service Fabric cluster by using Microsoft Entra authentication via PowerShell

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.eastus.cloudapp.azure.com'
$serverCertThumbprint = ''
Connect-ServiceFabricCluster -ConnectionEndpoint $clusterEndpoint `
  -AzureActiveDirectory `
  -ServerCertThumbprint $serverCertThumbprint `
  -Verbose

Connect to a Service Fabric managed cluster by using Microsoft Entra authentication via PowerShell

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.eastus.cloudapp.azure.com'
$clusterName = 'mysftestcluster'

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

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

Troubleshoot setting up Microsoft Entra ID

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

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

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

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.

Service Fabric Explorer returns an error when you sign in: "AADSTS50011"

Problem

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

Reason

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.

Solution

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.

Connecting to the cluster by 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 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>."

Reason

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.

Solution

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.

FAQ

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

Next steps

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