Set TLS certificate for standalone service fabric cluster using Windows security

Question

Set TLS certificate for standalone service fabric cluster using Windows security

Marbry Hardin 11

How do we define a certificate for HTTPS communication within a standalone service fabric cluster and service fabric explorer if we're using the Windows credential type?

This seems like it should be two separate things, but I don't see anywhere separate from the cluster and server certs to define that. And you can't have both CertificateInformation and WindowsIdentities sections in the config.

Does this mean that if you use the Windows credential type, you have to use only HTTP rather than HTTPS? Which doesn't seem to make much sense, so I assume there must be some way to do it.

0 comments

2 answers

Your answer

Answer 1

kagiyama yutaka 5,330

I think https stays fine… windowsIdentities never enters the tls path, the only failure point is the cert bind. just put ur https cert in Cluster/ServerCertificate and let sf read the thumbprint… that’s all that actually flips it.

Marbry Hardin 11 Reputation points

2026-04-04T18:49:30.18+00:00

The windowsidentities is defining who is an admin though, and it won't let you define both that and the certificate section in the config. So it's a bit confusing as there seems to be some overlap between them. This is mainly about securing an https connection for explorer while maintaining that functionality.
kagiyama yutaka 5,330 Reputation points

2026-04-05T01:36:52.8566667+00:00

I see.... I think windowsIdentities only decides who can admin, it never sits in the tls path, so there’s no overlap at all; just drop ur https cert under Cluster/ServerCertificate and sf will serve explorer over https while windows auth keeps runnin fine.
Marbry Hardin 11 Reputation points

2026-04-07T16:58:31.42+00:00

I guess I'm missing something, if you have the WindowsIdentities section defined, where exactly are you putting the certificate information within that config doc? Because it will not allow you to have both WindowsIdentities and CertificateInformation sections defined under Security. Not saying there isn't, but I don't see anywhere else in the examples given in the documentation to put that.
kagiyama yutaka 5,330 Reputation points

2026-04-08T03:33:26.31+00:00

The cert never sits under Security… u keep windowsIdentities there, and the https cert just lives in Cluster/ServerCertificate so they never clash.

Answer 2

Manish Deshpande 8,135 Microsoft External Staff Moderator

Hi Marbry,

Thank you for the clear description of your standalone Service Fabric cluster configuration question. This is a common point of confusion when mixing Windows credential type with HTTPS requirements for Service Fabric Explorer and the management API.

WindowsIdentities (under the security section) controls authentication and authorization — it defines which domain accounts or gMSA identities can connect to the cluster and which have admin rights.
The TLS/HTTPS layer for the management endpoint (port 19080) and Service Fabric Explorer is handled separately by the server certificate.
You do not need to use only HTTP. HTTPS is fully supported (and recommended for production) even when ClusterCredentialType is set to Windows.
The CertificateInformation section is used only when a credential type is X509. When using Windows security you configure the HTTPS certificate differently — specifically by setting ServerCredentialType to X509 and placing the server certificate details in the appropriate location in ClusterConfig.JSON. This keeps the two concerns cleanly separated.

Links :
https://learn.microsoft.com/en-us/azure/service-fabric/service-fabric-windows-cluster-windows-security

https://learn.microsoft.com/en-us/azure/service-fabric/service-fabric-windows-cluster-x509-security

Steps to work on

Open your ClusterConfig.JSON file (the one you use with CreateServiceFabricCluster.ps1 or TestConfiguration.ps1).

In the top-level security section, configure it like this (mixed credential types are fully supported):

  "security": {
    "ClusterCredentialType": "Windows",
    "ServerCredentialType": "X509",
    "WindowsIdentities": {
      "ClusterIdentity": "domain\\machinegroup",   // or use ClustergMSAIdentity + ClusterSPN
      "ClientIdentities": [
        {
          "Identity": "domain\\username",
          "IsAdmin": true
        }
      ]
    },
    "CertificateInformation": {
      "ServerCertificate": {
        "Thumbprint": "your-server-cert-thumbprint-here",
        "X509StoreName": "My",
        "X509StoreLocation": "LocalMachine"
      }
    }
  }

Make sure the server certificate (with the private key) is installed in the Local Computer \ Personal store on every node in the cluster, and that the NETWORK SERVICE account has read access to the private key.

Validate and deploy/upgrade the configuration:

  .\TestConfiguration.ps1 -ClusterConfigFilePath .\ClusterConfig.JSON
  .\CreateServiceFabricCluster.ps1 -ClusterConfigFilePath .\ClusterConfig.JSON -AcceptEULA

After the cluster is up, access Service Fabric Explorer using HTTPS on port 19080. The connection will be TLS-secured by the server certificate you just configured, while authentication and admin rights continue to be enforced via your Windows identities.

This approach gives you the best of both worlds: Windows-based authentication (no client certificates required) + proper TLS encryption for all management traffic and Explorer.

If you run into any validation errors during TestConfiguration or deployment, feel free to reply here with the exact error.

Thanks,
Manish.

Manish Deshpande 8,135 Reputation points Microsoft External Staff Moderator

2026-04-14T14:06:28.0333333+00:00

Hello Marbry,
I wanted to check if my last response made sense. I’d be glad to assist further or explain anything in more detail and please accept as Yes and upvote if the answer is helpful so that it can help others in the community.
Marbry Hardin 11 Reputation points

2026-04-17T16:35:47.0633333+00:00

It makes sense, thank you, that's exactly what I was looking for. I've just had some other things going on and haven't had a chance to test that yet, hopefully this afternoon though.
Manish Deshpande 8,135 Reputation points Microsoft External Staff Moderator

2026-04-22T19:38:51.7533333+00:00

Hello @Marbry Hardin

Please accept the answer as Yes and upvote if the answer is helpful so that it can help others in the community.
Marbry Hardin 11 Reputation points

2026-04-29T14:20:15.2+00:00

It ran the create script ok with that, but now it's prompting me for a user cert when I hit the explorer https URL rather than using Windows auth.
Anonymous

2026-04-29T14:51:37.4733333+00:00

Hello Marbry Hardin,We have noticed that you rated this answer as not helpful, we have reached out to you via Private Message to gather more details to assist you with more detailed manner. (with a Team's meeting as well if needed).
Manish Deshpande 8,135 Reputation points Microsoft External Staff Moderator

2026-05-06T02:33:26.07+00:00
Hi Marbry,

Thanks for the follow-up, and glad the HTTPS part is working! The client certificate prompt you're seeing is actually a well-understood behavior in this hybrid configuration, and the fix is straightforward — let me walk you through it.

Cause :

The issue is with the ServerCredentialType value in your ClusterConfig.json. When ServerCredentialType is set to "Windows", the HTTP gateway expects clients to authenticate using Windows/Kerberos credentials. However, once you add a ServerCertificate to the CertificateInformation block, Service Fabric internally treats the HTTPS endpoint as requiring mutual TLS — which causes the browser to prompt for a client certificate before Windows auth even gets a chance to kick in.

In other words: the ServerCredentialType is controlling how clients authenticate to the management API, not just whether TLS is used for transport. Because you want TLS on the wire but Windows auth for identity, these two settings need to be aligned correctly.

Fix :

The documented approach for this scenario is to set ServerCredentialType to "X509" (to tell Service Fabric to use the server certificate for the HTTPS binding), while keeping ClusterCredentialType as "Windows" (to preserve Windows/gMSA-based node-to-node auth). You then also need to add a ClientCertificateThumbprints entry so that authorized Windows clients can be mapped through.

However — and this is the important part — if your goal is purely to have HTTPS on the Explorer/management endpoint without requiring a client certificate from the browser, the cleanest approach is to ensure that your browser has access to a client certificate that is listed in ClientCertificateThumbprints. Service Fabric Explorer, when the cluster uses X509 for ServerCredentialType, expects the client (browser) to present a cert to authenticate. This is by design.

Here's the revised security section that reflects the correct hybrid setup:

"security": {

"ClusterCredentialType": "Windows",

"ServerCredentialType": "X509",

"WindowsIdentities": {

"ClustergMSAIdentity": "yourdomain\\YourGmsaAccount", "ClusterSPN": "http/servicefabric/clusterA.contoso.com", "ClientIdentities": [ { "Identity": "CONTOSO\\adminuser", "IsAdmin": true } ]

},

"CertificateInformation": {

"ServerCertificateCommonNames": { "CommonNames": [ { "CertificateCommonName": "your-cluster-fqdn.contoso.com" } ], "X509StoreName": "My" }, "ClientCertificateThumbprints": [ { "CertificateThumbprint": "<YourAdminClientCertThumbprint>", "IsAdmin": true } ]

}

}

Provision a client certificate for the administrator This can be the same cert as the server cert (for test/dev) or a separate cert. Install it into the Current User > Personal store on the machine you're browsing from.

Update ClusterConfig.json

Set ServerCredentialType to "X509"

Add the ClientCertificateThumbprints entry (as shown above) with the thumbprint of your admin client certificate

Apply the config change If the cluster is already running, apply via: .\UpdateServiceFabricCluster.ps1 -ClusterConfigFilePath .\ClusterConfig.json

Import the client cert into your browser On Windows, if the cert is installed in the Current User Personal store, Edge/Chrome will pick it up automatically. You'll still get a prompt to select the certificate — that's expected browser behavior when the server requests mutual TLS.

• The client certificate prompt from the browser is expected when ServerCredentialType is X509. There is no way to bypass it entirely while keeping HTTPS — the server is signaling that it wants to authenticate the client. If you select the right certificate, the Windows ClientIdentities will still control authorization inside Service Fabric.

• Per the documentation: "If you specify a server certificate for outside connections, set the ServerCredentialType to X509." Setting it to Windows while also providing a ServerCertificate is what's causing the mismatch you're seeing.

• ClusterCredentialType (Windows/gMSA) and ServerCredentialType (X509) can be mixed — these are independent settings controlling different authentication paths.

Thanks,
Manish
Marbry Hardin 11 Reputation points

2026-05-06T15:16:04.14+00:00

OK, so there's basically no way to accomplish that without a client certificate?

If i undrrstand correctly the client certificate would have to be deployed on any Windows instance an admin user was accessing explorer from, but they're also still authorized against the list of admin user accounts? So that would give us https connections and Windows authentication and authorization of the admins?

That's one of the things I was trying to avoid, creating a new requirement for configuration outside of the servers themselves. But at least it's confined to a small population.
Manish Deshpande 8,135 Reputation points Microsoft External Staff Moderator

2026-05-19T23:09:45.99+00:00
Hi Marbry,

Thank you for your detailed follow-up—this is a great question and you're absolutely thinking about the right trade-offs.

Yes, when you configure the Service Fabric management endpoint (Explorer / port 19080) with HTTPS using a server certificate, a client certificate is required for access when ServerCredentialType is set to X509. This behavior is by design and cannot be bypassed while keeping HTTPS enabled.

In Service Fabric, security is split into two independent layers:

ClusterCredentialType (Windows) → controls node-to-node communication and Windows-based identity/authorization

ServerCredentialType (X509) → controls how clients authenticate to the management endpoint (Explorer / APIs)

When you enable HTTPS by configuring a server certificate, Service Fabric uses certificate-based (mutual TLS) authentication for client-to-node communication.

As documented by Microsoft:

Service Fabric clusters secured with certificates use client certificates to authenticate connections to the cluster
https://learn.microsoft.com/en-us/azure/service-fabric/service-fabric-windows-cluster-x509-security

When connecting to a secure cluster using certificates, a client certificate must be installed on the machine that connects
https://learn.microsoft.com/en-us/azure/service-fabric/service-fabric-connect-to-secure-cluster

This is why your browser prompts for a certificate — the endpoint is enforcing mutual TLS.

Thanks,
Manish.
Sergey Karasev 0 Reputation points

2026-07-13T21:38:08.4733333+00:00

This approach gives you the best of both worlds: Windows-based authentication (no client certificates required) + proper TLS encryption for all management traffic and Explorer.

I checked on the builds: 11.5.116.1, 11.3.365.1, 10.1.2493.9590. In the configuration file, I used api 06-2023, 10-2017. When configuring ServerCredentialType = X509, mTLS is always used. If, as in the example, you specify only the ServerCertificate thumbprint, the ClientCertificate thumbprint will be automatically added to the configuration with a value equal to the ServerCertificate thumbprint. In other words, the browser will always ask for the certificate that is needed to establish an encrypted connection.

It remains unclear why neither the validator nor the documentation warns that, in fact, the ClientCertificate parameter is required and will be present in the cluster configuration.

And as usual,
if you need to use ClusterCredentialType = Windows, then you need to use a third-party reverse proxy to work over HTTPS without mandatory mTLS...
Manish Deshpande 8,135 Reputation points Microsoft External Staff Moderator

2026-08-05T01:03:09.6733333+00:00

Hello Marby,

I wanted to check if my last response made sense. I’d be glad to assist further or explain anything in more detail and please accept as Yes and upvote if the answer is helpful so that it can help others in the community.