API call with client certificate policy failing to execute due to message size on Azure API Management

Well, that is a mouthful of a title, but I wanted to capture the exact issue, because I couldn’t find any page to help with this specific error and managed to get it fixed thanks to Vladimir Vinogradsky pointing me out to a tip in one of the APIM docs.

So my scenario was this: my team was working on an API that is protected with a client certificate policy – quite simple, very straightforward. At the API level it had the following policy:

             c.Value.Thumbprint == context.Request.Certificate.Thumbprint))">

So, nothing special, right? And for the most part it worked. Then all of a sudden, the api call would freeze when I try to send a “large” message! But large compared to the other messages – the messages that worked were 10-15 kb, while this one was 32 kb. I didn’t return any errors, any response, just failed after a couple of minutes, which was the client timeout.

What my team found is that removing some of the content – the message had a huge number of gps coordinates, so we’ve removed almost all of them, cause we only needed the first one – it would work.

To confirm that the problem was not the message itself, but the certificates, we removed the policy and send the full message – it worked without a glitch. So everything pointed to a combination of message size and the client certificate. Which proved to be right.

The root case of that issue is documented here, and Microsoft have the APIM solution documented on this page, as a tip. But no internet search I’ve made pointed me to that page.

In the end, the fix was quite simple. What I needed to do was enable negotiate client certificate on the gateway endpoint. To do that you can follow the steps below:

  1. Within you API Management instance, navigate to Custom domains.
  2. Under endpoints, click on the Gateway
  3. Once in the Gateway properties, enable Negotiate client certificate
  4. Click on Update
  5. Finally remember to Save your changes.
Enabling client certificate negotiation on the Gateway endpoint.

On my environments that up to 5 minutes to persist those changes, but you will receive a notification that it is been completed successfully.

Once that was updated, the large message was processed just like the smaller ones.

So if you are planning to use client certificate validation on your inbound policies, I would suggest that you enable this property on your gateway, to avoid having surprises when your messages go over a certain size. Microsoft documentation says around 60 KB, but my messages presented on much smaller values – around 30 KB.

Although this solves the problem on the subscription plans (developer, basic, standard, premium) this option is not available in the consumption plan. And seems like at this stage this is not a feature that will be available in that plan.

Hopefully if you had this issue too, you managed to find this post and it avoided you scratching your head for a couple of hours like I did…

Sharing is caring...

3 thoughts on “API call with client certificate policy failing to execute due to message size on Azure API Management”

  1. Hi, I ran into this last week and eventually figured it out but wish I’d seen this article beforehand! Originally we had “Negotiate client certificate” ON BUT it would then challenge users for a cert if for example they used a web browser. Anyway we turned it off to combat this and tested any APIs that required cert auth and they still worked … but then a week later we had the above issue due to a 100K payload. So we turned it back on BUT we still have the issue of issues with APIs that don’t require a cert for auth but still perform the challenge (so if it’s from a web browser the user would be asked to select a cert but there’s no need and cancelling will let them continue the call).

    Is there anyway to turn off the client cert challenge in the policy or a solution that will cover both scenarios? The only thing I can think of is that we setup a separate hostname to handle client certs and setting “Negotiate client certificate” to ON and OFF for our standard hostname.

    Thanks in advance for any help/advice you can give.



    1. Hi Steve,

      Sorry for the late reply. Unfortunately I am not sure if I have an answer to you on that one. Probably something that would be worth asking the Product Group. Are you part of the Azure Customer Connection on Yammer. The API Management product group is quite active there. The address is https://www.yammer.com/azureadvisors – then search for the API Management group.

    2. Hi Steve,
      I am running into the same/similar issue as you described here. I would like to avoid client negotiation for all API calls as I only need it for a subset of calls. Ideally I could control this at the individual policy level. I’d rather not set up an additional gateway. Did you ever figure out a way to handle your issue?

Leave a Reply

Your email address will not be published.