Skip to content

Commit a6fdffa

Browse files
v-regandownerv-regandowner
authored
Merge pull request #192973 from maud-lv/ml-sc-tuto
Create tutorial: connect a web app to App Configuration with Service Connector
2 parents 43f8e90 + f63d021 commit a6fdffa

File tree

2 files changed

+330
-0
lines changed

2 files changed

+330
-0
lines changed

‎articles/service-connector/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ items:
3131
href: tutorial-java-spring-mysql.md
3232
- name: Spring Cloud app with Kafka on Confluent Cloud
3333
href: tutorial-java-spring-confluent-kafka.md
34+
- name: Web app with App Configuration
35+
href: tutorial-connect-web-app-app-configuration.md
3436
- name: Concepts
3537
expanded: true
3638
items:

‎articles/service-connector/tutorial-connect-web-app-app-configuration.md

Lines changed: 328 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,328 @@
1+
---
2+
title: 'Tutorial: Connect a web app to Azure App Configuration with Service Connector'
3+
description: Learn how you can connect an ASP.NET Core application hosted in Azure Web Apps to App Configuration using Service Connector'
4+
author: maud-lv
5+
ms.author: malev
6+
ms.service: service-connector
7+
ms.topic: tutorial
8+
ms.date: 05/01/2022
9+
---
10+
11+
# Tutorial: Connect a web app to Azure App Configuration with Service Connector
12+
13+
Learn how to connect an ASP.NET Core app running on Azure App Service, to Azure App Configuration, using one of the following methods:
14+
15+
- System-assigned managed identity (SMI)
16+
- User-assigned managed identity (UMI)
17+
- Service principal
18+
- Connection string
19+
20+
In this tutorial, use the Azure CLI to complete the following tasks:
21+
22+
> [!div class="checklist"]
23+
> - Set up Azure resources
24+
> - Create a connection between a web app and App Configuration
25+
> - Build and deploy your app to Azure App Service
26+
27+
## Prerequisites
28+
29+
- An Azure account with an active subscription. Your access role within the subscription must be "Contributor" or "Owner". [Create an account for free](https://azure.microsoft.com/free/dotnet).
30+
- The Azure CLI. You can use it in [Azure Cloud Shell](https://shell.azure.com/) or [install it locally](/cli/azure/install-azure-cli).
31+
- [.NET SDK](https://dotnet.microsoft.com/download)
32+
- [Git](/devops/develop/git/install-and-set-up-git)
33+
34+
## Sign in to Azure
35+
36+
Sign in to the Azure portal at [https://portal.azure.com/](https://portal.azure.com/) with your Azure account.
37+
38+
## Set up Azure resources
39+
40+
Start by creating your Azure resources.
41+
42+
1. Clone the following sample repo:
43+
44+
```bash
45+
git clone https://github.com/Azure-Samples/serviceconnector-webapp-appconfig-dotnet.git
46+
```
47+
48+
1. Deploy the web app to Azure
49+
50+
Run `az login` to sign in to and follow these steps to create an App Service and deploy the sample app. Make sure you have the Subscription Contributor role.
51+
52+
### [SMI](#tab/smi)
53+
54+
Create an app service and deploy the sample app that uses system-assigned managed identity to interact with App Config.
55+
56+
```azurecli
57+
# Change directory to the SMI sample
58+
cd serviceconnector-webapp-appconfig-dotnet\system-managed-identity
59+
60+
# Create a web app
61+
62+
LOCATION='eastus'
63+
RESOURCE_GROUP_NAME='service-connector-tutorial-rg'
64+
APP_SERVICE_NAME='webapp-appconfig-smi'
65+
66+
az webapp up --location $LOCATION --resource-group $RESOURCE_GROUP_NAME --name $APP_SERVICE_NAME
67+
```
68+
69+
| Parameter | Description | Example |
70+
|--------------|-----------------------------------------------------------------------------------------|----------|
71+
| Location | Choose a location near you. Use `az account list-locations --output table` to list locations. | *eastus* |
72+
| Resource group name | You'll use this resource group to organize all the Azure resources needed to complete this tutorial. | *service-connector-tutorial-rg* |
73+
| App service name | The app service name is used as the name of the resource in Azure and to form the fully qualified domain name for your app, in the form of the server endpoint `https://<app-service-name>.azurewebsites.com`. This name must be unique across all Azure and the only allowed characters are `A`-`Z`, `0`-`9`, and `-`. | *webapp-appconfig-smi* |
74+
75+
### [UMI](#tab/umi)
76+
77+
Create an app service and deploy the sample app that uses user-assigned managed identity to interact with App Config.
78+
79+
```azurecli
80+
# Change directory to the UMI sample
81+
cd serviceconnector-webapp-appconfig-dotnet\user-assigned-managed-identity
82+
83+
# Create a web app
84+
85+
LOCATION='eastus'
86+
RESOURCE_GROUP_NAME='service-connector-tutorial-rg'
87+
APP_SERVICE_NAME='webapp-appconfig-umi'
88+
89+
az webapp up --location $LOCATION --resource-group $RESOURCE_GROUP_NAME --name $APP_SERVICE_NAME
90+
```
91+
92+
| Parameter | Description | Example |
93+
|--------------|-----------------------------------------------------------------------------------------|----------|
94+
| Location | Choose a location near you. Use `az account list-locations --output table` to list locations. | *eastus* |
95+
| Resource group name | You'll use this resource group to organize all the Azure resources needed to complete this tutorial. | *service-connector-tutorial-rg* |
96+
| App service name | The app service name is used as the name of the resource in Azure and to form the fully qualified domain name for your app, in the form of the server endpoint `https://<app-service-name>.azurewebsites.com`. This name must be unique across all Azure and the only allowed characters are `A`-`Z`, `0`-`9`, and `-`. | *webapp-appconfig-umi* |
97+
98+
Create a user-assigned managed identity. Save the output into a temporary notepad.
99+
```azurecli
100+
az identity create --resource-group $RESOURCE_GROUP_NAME -n "myIdentity"
101+
```
102+
103+
### [Service principal](#tab/serviceprincipal)
104+
105+
Create an app service and deploy the sample app that uses service principal to interact with App Config.
106+
107+
```azurecli
108+
# Change directory to the service principal sample
109+
cd serviceconnector-webapp-appconfig-dotnet\service-principal
110+
111+
# Create a web app
112+
113+
LOCATION='eastus'
114+
RESOURCE_GROUP_NAME='service-connector-tutorial-rg'
115+
APP_SERVICE_NAME='webapp-appconfig-sp'
116+
117+
az webapp up --location $LOCATION --resource-group $RESOURCE_GROUP_NAME --name $APP_SERVICE_NAME
118+
```
119+
120+
| Parameter | Description | Example |
121+
|--------------|-----------------------------------------------------------------------------------------|----------|
122+
| Location | Choose a location near you. Use `az account list-locations --output table` to list locations. | *eastus* |
123+
| Resource group name | You'll use this resource group to organize all the Azure resources needed to complete this tutorial. | *service-connector-tutorial-rg* |
124+
| App service name | The app service name is used as the name of the resource in Azure and to form the fully qualified domain name for your app, in the form of the server endpoint `https://<app-service-name>.azurewebsites.com`. This name must be unique across all Azure and the only allowed characters are `A`-`Z`, `0`-`9`, and `-`. | *webapp-appconfig-sp* |
125+
126+
Create a service principal, make sure to replace the `yourSubscriptionID` with your actual subscription ID. Save the output into a temporary notepad.
127+
128+
```azurecli
129+
az ad sp create-for-rbac --name myServicePrincipal --role Contributor --scopes /subscriptions/{yourSubscriptionID}/resourceGroups/$RESOURCE_GROUP_NAME
130+
```
131+
132+
### [Connection string](#tab/connectionstring)
133+
134+
Create an app service and deploy the sample app that uses connection string to interact with App Config.
135+
136+
```azurecli
137+
# Change directory to the service principal sample
138+
cd serviceconnector-webapp-appconfig-dotnet\connection-string
139+
140+
# Create a web app
141+
142+
LOCATION='eastus'
143+
RESOURCE_GROUP_NAME='service-connector-tutorial-rg'
144+
APP_SERVICE_NAME='webapp-appconfig-cs'
145+
146+
az webapp up --location $LOCATION --resource-group $RESOURCE_GROUP_NAME --name $APP_SERVICE_NAME
147+
```
148+
149+
| Parameter | Description | Example |
150+
|--------------|-----------------------------------------------------------------------------------------|----------|
151+
| Location | Choose a location near you. Use `az account list-locations --output table` to list locations. | *eastus* |
152+
| Resource group name | You'll use this resource group to organize all the Azure resources needed to complete this tutorial. | *service-connector-tutorial-rg* |
153+
| App service name | The app service name is used as the name of the resource in Azure and to form the fully qualified domain name for your app, in the form of the server endpoint `https://<app-service-name>.azurewebsites.com`. This name must be unique across all Azure and the only allowed characters are `A`-`Z`, `0`-`9`, and `-`. | *webapp-appconfig-cs* |
154+
155+
---
156+
157+
1. Create an Azure App Configuration store
158+
159+
```azurecli
160+
APP_CONFIG_NAME='my-app-config'
161+
162+
az appconfig create -g $RESOURCE_GROUP_NAME -n $APP_CONFIG_NAME --sku Free -l eastus
163+
```
164+
165+
1. Import the test configuration file to Azure App Configuration.
166+
167+
### [SMI](#tab/smi)
168+
169+
Import the test configuration file to Azure App Configuration using a system-assigned managed identity.
170+
171+
1. Cd into the folder `ServiceConnectorSample`
172+
1. Import the [./sampleconfigs.json](https://github.com/Azure-Samples/serviceconnector-webapp-appconfig-dotnet/blob/main/system-managed-identity/ServiceConnectorSample/sampleconfigs.json) test configuration file into the App Configuration store. If you're using Cloud Shell, upload [sampleconfigs.json](../cloud-shell/persisting-shell-storage.md) before running the command.
173+
174+
```azurecli
175+
az appconfig kv import -n $APP_CONFIG_NAME --source file --format json --path ./sampleconfigs.json --separator : --yes
176+
```
177+
178+
### [UMI](#tab/umi)
179+
180+
Import the test configuration file to Azure App Configuration using a user-assigned managed identity.
181+
182+
1. Cd into the folder `ServiceConnectorSample`
183+
1. Import the [./sampleconfigs.json](https://github.com/Azure-Samples/serviceconnector-webapp-appconfig-dotnet/blob/main/user-assigned-managed-identity/ServiceConnectorSample/sampleconfigs.json) test configuration file into the App Configuration store. If you're using Cloud Shell, upload [sampleconfigs.json](../cloud-shell/persisting-shell-storage.md) before running the command.
184+
185+
```azurecli
186+
az appconfig kv import -n $APP_CONFIG_NAME --source file --format json --path ./sampleconfigs.json --separator : --yes
187+
```
188+
189+
### [Service principal](#tab/serviceprincipal)
190+
191+
Import the test configuration file to Azure App Configuration using service principal.
192+
193+
1. Cd into the folder `ServiceConnectorSample`
194+
1. Import the [./sampleconfigs.json](https://github.com/Azure-Samples/serviceconnector-webapp-appconfig-dotnet/blob/main/service-principal/ServiceConnectorSample/sampleconfigs.json) test configuration file into the App Configuration store. If you're using Cloud Shell, upload [sampleconfigs.json](../cloud-shell/persisting-shell-storage.md) before running the command.
195+
196+
```azurecli
197+
az appconfig kv import -n $APP_CONFIG_NAME --source file --format json --path ./sampleconfigs.json --separator : --yes
198+
```
199+
200+
### [Connection string](#tab/connectionstring)
201+
202+
Import the test configuration file to Azure App Configuration using a connection string.
203+
204+
1. Cd into the folder `ServiceConnectorSample`
205+
1. Import the [./sampleconfigs.json](https://github.com/Azure-Samples/serviceconnector-webapp-appconfig-dotnet/blob/main/connection-string/ServiceConnectorSample/sampleconfigs.json) test configuration file into the App Configuration store. If you're using Cloud Shell, upload [sampleconfigs.json](../cloud-shell/persisting-shell-storage.md) before running the command.
206+
207+
```azurecli
208+
az appconfig kv import -n $APP_CONFIG_NAME --source file --format json --path ./sampleconfigs.json --separator : --yes
209+
```
210+
211+
---
212+
213+
## Connect the web app to App Configuration
214+
215+
Create a connection between your web application and your App Configuration store.
216+
217+
### [SMI](#tab/smi)
218+
219+
Create a connection between your web application and your App Configuration store, using a system-assigned managed identity authentication. This connection is done through Service Connector.
220+
221+
```azurecli
222+
az webapp connection create appconfig -g $RESOURCE_GROUP_NAME -n $APP_SERVICE_NAME --app-config $APP_CONFIG_NAME --tg $RESOURCE_GROUP_NAME --connection "app_config_smi" --system-identity
223+
```
224+
225+
`system-identity` refers to the system-assigned managed identity (SMI) authentication type. Service Connector also supports the following authentications: user-assigned managed identity (UMI), connection string (secret) and service principal.
226+
227+
### [UMI](#tab/umi)
228+
229+
Create a connection between your web application and your App Configuration store, using a user-assigned managed identity authentication. This connection is done through Service Connector.
230+
231+
```azurecli
232+
az webapp connection create appconfig -g $RESOURCE_GROUP_NAME -n $APP_SERVICE_NAME --app-config $APP_CONFIG_NAME --tg $RESOURCE_GROUP_NAME --connection "app_config_umi" --user-identity client-id=<myIdentityClientId> subs-id=<myTestSubsId>
233+
```
234+
235+
`user-identity` refers to the user-assigned managed identity authentication type. Service Connector also supports the following authentications: system-assigned managed identity, connection string (secret) and service principal.
236+
237+
There are two ways you can find the `client-id`:
238+
239+
- In the Azure CLI, enter `az identity show -n "myIdentity" -g $RESOURCE_GROUP_NAME --query 'clientId'`.
240+
- In the Azure portal, open the Managed Identity that was created earlier and in **Overview**, get the value under **Client ID**.
241+
242+
### [Service principal](#tab/serviceprincipal)
243+
244+
Create a connection between your web application and your App Configuration store, using a service principal. This is done through Service Connector.
245+
246+
```azurecli
247+
az webapp connection create appconfig -g $RESOURCE_GROUP_NAME -n $APP_SERVICE_NAME --app-config $APP_CONFIG_NAME --tg $RESOURCE_GROUP_NAME --connection "app_config_sp" --service-principal client-id=<mySPClientId> secret=<mySPSecret>
248+
```
249+
250+
`service-principal` refers to the service principal authentication type. Service Connector also supports the following authentications: system-assigned managed identity (UMI), user-assigned managed identity (UMI) and connection string (secret).
251+
252+
### [Connection string](#tab/connectionstring)
253+
254+
Create a connection between your web application and your App Configuration store, using a connection string. This connection is done through Service Connector.
255+
256+
```azurecli
257+
az webapp connection create appconfig -g $RESOURCE_GROUP_NAME -n $APP_SERVICE_NAME --app-config $APP_CONFIG_NAME --tg $RESOURCE_GROUP_NAME --connection "app_config_cs" --secret
258+
```
259+
260+
`secret` refers to the connection-string authentication type. Service Connector also supports the following authentications: system-assigned managed identity, user-assigned managed identity, and service principal.
261+
262+
---
263+
264+
## Validate the connection
265+
266+
1. To check if the connection is working, navigate to your web app at `https://<myWebAppName>.azurewebsites.net/` from your browser. Once the website is up, you'll see it displaying "Hello. Your Azure WebApp is connected to App Configuration by ServiceConnector now".
267+
268+
## How it works
269+
270+
Find below what Service Connector manages behind the scenes for each authentication type.
271+
272+
### [SMI](#tab/smi)
273+
274+
Service Connector manages the connection configuration for you:
275+
276+
- Set up the web app's `AZURE_APPCONFIGURATION_ENDPOINT` to let the application access it and get the App Configuration endpoint. Access [sample code](https://github.com/Azure-Samples/serviceconnector-webapp-appconfig-dotnet/blob/main/system-managed-identity/ServiceConnectorSample/Program.cs#L10).
277+
- Activate the web app's system-assigned managed authentication and grant App Configuration a Data Reader role to let the application authenticate to the App Configuration using DefaultAzureCredential from Azure.Identity. Access [sample code](https://github.com/Azure-Samples/serviceconnector-webapp-appconfig-dotnet/blob/main/system-managed-identity/ServiceConnectorSample/Program.cs#L13).
278+
279+
### [UMI](#tab/umi)
280+
281+
Service Connector manages the connection configuration for you:
282+
283+
- Set up the web app's `AZURE_APPCONFIGURATION_ENDPOINT`, `AZURE_APPCONFIGURATION_CLIENTID`
284+
to let the application access it and get app configuration endpoint in [code](https://github.com/Azure-Samples/serviceconnector-webapp-appconfig-dotnet/blob/main/user-assigned-managed-identity/ServiceConnectorSample/Program.cs#L10-L12);
285+
- Activate the web app's user-assigned managed authentication and grant App Configuration a Data Reader role to let the application authenticate to the App Configuration using DefaultAzureCredential from Azure.Identity. Access [sample code](https://github.com/Azure-Samples/serviceconnector-webapp-appconfig-dotnet/blob/main/user-assigned-managed-identity/ServiceConnectorSample/Program.cs#L16).
286+
287+
### [Service principal](#tab/serviceprincipal)
288+
289+
Service Connector manages the connection configuration for you:
290+
291+
- Set up the web app's `AZURE_APPCONFIGURATION_ENDPOINT` to let the application access it and get the App Configuration endpoint. Access [sample code](https://github.com/Azure-Samples/serviceconnector-webapp-appconfig-dotnet/blob/main/service-principal/ServiceConnectorSample/Program.cs#L10).
292+
- save service principal credential to WebApp AppSettings `AZURE_APPCONFIGURATION_CLIENTID`. `AZURE_APPCONFIGURATION_TENANTID`, `AZURE_APPCONFIGURATION_CLIENTSECRET` and grant App Configuration Data Reader role to the service principal, so the application could be authenticated to the App Configuration in [code](https://github.com/Azure-Samples/serviceconnector-webapp-appconfig-dotnet/blob/main/service-principal/ServiceConnectorSample/Program.cs#L11-L18), by using `ClientSecretCredential` from [Azure.Identity](https://azuresdkdocs.blob.core.windows.net/$web/dotnet/Azure.Identity/1.0.0/api/index.html).
293+
294+
### [Connection string](#tab/connectionstring)
295+
296+
Service Connector manages the connection configuration for you:
297+
298+
- Set up the web app's `AZURE_APPCONFIGURATION_CONNECTIONSTRING` to let the application access it and get the App Configuration connection string. Access [sample code](https://github.com/Azure-Samples/serviceconnector-webapp-appconfig-dotnet/blob/main/connection-string/Microsoft.Azure.ServiceConnector.Sample/Program.cs#L9-L12).
299+
- Activate the web app's system-assigned managed authentication and grant App Configuration a Data Reader role to let the application authenticate to the App Configuration using DefaultAzureCredential from Azure.Identity. Access [sample code](https://github.com/Azure-Samples/serviceconnector-webapp-appconfig-dotnet/blob/main/connection-string/Microsoft.Azure.ServiceConnector.Sample/Program.cs#L43).
300+
301+
---
302+
303+
For more information, go to [Service Connector internals.](concept-service-connector-internals.md)
304+
305+
## Test (optional)
306+
307+
Optionally, do the following tests:
308+
309+
1. Update the value of the key `SampleApplication:Settings:Messages` in the App Configuration Store.
310+
311+
```azurecli
312+
az appconfig kv set -n <myAppConfigStoreName> --key SampleApplication:Settings:Messages --value hello --yes
313+
```
314+
315+
1. Navigate to your Azure web app by going to `https://<myWebAppName>.azurewebsites.net/` and refresh the page. You'll see that the message is updated to "hello".
316+
317+
## Cleanup
318+
319+
Once you're done, delete the Azure resources you created.
320+
321+
`az group delete -n <myResourceGroupName> --yes`
322+
323+
## Next steps
324+
325+
Follow the tutorials listed below to learn more about Service Connector.
326+
327+
> [!div class="nextstepaction"]
328+
> [Learn about Service Connector concepts](./concept-service-connector-internals.md)

0 commit comments

Comments
 (0)