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
title: Authentication and authorization for Azure Static Web Apps
3
-
description: Learn to use different authorization providers to secure your static app.
2
+
title: Authenticate and authorize Static Web Apps
3
+
description: Learn to use different authorization providers to secure your Azure Static Web Apps.
4
4
services: static-web-apps
5
+
ms.custom: engagement-fy23
5
6
author: craigshoemaker
6
7
ms.service: static-web-apps
7
-
ms.topic: conceptual
8
-
ms.date: 10/08/2021
8
+
ms.topic: how-to
9
+
ms.date: 12/22/2022
9
10
ms.author: cshoe
10
11
---
11
12
12
-
# Authentication and authorization for Azure Static Web Apps
13
+
# Authenticate and authorize Static Web Apps
13
14
14
-
Azure Static Web Apps provides a streamlined authentication experience. By default, you have access to a series of pre-configured providers, or the option to [register a custom provider](./authentication-custom.md).
15
+
Azure Static Web Apps provides a streamlined authentication experience, where no other actions or configurations are required to use GitHub, Twitter, and Azure Active Directory (Azure AD) for authentication.
15
16
16
-
- Any user can authenticate with an enabled provider.
17
-
- Once logged in, users belong to the `anonymous` and `authenticated` roles by default.
18
-
- Authorized users gain access to restricted [routes](configuration.md#routes) by rules defined in the [staticwebapp.config.json file](./configuration.md).
19
-
- Users are assigned custom roles using the built-in [invitations](#invitations) system.
20
-
- Users can be programmatically assigned custom roles at login by an API function.
21
-
- All authentication providers are enabled by default.
22
-
- To restrict an authentication provider, [block access](#block-an-authentication-provider) with a custom route rule. Configuring a custom provider also disables pre-configured providers.
23
-
- Pre-configured providers include:
24
-
- Azure Active Directory<sup>1</sup>
25
-
- GitHub
26
-
- Twitter
17
+
In this article, learn about default behavior, how to set up sign-in and sign-out, how to block an authentication provider, and more.
18
+
19
+
You can [register a custom provider](./authentication-custom.md), which disables all pre-configured providers.
27
20
28
-
<sup>1</sup> The preconfigured Azure Active Directory provider allows any Microsoft Account to sign in. To restrict login to a specific Active Directory tenant, configure a [custom Azure Active Directory provider](authentication-custom.md?tabs=aad).
21
+
## Prerequisites
29
22
30
-
The subjects of authentication and authorization significantly overlap with routing concepts, which are detailed in the [application configuration guide](configuration.md#routes).
23
+
Be aware of the following defaults and resources for authentication and authorization with Azure Static Web Apps.
31
24
32
-
## System folder
25
+
**Defaults:**
26
+
- Any user can authenticate with a pre-configured provider
27
+
- GitHub
28
+
- Twitter
29
+
- Azure Active Directory (Azure AD)
30
+
- To restrict an authentication provider, [block access](#block-an-authentication-provider) with a custom route rule
31
+
- After sign-in, users belong to the `anonymous` and `authenticated` roles. For more information about roles, see [Manage roles](authentication-custom.md#manage-roles)
33
32
34
-
Azure Static Web Apps uses the `/.auth` system folder to provide access to authorization-related APIs. Rather than exposing any of the routes under the `/.auth` folder directly to end users, consider creating [routing rules](configuration.md#routes) to create friendly URLs.
33
+
**Resources:**
34
+
- Define rules in the [staticwebapp.config.json file](./configuration.md) for authorized users to gain access to restricted [routes](configuration.md#routes)
35
+
- Assign users custom roles using the built-in [invitations system](authentication-custom.md#manage-roles)
36
+
- Programmatically assign users custom roles at sign-in with an [API function](apis-overview.md)
37
+
- Understand that authentication and authorization significantly overlap with routing concepts, which are detailed in the [Application configuration guide](configuration.md)
38
+
- Restrict sign-in to a specific Azure AD tenant by [configuring a custom Azure AD provider](authentication-custom.md?tabs=aad). The pre-configured Azure AD provider allows any Microsoft account to sign in.
39
+
## Set up sign-in
35
40
36
-
## Login
41
+
Azure Static Web Apps uses the `/.auth` system folder to provide access to authorization-related APIs. Rather than expose any of the routes under the `/.auth` folder directly to end users, create [routing rules](configuration.md#routes) for friendly URLs.
37
42
38
43
Use the following table to find the provider-specific route.
For example, to log in with GitHub you could include a link like the following snippet:
51
+
For example, to sign in with GitHub, you could include something similar to the following link.
47
52
48
53
```html
49
54
<ahref="/.auth/login/github">Login</a>
50
55
```
51
56
52
-
If you chose to support more than one provider, then you need to expose a provider-specific link for each on your website.
53
-
54
-
You can use a [route rule](./configuration.md#routes) to map a default provider to a friendly route like _/login_.
57
+
If you chose to support more than one provider, expose a provider-specific link for each on your website.
58
+
Use a [route rule](./configuration.md#routes) to map a default provider to a friendly route like _/login_.
55
59
56
60
```json
57
61
{
@@ -60,19 +64,15 @@ You can use a [route rule](./configuration.md#routes) to map a default provider
60
64
}
61
65
```
62
66
63
-
### Post login redirect
64
-
65
-
If you want a user to return to a specific page after login, provide a full qualified URL in `post_login_redirect_uri` query string parameter.
67
+
### Set up post-sign-in redirect
66
68
67
-
For example:
69
+
Return a user to a specific page after they sign in by providing a fully qualified URL in the `post_login_redirect_uri` query string parameter, like in the following example.
Additionally, you can redirect unauthenticated users back to the referring page after they log in. To configure this behavior, create a [response override](configuration.md#response-overrides) rule that sets `post_login_redirect_uri` to `.referrer`.
74
-
75
-
For example:
75
+
You can also redirect unauthenticated users back to the referring page after they sign in. To configure this behavior, create a [response override](configuration.md#response-overrides) rule that sets `post_login_redirect_uri` to `.referrer`, like in the following example.
76
76
77
77
```json
78
78
{
@@ -85,15 +85,15 @@ For example:
85
85
}
86
86
```
87
87
88
-
## Logout
88
+
## Set up sign-out
89
89
90
-
The `/.auth/logout` route logs users out from the website. You can add a link to your site navigation to allow the user to log out as shown in the following example.
90
+
The `/.auth/logout` route signs users out from the website. You can add a link to your site navigation to allow the user to sign out, like in the following example.
91
91
92
92
```html
93
93
<ahref="/.auth/logout">Log out</a>
94
94
```
95
95
96
-
You can use a [route rule](./configuration.md#routes) to map a friendly route like _/logout_.
96
+
Use a [route rule](./configuration.md#routes) to map a friendly route like _/logout_.
97
97
98
98
```json
99
99
{
@@ -102,13 +102,13 @@ You can use a [route rule](./configuration.md#routes) to map a friendly route li
102
102
}
103
103
```
104
104
105
-
### Post logout redirect
105
+
### Set up post-sign-out redirect
106
106
107
-
If you want a user to return to a specific page after logout, provide a URL in `post_logout_redirect_uri` query string parameter.
107
+
To return a user to a specific page after they sign out, provide a URL in `post_logout_redirect_uri` query string parameter.
108
108
109
109
## Block an authentication provider
110
110
111
-
You may want to restrict your app from using an authentication provider. For instance, your app may want to standardize only on [providers that expose email addresses](#provider-user-details).
111
+
You may want to restrict your app from using an authentication provider, since all authentication providers are enabled. For instance, your app may want to standardize only on [providers that expose email addresses](authentication-custom.md#create-an-invitation).
112
112
113
113
To block a provider, you can create [route rules](configuration.md#routes) to return a 404 status code for requests to the blocked provider-specific route. For example, to restrict Twitter as provider, add the following route rule.
114
114
@@ -119,213 +119,36 @@ To block a provider, you can create [route rules](configuration.md#routes) to re
119
119
}
120
120
```
121
121
122
-
## Roles
123
-
124
-
Every user who accesses a static web app belongs to one or more roles. There are two built-in roles that users can belong to:
125
-
126
-
-**anonymous**: All users automatically belong to the _anonymous_ role.
127
-
-**authenticated**: All users who are logged in belong to the _authenticated_ role.
128
-
129
-
Beyond the built-in roles, you can assign custom roles to users, and reference them in the _staticwebapp.config.json_ file.
130
-
131
-
## Role management
132
-
133
-
# [Invitations](#tab/invitations)
134
-
135
-
### Add a user to a role
136
-
137
-
To add a user to a role, you generate invitations that allow you to associate users to specific roles. Roles are defined and maintained in the _staticwebapp.config.json_ file.
138
-
139
-
<aname="invitations"id="invitations"></a>
140
-
141
-
#### Create an invitation
142
-
143
-
Invitations are specific to individual authorization-providers, so consider the needs of your app as you select which providers to support. Some providers expose a user's email address, while others only provide the site's username.
1. Go to a Static Web Apps resource in the [Azure portal](https://portal.azure.com).
154
-
1. Under _Settings_, select **Role Management**.
155
-
2. Select **Invite**.
156
-
3. Select an _Authorization provider_ from the list of options.
157
-
4. Add either the username or email address of the recipient in the _Invitee details_ box.
158
-
- For GitHub and Twitter, you enter the username. For all others, enter the recipient's email address.
159
-
5. Select the domain of your static site from the _Domain_ drop-down.
160
-
- The domain you select is the domain that appears in the invitation. If you have a custom domain associated with your site, you probably want to choose the custom domain.
161
-
6. Add a comma-separated list of role names in the _Role_ box.
162
-
7. Enter the maximum number of hours you want the invitation to remain valid.
163
-
- The maximum possible limit is 168 hours, which is 7 days.
164
-
8. Select **Generate**.
165
-
9. Copy the link from the _Invite link_ box.
166
-
10. Email the invitation link to the person you're granting access to your app.
167
-
168
-
When the user selects the link in the invitation, they're prompted to log in with their corresponding account. Once successfully logged-in, the user is associated with the selected roles.
169
-
170
-
> [!CAUTION]
171
-
> Make sure your route rules don't conflict with your selected authentication providers. Blocking a provider with a route rule would prevent users from accepting invitations.
172
-
173
-
### Update role assignments
174
-
175
-
1. Go to a Static Web Apps resource in the [Azure portal](https://portal.azure.com).
176
-
1. Under _Settings_, select **Role Management**.
177
-
2. Select the user in the list.
178
-
3. Edit the list of roles in the _Role_ box.
179
-
4. Select **Update**.
180
-
181
-
### Remove user
182
-
183
-
1. Go to a Static Web Apps resource in the [Azure portal](https://portal.azure.com).
184
-
1. Under _Settings_, select **Role Management**.
185
-
1. Locate the user in the list.
186
-
1. Check the checkbox on the user's row.
187
-
2. Select **Delete**.
188
-
189
-
As you remove a user, keep in mind the following items:
190
-
191
-
1. Removing a user invalidates their permissions.
192
-
1. Worldwide propagation may take a few minutes.
193
-
1. If the user is added back to the app, the [`userId` changes](user-information.md).
194
-
195
-
# [Function (preview)](#tab/function)
196
-
197
-
Instead of using the built-in invitations system, you can use a serverless function to programmatically assign roles to users when they log in.
198
-
199
-
To assign custom roles in a function, you can define an API function that is automatically called after each time a user successfully authenticates with an identity provider. The function is passed the user's information from the provider. It must return a list of custom roles that are assigned to the user.
200
-
201
-
Example uses of this function include:
202
-
203
-
- Query a database to determine which roles a user should be assigned
204
-
- Call the [Microsoft Graph API](https://developer.microsoft.com/graph) to determine a user's roles based on their Active Directory group membership
205
-
- Determine a user's roles based on claims returned by the identity provider
206
-
207
-
> [!NOTE]
208
-
> The ability to assign roles via a function is only available when [custom authentication](authentication-custom.md) is configured.
209
-
>
210
-
> When this feature is enabled, any roles assigned via the built-in invitations system are ignored.
122
+
## Remove personal data
211
123
212
-
### Configure a function for assigning roles
213
-
214
-
To configure Static Web Apps to use an API function as the role assignment function, add a `rolesSource` property to the `auth` section of your app's [configuration file](configuration.md). The value of the `rolesSource` property is the path to the API function.
215
-
216
-
```json
217
-
{
218
-
"auth": {
219
-
"rolesSource": "/api/GetRoles",
220
-
"identityProviders": {
221
-
// ...
222
-
}
223
-
}
224
-
}
225
-
```
226
-
227
-
> [!NOTE]
228
-
> Once configured, the role assignment function can no longer be accessed by external HTTP requests.
229
-
230
-
### Create a function for assigning roles
231
-
232
-
After defining the `rolesSource` property in your app's configuration, add an [API function](apis-functions.md) in your static web app at the path you specified. You can use a managed function app or a bring your own function app.
233
-
234
-
Each time a user successfully authenticates with an identity provider, the specified function is called via the POST method. The function is passed a JSON object in the request body that contains the user's information from the provider. For some identity providers, the user information also includes an `accessToken` that the function can use to make API calls using the user's identity.
235
-
236
-
This is an example payload from Azure Active Directory:
The function can use the user's information to determine which roles to assign to the user. It must return an HTTP 200 response with a JSON body containing a list of custom role names to assign to the user.
286
-
287
-
For example, to assign the user to the `Reader` and `Contributor` roles, return the following response:
288
-
289
-
```json
290
-
{
291
-
"roles": [
292
-
"Reader",
293
-
"Contributor"
294
-
]
295
-
}
296
-
```
297
-
298
-
If you do not want to assign any additional roles to the user, return an empty `roles` array.
299
-
300
-
To learn more, see [Tutorial: Assign custom roles with a function and Microsoft Graph](assign-roles-microsoft-graph.md).
301
-
302
-
---
303
-
304
-
## Remove personal identifying information
305
-
306
-
When you grant consent to an application as an end user, the application has access to your email address or your username depending on the identity provider. Once this information is provided, the owner of the application decides how to manage personally identifying information.
124
+
When you grant consent to an application as an end user, the application has access to your email address or username, depending on the identity provider. Once this information is provided, the owner of the application can decide how to manage personal data.
307
125
308
126
End users need to contact administrators of individual web apps to revoke this information from their systems.
309
127
310
-
To remove personally identifying information from the Azure Static Web Apps platform, and prevent the platform from providing this information on future requests, submit a request using the URL:
128
+
To remove personal data from the Azure Static Web Apps platform, and prevent the platform from providing this information on future requests, submit a request using the following URL:
0 commit comments