Skip to content

app-service-web-tutorial-rest-api.md

Latest commit

 

History

History
237 lines (154 loc) · 11.4 KB

app-service-web-tutorial-rest-api.md

File metadata and controls

237 lines (154 loc) · 11.4 KB
title Tutorial: Host a RESTful API with CORS
description Learn how Azure App Service helps you host your RESTful APIs with CORS support. App Service can host both front-end web apps and back-end APIs.
ms.assetid a820e400-06af-4852-8627-12b3db4a8e70
ms.devlang csharp
ms.topic tutorial
ms.date 08/29/2025
ms.update-cycle 1095-days
ms.custom UpdateFrequency3, devx-track-csharp, mvc, devcenter, devx-track-azurecli
ms.author msangapu
author msangapu-msft
ms.service azure-app-service

Tutorial: Host a RESTful API with CORS in Azure App Service

Azure App Service provides a highly scalable self-patching web hosting service. In addition, App Service has built-in support for cross-origin resource sharing (CORS) for RESTful APIs. This tutorial shows how to deploy an ASP.NET Core API app to App Service with CORS support. You configure the app by using command-line tools and deploy the app by using Git.

In this tutorial, you learn how to:

[!div class="checklist"]

  • Create App Service resources by the using the Azure CLI.
  • Deploy a RESTful API to Azure by using Git.
  • Enable App Service CORS support.

You can complete this tutorial on macOS, Linux, or Windows.

[!INCLUDE quickstarts-free-trial-note]

Prerequisites

Create a local ASP.NET Core app

In this step, you set up the local ASP.NET Core project. App Service supports the same workflow for APIs written in other languages.

Clone the sample application

  1. In the terminal window, use cd to go to a working directory.

  2. Clone the sample repository, and then go to the repository root.

    git clone https://github.com/Azure-Samples/dotnet-core-api
cd dotnet-core-api

    This repository contains an app that's based on the tutorial ASP.NET Core web API documentation with Swagger / OpenAPI. It uses a Swagger generator to serve the Swagger UI and the Swagger JSON endpoint.

  3. Make sure the default branch is main.

    git branch -m main

    [!TIP] The branch name change isn't required by App Service. However, because many repositories are changing their default branch to main (see Change deployment branch), this tutorial shows how to deploy a repository from main.

Run the application

  1. Run the following commands to install the required packages, run database migrations, and start the application.

    dotnet restore
dotnet run

  2. Go to http://localhost:5000/swagger in a browser to try the Swagger UI.

    Screenshot of an ASP.NET Core API running locally.

  3. Go to http://localhost:5000/api/todo to see a list of ToDo JSON items.

  4. Go to http://localhost:5000 and experiment with the browser app. Later, you'll point the browser app to a remote API in App Service to test CORS functionality. Code for the browser app is found in the repository's wwwroot directory.

  5. To stop ASP.NET Core at any time, select Ctrl+C in the terminal.

[!INCLUDE cloud-shell-try-it.md]

Deploy the app to Azure

In this step, you deploy your .NET Core application to App Service.

Configure local Git deployment

[!INCLUDE Configure a deployment user]

Create a resource group

[!INCLUDE Create resource group]

Create an App Service plan

[!INCLUDE Create app service plan]

Create a web app

[!INCLUDE Create web app]

Push to Azure from Git

[!INCLUDE app-service-plan-no-h]

Enumerating objects: 83, done.
Counting objects: 100% (83/83), done.
Delta compression using up to 8 threads
Compressing objects: 100% (78/78), done.
Writing objects: 100% (83/83), 22.15 KiB | 3.69 MiB/s, done.
Total 83 (delta 26), reused 0 (delta 0)
remote: Updating branch 'master'.
remote: Updating submodules.
remote: Preparing deployment for commit id '509236e13d'.
remote: Generating deployment script.
remote: Project file path: .\TodoApi.csproj
remote: Generating deployment script for ASP.NET MSBuild16 App
remote: Generated deployment script files
remote: Running deployment command...
remote: Handling ASP.NET Core Web Application deployment with MSBuild16.
remote: .
remote: .
remote: .
remote: Finished successfully.
remote: Running post deployment command(s)...
remote: Triggering recycle (preview mode disabled).
remote: Deployment successful.
To https://<app_name>.scm.azurewebsites.net/<app_name>.git
* [new branch]      master -> master

Browse to the Azure app

  1. Go to http://<app_name>.azurewebsites.net/swagger in a browser and view the Swagger UI.

    Screenshot of an ASP.NET Core API running in Azure App Service.

  2. Go to http://<app_name>.azurewebsites.net/swagger/v1/swagger.json to see the swagger.json for your deployed API.

  3. Go to http://<app_name>.azurewebsites.net/api/todo to see your deployed API working.

Add CORS functionality

Next, you enable the built-in CORS support in App Service for your API.

Test CORS in the sample app

  1. In your local repository, open wwwroot/index.html.

  2. On line 51, set the apiEndpoint variable to the URL of your deployed API (http://<app_name>.azurewebsites.net). Replace <appname> with your app name.

  3. In your local terminal window, run the sample app again.

    dotnet run

  4. Go to the browser app at http://localhost:5000. Open the developer tools window in your browser (Ctrl+Shift+i in Chrome for Windows) and inspect the Console tab. You should now see the error message No 'Access-Control-Allow-Origin' header is present on the requested resource.

    Screenshot of the CORS error in the browser client.

    The domain mismatch between the browser app (http://localhost:5000) and remote resource (http://<app_name>.azurewebsites.net) is recognized by your browser as a cross-origin resource request. Also, because the App Service app isn't sending the Access-Control-Allow-Origin header, the browser has prevented cross-domain content from loading.

    In production, your browser app would have a public URL instead of the localhost URL, but the process for enabling CORS to a localhost URL is the same as the process for a public URL.

Enable CORS

In Cloud Shell, enable CORS to your client's URL by using the az webapp cors add command. Replace the <app-name> placeholder.

az webapp cors add --resource-group myResourceGroup --name <app-name> --allowed-origins 'http://localhost:5000'

You can add multiple allowed origins by running the command multiple times or by adding a comma-separated list in --allowed-origins. To allow all origins, use --allowed-origins '*'.

Test CORS again

Refresh the browser app at http://localhost:5000. The error message in the Console window is now gone, and you can see the data from the deployed API and interact with it. Your remote API now supports CORS to your browser app running locally.

Screenshot that shows CORS support in the browser client.

Congratulations, you're running an API in Azure App Service with CORS support.

Frequently asked questions

App Service CORS vs. your CORS

To get more flexibility, you can use your own CORS utilities instead of App Service CORS. For example, you might want to specify different allowed origins for different routes or methods. Because App Service CORS lets you specify only one set of accepted origins for all API routes and methods, you would need to use your own CORS code. To learn how to enable CORS in ASP.NET Core, see Enable CORS.

The built-in App Service CORS feature doesn't have options to allow only specific HTTP methods or verbs for each origin that you specify. It automatically allows all methods and headers for each origin defined. This behavior is similar to ASP.NET Core CORS policies when you use the options .AllowAnyHeader() and .AllowAnyMethod() in the code.

Note

Don't try to use App Service CORS and your own CORS code together. If you try to use them together, App Service CORS takes precedence and your own CORS code has no effect.

How do I set allowed origins to a wildcard subdomain?

A wildcard subdomain like *.contoso.com is more restrictive than the wildcard origin *. The app's CORS management page in the Azure portal doesn't let you set a wildcard subdomain as an allowed origin. However, you can do that by using the Azure CLI:

az webapp cors add --resource-group <group-name> --name <app-name> --allowed-origins 'https://*.contoso.com'

How do I enable the ACCESS-CONTROL-ALLOW-CREDENTIALS header on the response?

If your app requires credentials such as cookies or authentication tokens to be sent, the browser might require the ACCESS-CONTROL-ALLOW-CREDENTIALS header on the response. To enable this in App Service, set properties.cors.supportCredentials to true:

az resource update --name web --resource-group <group-name> \
  --namespace Microsoft.Web --resource-type config \
  --parent sites/<app-name> --set properties.cors.supportCredentials=true

This operation isn't allowed when allowed origins include the wildcard origin '*'. Specifying AllowAnyOrigin and AllowCredentials isn't secure. Doing so can result in cross-site request forgery. To allow credentials, try replacing the wildcard origin with wildcard subdomains.

[!INCLUDE cli-samples-clean-up]

Next step

What you learned:

[!div class="checklist"]

  • Create App Service resources by using the Azure CLI.
  • Deploy a RESTful API to Azure by using Git.
  • Enable App Service CORS support.

Go to the following tutorial to learn how to authenticate and authorize users.

[!div class="nextstepaction"] Tutorial: Authenticate and authorize users end-to-end