You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 backend APIs.
2
+
title: 'Tutorial: Host a RESTful API with CORS'
3
+
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.
# Tutorial: Host a RESTful API with CORS in Azure App Service
14
14
15
-
[Azure App Service](overview.md) provides a highly scalable, self-patching web hosting service. In addition, App Service has built-in support for [Cross-Origin Resource Sharing (CORS)](https://wikipedia.org/wiki/Cross-Origin_Resource_Sharing) 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 using command-line tools and deploy the app using Git.
15
+
[Azure App Service](overview.md) provides a highly scalable self-patching web hosting service. In addition, App Service has built-in support for [cross-origin resource sharing (CORS)](https://wikipedia.org/wiki/Cross-Origin_Resource_Sharing) 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 using command-line tools and deploy the app using Git.
16
16
17
17
In this tutorial, you learn how to:
18
18
19
19
> [!div class="checklist"]
20
-
> * Create App Service resources using Azure CLI
21
-
> * Deploy a RESTful API to Azure using Git
22
-
> * Enable App Service CORS support
20
+
> * Create App Service resources using Azure CLI.
21
+
> * Deploy a RESTful API to Azure using Git.
22
+
> * Enable App Service CORS support.
23
23
24
-
You can follow the steps in this tutorial on macOS, Linux, Windows.
24
+
You can complete this tutorial on macOS, Linux, or Windows.
This repository contains an app that's created based on the following tutorial: [ASP.NET Core Web API help pages using Swagger](/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs=visual-studio). It uses a Swagger generator to serve the [Swagger UI](https://swagger.io/swagger-ui/) and the Swagger JSON endpoint.
48
+
This repository contains an app that's created based on the tutorial [ASP.NET Core web API documentation with Swagger / OpenAPI](/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs=visual-studio). It uses a Swagger generator to serve the [Swagger UI](https://swagger.io/swagger-ui/) and the Swagger JSON endpoint.
51
49
52
50
1. Make sure the default branch is `main`.
53
51
@@ -56,7 +54,7 @@ In this step, you set up the local ASP.NET Core project. App Service supports th
56
54
```
57
55
58
56
> [!TIP]
59
-
> The branch name change isn't required by App Service. However, since many repositories are changing their default branch to `main` (see [Change deployment branch](deploy-local-git.md#change-deployment-branch)), this tutorial also shows you how to deploy a repository from `main`.
57
+
> The branch name change isn't required by App Service. However, since many repositories are changing their default branch to `main` (see [Change deployment branch](deploy-local-git.md#change-deployment-branch)), this tutorial shows you how to deploy a repository from `main`.
60
58
61
59
### Run the application
62
60
@@ -67,23 +65,23 @@ In this step, you set up the local ASP.NET Core project. App Service supports th
67
65
dotnet run
68
66
```
69
67
70
-
1. Navigate to `http://localhost:5000/swagger`in a browser to play with the Swagger UI.
68
+
1. Navigate to `http://localhost:5000/swagger`in a browser to try the Swagger UI.
71
69
72
-
70
+
73
71
74
-
1. Navigate to `http://localhost:5000/api/todo`and see a list of ToDo JSON items.
72
+
1. Navigate to `http://localhost:5000/api/todo`to see a list of ToDo JSON items.
75
73
76
-
1. Navigate to `http://localhost:5000` and play with the browser app. Later, you will point the browser app to a remote API in App Service to test CORS functionality. Code forthe browser app is foundin the repository's _wwwroot_ directory.
74
+
1. Navigate 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.
77
75
78
-
1. To stop ASP.NET Core at any time, press `Ctrl+C` in the terminal.
76
+
1. To stop ASP.NET Core at any time, select**Ctrl+C**in the terminal.
@@ -128,13 +126,13 @@ In this step, you deploy your .NET Core application to App Service.
128
126
remote: Deployment successful.
129
127
To https://<app_name>.scm.azurewebsites.net/<app_name>.git
130
128
* [new branch] master -> master
131
-
</pre>
129
+
```
132
130
133
131
### Browse to the Azure app
134
132
135
-
1. Navigate to `http://<app_name>.azurewebsites.net/swagger` in a browser and play with the Swagger UI.
133
+
1. Navigate to `http://<app_name>.azurewebsites.net/swagger`in a browser and view the Swagger UI.
136
134
137
-
135
+
138
136
139
137
1. Navigate to `http://<app_name>.azurewebsites.net/swagger/v1/swagger.json` to see the _swagger.json_ for your deployed API.
140
138
@@ -144,41 +142,41 @@ In this step, you deploy your .NET Core application to App Service.
144
142
145
143
Next, you enable the built-in CORS support in App Service for your API.
146
144
147
-
### Test CORS in sample app
145
+
### Test CORS in the sample app
148
146
149
147
1. In your local repository, open _wwwroot/index.html_.
150
148
151
-
1. In Line 51, set the `apiEndpoint` variable to the URL of your deployed API (`http://<app_name>.azurewebsites.net`). Replace _\<appname>_ with your app name in App Service.
149
+
1. 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 in App Service.
152
150
153
151
1. In your local terminal window, run the sample app again.
154
152
155
153
```bash
156
154
dotnet run
157
155
```
158
156
159
-
1. Navigate 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`.
157
+
1. Navigate 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`.
160
158
161
-
159
+
162
160
163
-
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, the fact that your REST API the App Service app is not sending the `Access-Control-Allow-Origin` header, the browser has prevented cross-domain content from loading.
161
+
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.
164
162
165
-
In production, your browser app would have a public URL instead of the localhost URL, but the way to enable CORS to a localhost URL is the same as a public URL.
163
+
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.
166
164
167
165
### Enable CORS
168
166
169
-
In the Cloud Shell, enable CORS to your client's URL by using the [`az webapp cors add`](/cli/azure/webapp/cors#az-webapp-cors-add) command. Replace the _<app-name>_ placeholder.
167
+
In Cloud Shell, enable CORS to your client's URL by using the [`az webapp cors add`](/cli/azure/webapp/cors#az-webapp-cors-add) command. Replace the _<app-name>_ placeholder.
170
168
171
169
```azurecli-interactive
172
170
az webapp cors add --resource-group myResourceGroup --name <app-name> --allowed-origins 'http://localhost:5000'
173
171
```
174
172
175
-
You can add multiple allowed origins by running the command multiple times or by adding a comma-separate list in`--allowed-origins`. To allow all origins, use `--allowed-origins '*'`.
173
+
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 '*'`.
176
174
177
175
### Test CORS again
178
176
179
177
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.
182
180
183
181
Congratulations, you're running an API in Azure App Service with CORS support.
184
182
@@ -190,34 +188,34 @@ Congratulations, you're running an API in Azure App Service with CORS support.
190
188
191
189
#### App Service CORS vs. your CORS
192
190
193
-
You can use your own CORS utilities instead of App Service CORS for more flexibility. For example, you may want to specify different allowed origins for different routes or methods. Since App Service CORS lets you specify one set of accepted origins for all API routes and methods, you would want to use your own CORS code. See how ASP.NET Core does it at [Enabling Cross-Origin Requests (CORS)](/aspnet/core/security/cors).
191
+
You can use your own CORS utilities instead of App Service CORS for more flexibility. For example, you might want to specify different allowed origins for different routes or methods. Since App Service CORS lets you specify only one set of accepted origins for all API routes and methods, you would want to use your own CORS code. See how CORS is enabled in ASP.NET Core at [Enable CORS](/aspnet/core/security/cors).
194
192
195
-
The built-in App Service CORS feature does not have options to allow only specific HTTP methods or verbs for each origin that you specify. It will automatically allow all methods and headers for each origin defined. This behavior is similar to [ASP.NET Core CORS](/aspnet/core/security/cors) policies when you use the options `.AllowAnyHeader()` and `.AllowAnyMethod()` in the code.
193
+
The built-in App Service CORS feature doesn't have options to allow only specific HTTP methods or verbs foreach origin that you specify. It will automatically allow all methods and headers for each origin defined. This behavior is similar to [ASP.NET Core CORS](/aspnet/core/security/cors) policies when you use the options `.AllowAnyHeader()` and `.AllowAnyMethod()`in the code.
196
194
197
195
> [!NOTE]
198
-
> Don't try to use App Service CORS and your own CORS code together. When used together, App Service CORS takes precedence and your own CORS code has no effect.
196
+
> 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.
199
197
>
200
198
>
201
199
202
200
#### How do I set allowed origins to a wildcard subdomain?
203
201
204
-
A wildcard subdomain like `*.contoso.com` is more restrictive than the wildcard origin `*`. However, 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 doit using the Azure CLI, like so:
202
+
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 Azure CLI, like so:
205
203
206
204
```azurecli-interactive
207
205
az webapp cors add --resource-group <group-name> --name <app-name> --allowed-origins 'https://*.contoso.com'
208
206
```
209
207
210
208
#### How do I enable the ACCESS-CONTROL-ALLOW-CREDENTIALS header on the response?
211
209
212
-
If your app requires credentials such as cookies or authentication tokens to be sent, the browser may require the `ACCESS-CONTROL-ALLOW-CREDENTIALS` header on the response. To enable this in App Service, set`properties.cors.supportCredentials` to `true`.
210
+
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`:
213
211
214
212
```azurecli-interactive
215
213
az resource update --name web --resource-group <group-name> \
This operation is not allowed when allowed origins include the wildcard origin `'*'`. Specifying `AllowAnyOrigin` and `AllowCredentials`is an insecure configuration and can result in cross-site request forgery. To allow credentials, try replacing the wildcard origin with [wildcard subdomains](#how-do-i-set-allowed-origins-to-a-wildcard-subdomain).
218
+
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](#how-do-i-set-allowed-origins-to-a-wildcard-subdomain).
1. Push to the Azure remote to deploy your app with the following command. When Git Credential Manager prompts you for credentials, make sure you enter the credentials you created in **Configure a deployment user**, not the credentials you use to sign in to the Azure portal.
25
+
1. Push to the Azure remote to deploy your app with the following command. When Git Credential Manager prompts you for credentials, make sure you enter the credentials you created in **Configure local git deployment**, not the credentials you use to sign in to the Azure portal.
26
26
27
27
```bash
28
28
git push azure main
29
29
```
30
30
31
-
This command may take a few minutes to run. While running, it displays information similar to the following example:
31
+
This command might take a few minutes to run. While running, it displays information similar to the following example:
0 commit comments