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
* service-principal-on-prem and guidance changes
Co-authored-by: Scott Addie <[email protected]>
* Fix date
---------
Co-authored-by: Scott Addie <[email protected]>
# Authenticate .NET apps to Azure services during local development using service principals
@@ -26,252 +26,12 @@ When the app is registered in Azure, an application service principal is created
26
26
27
27
During local development, environment variables are set with the application service principal's identity. The Azure Identity library reads these environment variables to authenticate the app to the required Azure resources.
1. In the Azure portal, use the search bar to navigate to the **App registrations** page.
36
-
1. On the **App registrations** page, select **+ New registration**.
37
-
1. On the **Register an application** page:
38
-
- For the **Name** field, enter a descriptive value that includes the app name and the target environment.
39
-
- For the **Supported account types**, select **Accounts in this organizational directory only (Microsoft Customer Led only - Single tenant)**, or whichever option best fits your requirements.
40
-
1. Select **Register** to register your app and create the service principal.
41
-
42
-
:::image type="content" source="../../media/app-registration.png" alt-text="A screenshot showing how to create an app registration in the Azure portal.":::
43
-
44
-
1. On the **App registration** page for your app, copy the **Application (client) ID** and **Directory (tenant) ID** and paste them in a temporary location for later use in your app code configurations.
45
-
1. Select **Add a certificate or secret** to set up credentials for your app.
46
-
1. On the **Certificates & secrets** page, select **+ New client secret**.
47
-
1. In the **Add a client secret** flyout panel that opens:
48
-
- For the **Description**, enter a value of Current.
49
-
- For the **Expires** value, leave the default recommended value of 180 days.
50
-
- Select **Add** to add the secret.
51
-
1. On the **Certificates & secrets** page, copy the **Value** property of the client secret for use in a future step.
52
-
53
-
> [!NOTE]
54
-
> The client secret value is only displayed once after the app registration is created. You can add more client secrets without invalidating this client secret, but there's no way to display this value again.
55
-
56
-
### [Azure CLI](#tab/azure-cli)
57
-
58
-
Azure CLI commands can be run in the [Azure Cloud Shell](https://shell.azure.com) or on a workstation with the [Azure CLI installed](/cli/azure/install-azure-cli).
59
-
60
-
1. Use the [az ad sp create-for-rbac](/cli/azure/ad/sp#az-ad-sp-create-for-rbac) command to create a new app registration and service principal for the app.
61
-
62
-
```azurecli
63
-
az ad sp create-for-rbac --name <service-principal-name>
64
-
```
65
-
66
-
The output of this command resembles the following JSON:
67
-
68
-
```json
69
-
{
70
-
"appId": "00000000-0000-0000-0000-000000000000",
71
-
"displayName": "<service-principal-name>",
72
-
"password": "abcdefghijklmnopqrstuvwxyz",
73
-
"tenant": "11111111-1111-1111-1111-111111111111"
74
-
}
75
-
```
76
-
77
-
1. Copy this output into a temporary file in a text editor, as you'll need these values in a future step.
78
-
79
-
> [!NOTE]
80
-
> The client secret value is only displayed once after the app registration is created. You can add more client secrets without invalidating this client secret, but there's no way to display this value again.
81
-
82
-
---
83
-
84
-
## Create a Microsoft Entra group for local development
85
-
86
-
Create a Microsoft Entra group to encapsulate the roles (permissions) the app needs in local development rather than assigning the roles to individual service principal objects. This approach offers the following advantages:
87
-
88
-
- Every developer has the same roles assigned at the group level.
89
-
- If a new role is needed for the app, it only needs to be added to the group for the app.
90
-
- If a new developer joins the team, a new application service principal is created for the developer and added to the group, ensuring the developer has the right permissions to work on the app.
91
-
92
-
### [Azure portal](#tab/azure-portal)
93
-
94
-
1. Navigate to the **Microsoft Entra ID** overview page in the Azure portal.
95
-
1. Select **All groups** from the left-hand menu.
96
-
1. On the **Groups** page, select **New group**.
97
-
1. On the **New group** page, fill out the following form fields:
98
-
- **Group type**: Select **Security**.
99
-
- **Group name**: Enter a name for the group that includes a reference to the app or environment name.
100
-
- **Group description**: Enter a description that explains the purpose of the group.
101
-
102
-
:::image type="content" source="../../media/create-group.png" alt-text="A screenshot showing how to create a group in the Azure portal.":::
103
-
104
-
1. Select the **No members selected** link under **Members** to add members to the group.
105
-
1. In the flyout panel that opens, search for the service principal you created earlier and select it from the filtered results. Choose the **Select** button at the bottom of the panel to confirm your selection.
106
-
1. Select **Create** at the bottom of the **New group** page to create the group and return to the **All groups** page. If you don't see the new group listed, wait a moment and refresh the page.
107
-
108
-
### [Azure CLI](#tab/azure-cli)
109
-
110
-
1. Use the [az ad group create](/cli/azure/ad/group#az-ad-group-create) command to create groups in Microsoft Entra ID.
111
-
112
-
```azurecli
113
-
az ad group create \
114
-
--display-name <group-name> \
115
-
--mail-nickname <group-mail-nickname> \
116
-
--description <group-description>
117
-
```
118
-
119
-
The `--display-name` and `--mail-nickname` parameters are required. The name given to the group should be based on the name and environment of the app to indicate the group's purpose.
120
-
121
-
1. To add members to the group, you need the object ID of the application service principal, which is different than the application ID. Use the [az ad sp list](/cli/azure/ad/sp#az-ad-sp-list) command to list the available service principals:
The `--filter` parameter accepts OData-style filters and can be used to filter the list as shown. The `--query` parameter limits the output to only the columns of interest.
130
-
131
-
1. Use the [az ad group member add](/cli/azure/ad/group/member#az-ad-group-member-add) command to add members to the group:
132
-
133
-
```azurecli
134
-
az ad group member add \
135
-
--group <group-name> \
136
-
--member-id <object-id>
137
-
```
138
-
139
-
---
140
-
141
-
## Assign roles to the group
142
-
143
-
Next, determine what roles (permissions) your app needs on what resources and assign those roles to the Microsoft Entra group you created. Groups can be assigned a role at the resource, resource group, or subscription scope. This example shows how to assign roles at the resource group scope, since most apps group all their Azure resources into a single resource group.
144
-
145
-
### [Azure portal](#tab/azure-portal)
146
-
147
-
1. In the Azure portal, navigate to the **Overview** page of the resource group that contains your app.
148
-
1. Select **Access control (IAM)** from the left navigation.
149
-
1. On the **Access control (IAM)** page, select **+ Add** and then choose **Add role assignment** from the drop-down menu. The **Add role assignment** page provides several tabs to configure and assign roles.
150
-
1. On the **Role** tab, use the search box to locate the role you want to assign. Select the role, and then choose **Next**.
151
-
1. On the **Members** tab:
152
-
- For the **Assign access to** value, select **User, group, or service principal** .
153
-
- For the **Members** value, choose **+ Select members** to open the **Select members** flyout panel.
154
-
- Search for the Microsoft Entra group you created earlier and select it from the filtered results. Choose **Select** to select the group and close the flyout panel.
155
-
- Select **Review + assign** at the bottom of the **Members** tab.
156
-
157
-
:::image type="content" source="../../media/app-role-assignment.png" alt-text="A screenshot showing how to assign a role to the Microsoft Entra group.":::
158
-
159
-
1. On the **Review + assign** tab, select **Review + assign** at the bottom of the page.
160
-
161
-
### [Azure CLI](#tab/azure-cli)
162
-
163
-
1. Use the [az role definition list](/cli/azure/role/definition#az-role-definition-list) command to get the names of the roles that a service principal can be assigned to:
1. Use the [az role assignment create](/cli/azure/role/assignment#az-role-assignment-create) command to assign a role to an application service principal:
172
-
173
-
```azurecli
174
-
az role assignment create \
175
-
--assignee "<app-Id>" \
176
-
--role "<role-name>" \
177
-
--resource-group "<resource-group-name>"
178
-
```
179
-
180
-
For information on assigning permissions at the resource or subscription level using the Azure CLI, see [Assign Azure roles using the Azure CLI](/azure/role-based-access-control/role-assignments-cli).
181
-
182
-
---
183
-
184
-
## Set the app environment variables
185
-
186
-
At runtime, certain credentials from the [Azure Identity library](/dotnet/api/azure.identity?view=azure-dotnet&preserve-view=true), such as `DefaultAzureCredential`, `EnvironmentCredential`, and `ClientSecretCredential`, search for service principal information by convention in the environment variables. There are multiple ways to configure environment variables when working with .NET, depending on your tooling and environment.
187
-
188
-
Regardless of the approach you choose, configure the following environment variables for a service principal:
189
-
190
-
- `AZURE_CLIENT_ID`: Used to identify the registered app in Azure.
191
-
- `AZURE_TENANT_ID`: The ID of the Microsoft Entra tenant.
192
-
- `AZURE_CLIENT_SECRET`: The secret credential that was generated for the app.
193
-
194
-
### [Visual Studio](#tab/visual-studio)
195
-
196
-
In Visual Studio, environment variables can be set in the `launchsettings.json` file in the `Properties` folder of your project. These values are pulled in automatically when the app starts. However, these configurations don't travel with your app during deployment, so you need to set up environment variables on your target hosting environment.
In Visual Studio Code, environment variables can be set in the `launch.json` file of your project. These values are pulled in automatically when the app starts. However, these configurations don't travel with your app during deployment, so you need to set up environment variables on your target hosting environment.
228
-
229
-
```json
230
-
"configurations": [
231
-
{
232
-
"env": {
233
-
"ASPNETCORE_ENVIRONMENT": "Development",
234
-
"AZURE_CLIENT_ID": "<your-client-id>",
235
-
"AZURE_TENANT_ID":"<your-tenant-id>",
236
-
"AZURE_CLIENT_SECRET": "<your-client-secret>"
237
-
}
238
-
}
239
-
```
240
-
241
-
### [Windows](#tab/windows)
242
-
243
-
You can set environment variables for Windows from the command line. However, the values are accessible to all apps running on that operating system and could cause conflicts, so use caution with this approach. Environment variables can be set at the user or system level.
244
-
245
-
```bash
246
-
# Set user environment variables
247
-
setx ASPNETCORE_ENVIRONMENT "Development"
248
-
setx AZURE_CLIENT_ID "<your-client-id>"
249
-
setx AZURE_TENANT_ID "<your-tenant-id>"
250
-
setx AZURE_CLIENT_SECRET "<your-client-secret>"
251
-
252
-
# Set system environment variables - requires running as admin
0 commit comments