DEV Community: shailugit

Azure API Management - Deploy gRPC API on Azure API management using self hosted gateway

shailugit — Sun, 31 May 2026 03:25:05 +0000

This is a complete guide with steps by step process to deploy the gRPC and how to use Azure API Management to import the gRPC API.
It cover step‑by‑step guide to deploying a gRPC API on Azure API Management (APIM), grounded in the Microsoft documentation and a real-world deployment workflow.

NOTE: This post is published already in GITHUB here. https://github.com/shailugit/apimGrpc/blob/main/README.md

The API Management can expose gRPC services, but with important constraints:

APIM supports gRPC by importing a .proto file and forwarding calls to a gRPC backend.
gRPC requires HTTP/2 end‑to‑end.
gRPC APIs are supported in Self-hosted gateway and not supported in APIM v2 tiers.
You can't use the test console to test gRPC

The major steps claissfied in two major steps

Creating a gRPC server
Calling the gPRC application using APIM

1. Creating gRPC Application

Typical backend deployment steps include the following

Create a .NET gRPC server application
Create a .NET gRPC client application
Test the setup locally
Publish the .NET gRPC server to Azure WebApp and verify the service works directly over HTTPS

Step-1
As a first step we will be building a .NET gRPC server application.
You can skip this step in case you already have gRPC server application.
If you would like to view .NET Core sample used for this sample project, please visit here.

Step-2
As a second step we will be building a .NET gRPC client application. You can skip this step in case you already have gRPC client.
If you would like to view .NET Core client used for this sample project, please visit the below here.

Step-3
Once your client and server code is ready here are the steps to Test your application locally

Step-4
Deploy the server to Azure WebApp
To understand how-to deploy a .NET 6 gRPC app on App Service, please visit here.
Please make sure to enable HTTP version, Enable HTTP 2.0 Proxy and add HTTP20_ONLY_PORT application setting as gRPC only work using http2.0 as shown below

2. Calling gRPC from APIM

Typical API deployment steps include the following

Deploy the self hosted gateway on Azure API management.
Import the gRPC API in API Management
Update the .NET gRPC client application to test using API management.
Since gRPC requires HTTP/2 for inbound and outbound traffic make sure that you enabled HTTP/2 protocol for client traffic.
Go to API Management(left side blade) Settings → Protocols & Ciphers
Enable HTTP/2

Step-1
Deploy the self hosted gateway on Azure API management as explianed here

Step-2
Import the gRPC API in API Management and enable the http2 in API management as shown below

Open your APIM instance in Azure Portal.
Go to APIs > Under Define a new API, select gRPC.
Upload your .proto file.
Enter your gRPC server URL (must be HTTPS + HTTP/2).
Select the gateway you want to expose it on.
Click Create.
API will Parse the .proto file and create operations for each RPC method and Map them to the backend service

Step-3
As a last step update the .NET gRPC client application to test or call the endpoint using API management.
Ref this link

Common ssues & Fixes

APIM cannot route the request

Cause: .proto mismatch or wrong method name.As
Fix: Re-import correct .proto.

Backend not reachable

Cause: HTTP/2 disabled on App Service.
Fix: Enable HTTP/2 + HTTP2 Proxy.

Testing fails in APIM portal

Cause: Portal does not support gRPC testing.
Fix: Use external gRPC client.

Configuring CORS in Azure API Management

shailugit — Sat, 30 May 2026 19:08:48 +0000

Configuring CORS in Azure API Management is about adding the built‑in cors policy in the right scope. You can set it up at all APIs or a single API/single operation and setting the allowed origins, methods, and headers correctly. This article will explain step by step on how to setup APIM CORS policy from basics to testing and common pitfalls.

This policy let browser-based apps to call your APIs hosted behind APIM without being blocked by the browser’s same-origin policy. APIM handle preflight OPTIONS requests and add the right headers before the request hits your backend.

Here are the basic CORS configuration which you can setup via Azure portal.

Open your APIM instance

Go to Azure portal and search for “API Management services” and select your APIM instance from the list.

Add CORS policy at the desired scope

To configure at API level (most common):

In the left menu, select APIs and choose the API you want to configure.

In the Design or Policies view, locate Inbound processing.
- Click + Add policy.
- Choose “Allow cross-origin resource sharing (CORS)” from the list.
- You’ll see a form-based editor where you can set:
- Allowed origins – e.g. https://myapp.com, https://app.contoso.com
- Allowed methods – e.g. GET, POST, PUT, DELETE
- Allowed headers – e.g. Content-Type, Authorization, custom headers
- Expose headers – headers the browser can read from responses
- Allow credentials – whether to allow cookies/auth headers

<inbound> <cors allow-credentials="true"> <allowed-origins> <origin>https://apim-one-shailesh.developer.azure-api.net</origin> </allowed-origins> <allowed-methods preflight-result-max-age="60"> <method>POST</method> <method>PATCH</method> </allowed-methods> <allowed-headers> <header>*</header> </allowed-headers> <expose-headers> <header>*</header> </expose-headers> </cors> </inbound>

Click Save to apply.
Initally lets allow all the methods to call and to test the scenerio we will be using APIM developer portal test console to work so you can try APIs from the portal, here portal’s domain must be in your CORS policy’s allowed origins.

In your APIM instance, under Developer portal → Portal overview, there’s an Enable CORS option that can auto-configure a CORS policy for all APIs.
Alternatively, manually add the portal domain to your global CORS policy.

Since in the above sample code "GET" method is not allowed in CORS policy , hence testing it via APIM developer portal is showing CORS validation error.

You can allowed origins, headers or methods as your scenario grows.

Note: If you put CORS only at Product scope and your API uses subscription key in a header, the preflight OPTIONS request may fail because it doesn’t include the subscription key header. Prefer API/global scope or pass the key via query string in that scenario.

Common mistakes and how to avoid them
No CORS policy at all:
Browser shows “No Access-Control-Allow-Origin header is present” → Add a cors policy at the appropriate scope.

Using * with credentials:

If allow-credentials="true", you cannot use * for allowed-origins. List explicit origins instead.

Multiple conflicting CORS policies:

Having one at global and another at API level with different settings can cause unexpected behavior. Consolidate into one clear policy.

Forgetting custom headers:

If your frontend sends headers like x-api-version or x-request-id, they must be listed in or the preflight will fail.

OPTIONS not defined in backend:
Without a CORS policy, APIM may return 405 Method Not Allowed for OPTIONS because no operation is defined. The cors policy handles OPTIONS at the gateway so your backend doesn’t need to.

Azure API Management Service with Custom Domain

shailugit — Sat, 11 Apr 2026 02:28:15 +0000

Scenario:
When you create an Azure API Management service instance, Azure assigns a domain of *.azure-api.net like .azure-api.net. However, in general you see customers do expose their API Management endpoints using their own custom domain name. This tutorial will show steps by steps how you can procure custom domain and then setup your APIM instance to map the custom domain name.

Pre-requirements
Before we start, we could make sure that we have APIM service created
Obtain/Buy a custom domain name owned by you or your organization.

Note: The document I already publised it at my GITHUB here
https://github.com/shailugit/Azure-API-Management-Blogs/blob/main/APIM%20with%20Custom%20Domain.md

Steps:
To set up a custom domain in Azure API Management (APIM) we should have APIM instance available and obtain a custom domain name.
Once done we should have a valid certificate with a public and private key (.PFX) matches the domain name for DNS Configuration.
Later we have to host DNS records on a DNS server to map the custom domain name to the default domain name of your API Management instance.

Please follow the below steps to capture your domain name and how to map it with your API Management instance.
First you need to create an API Management instance using the steps in the document below, for the same I am using APIM Developer Tier. Please note that we are not using APIM in VNET mode as it may need additional changes in case you are using your own DNS server.

Refer
https://learn.microsoft.com/en-us/azure/api-management/api-management-get-started#a-namecreate-service-instance-acreate-an-api-management-instance.

The first step is to have a custom domain name. To purchase the custom domain you can look for various domain name registrars like Namecheap, GoDaddy, Google Domains, or any other service providers. However for our demo purpose I am using the IONOS service here.

You can also use the Azure App service domain https://learn.microsoft.com/en-us/azure/app-service/manage-custom-dns-buy-domain
but I since I get a good discount at https://www.ionos.com/ and able to procure my domain in less than a dollar for a year hence I am using this service.

To purchase the domain look for the any of the above domain provider or check out the domain name. I google free custom domain service however as of writing this article I don't see any registrars providing free services.

Since I used IONOS I need to login and create a account(Simple step).
Then look for your domain name if available and purchase it. This service will provide you free email and other offers however please see fit based on your needs. The IONOS will take 6-8 hours to confirm the availability of your domain.

This is how your order will look like once you create and submit the order to purchase a domain name. The potal will allow you to create a login for IONOS where you are configure your domain and purchase other products offered.

Confirm your order and agree on the contract details since it will auto renew, so if you are just using this for testing purpose please check your bill for next year(if you would like to continue or not).

I just need to setup our Custom domain hence I purchase Domain and SSL only option and once domain is available you will receive the email confirmation. This is how your domain registration looks like once your domain is ready to use and you logged in to your IONOS dashboard.

Now the next steps is to generate the SSL certificate for your register domain.
Select the domain and click the gear icon next to the SSL certificate you want to set up. Then, click Set up SSL certificate. Click Activate now in the SSL Unlimited tile. In the input field, enter the domain to which the certificate should be issued or click in the input field and select the desired domain to generate the certificate.

Once the certificate is generated click Download Private Key and save the private key to your computer. It's important to have this private key as you may need it in future. However you can Reissue the certificate or download certificate files under tab SSL Certificate files. Since we need PFX files for our APIM instance hence download the .PFX file. To create a password-protected .PFX file, you have to provide the private key and a password. Please do select create intermediate certificate option and provide the private key and password for PFX file.

Please note that the certificate is required with a public and private key (.PFX) and subject or subject alternative name (SAN) must match the domain name which will enable your API Management instance to securely expose URLs over SSL.

Now to setup the custom domain go to your APIM instance and select Custom domain blade under Deployment +Infrastructure. Here is a default domain provided my APIM service. To add your custom domain Click on + Add button

For the demo purpose I am adding the certificate for my Gateway and Developer portal, the option below is using certificate file directly loading to Azure API management however if you prefer you can select certificate from Key Vault. The host name here for Gateway is api.aztechbytes.com and for developer portal is developer.aztechbytes.com.

Since I am using custom domain for gateway and developer portal hence I added both under Custom domain. Adding custom domain may take up to 45+ min and your developer SKU will be down for this operation. Once the custom domain updated scessfully you will see the names under your APIM>Custom domain. Now call your APIM endpoint using your custom domain and customize your APIM developer portal.