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.

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.

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…