Set up Microsoft Entra ID for client authentication in the Azure portal
Article
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.
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.
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.
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
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:
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:
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.
Discover how Microsoft Entra External ID can provide secure, seamless sign-in experiences for your consumers and business customers. Explore tenant creation, app registration, flow customization, and account security.