Browser prompts to select a client certificate when browsing to custom domain (Developer Portal, Internal VNet mode)

Ankit Pathak 0 Reputation points

Environment: Azure API Management, Developer tier, Internal VNet mode (private IP only, no public endpoint). Custom domain configured for the Developer Portal, resolving to the APIM private IP via a Private DNS Zone.

Issue: When browsing to [CUSTOM_DOMAIN] from a machine with network access to the APIM private IP, the browser shows a "Select a certificate for authentication" dialog before the Developer Portal loads (screenshot attached). It lists personal certificates from the local certificate store, including one resembling the custom domain name.

What I've checked: DNS resolves correctly to the private IP. [Confirm before posting: is "Negotiate client certificate" on this custom domain set to On or Off in the APIM portal? If unsure, say "currently unsure" instead.]

Question: What triggers a client certificate prompt on an APIM custom domain configured for the Developer Portal — is this controlled solely by the "Negotiate client certificate" setting on the custom domain, or can it originate elsewhere (e.g., an upstream proxy's SSL profile)? If we don't need client cert auth, what's the correct way to ensure the custom domain does standard server-side TLS only?👁 Screenshot 2026-06-17 172234

  1. Rakesh Mishra 9,695 Reputation points • Microsoft External Staff • Moderator

    Hello Ankit,

    Welcome to the Microsoft Q&A Platform! Thank you for asking your question here.

    The browser prompt you are seeing is triggered during the initial TLS handshake. When the "Negotiate client certificate" setting is enabled on a hostname in your Azure API Management instance, APIM sends a CertificateRequest message to the client, which forces the browser to display a list of available client certificates to the user.

    As per the official Microsoft documentation on configuring custom domains, this setting is intended for scenarios requiring mutual TLS (mTLS). If your intent is to use standard server-side TLS (one-way authentication) for the Developer Portal, you must ensure this setting is disabled:

    Navigate to your API Management instance in the Azure portal.

    In the left-hand menu, under Deployment + infrastructure, select Custom domains.

    Click on the custom domain (or the gateway hostname) associated with your Developer Portal.

    Expand Advanced settings and verify that Negotiate client certificate is set to Off.

    Click Save.

    Please note that changes to custom domain settings may take a few minutes to propagate across the APIM gateway. If you continue to see the prompt after disabling this setting and allowing time for propagation, the request may be originating from an upstream component (e.g., an Azure Application Gateway or a private load balancer) configured to terminate TLS and request client certificates. You should verify the SSL profile settings of any such intermediary devices in your network architecture.

    Please let me know if it works or any other questions.

Sign in to comment

1 answer

  1. AI answer

    The client certificate prompt is triggered when the TLS endpoint requests a client certificate during the SSL/TLS handshake. In Azure API Management, this behavior is controlled by the client-certificate settings on the APIM gateway/hostnames, not by the Developer Portal itself.

    From the documented behavior:

    • For Developer, Basic, Standard, and Premium tiers, enabling Negotiate client certificate on a gateway hostname causes APIM to request a client certificate at SSL/TLS connection time, before any HTTP request is exchanged.
    • This setting applies at the Gateway hostname level. When it is enabled, all connections to that hostname will prompt for a client certificate, regardless of which API or portal feature is being accessed.
    • The same setting is also recommended to avoid client-certificate deadlocks and request freezes for large PUT/POST payloads, which confirms that the prompt originates from the APIM TLS endpoint, not from an upstream application.

    Therefore:

    • If the custom domain used for the Developer Portal (or any shared gateway hostname) has Negotiate client certificate enabled, browsers will show a “Select a certificate for authentication” dialog whenever users browse to that hostname.
    • If an upstream proxy or WAF terminates TLS and is configured to request client certificates, that device could also cause a prompt; however, on APIM itself the documented control is the Negotiate client certificate setting on the custom domain/gateway hostname.

    To ensure the custom domain uses standard server-side TLS only (no client certificate prompt) on APIM:

    1. In the Azure portal, open the API Management instance.
    2. Go to Deployment + infrastructure → Custom domains.
    3. Select the relevant gateway/hostname entry that corresponds to the Developer Portal custom domain.
    4. Make sure Negotiate client certificate is not selected for that hostname, then Update and Save.

    With Negotiate client certificate disabled, APIM will no longer request client certificates during the TLS handshake, and the browser will stop prompting for a client certificate when accessing that custom domain.

    If a client certificate prompt still appears after disabling this setting, the cause is likely an upstream TLS-terminating component (for example, Application Gateway or another proxy) whose SSL profile is configured to request client certificates.

    References:

    AI-generated content may be incorrect. Read our transparency notes for more information.
Sign in to answer

Your answer