Merge pull request #222274 from chcomley/users/chcomley/swa-authentication-authorization-12-14-2022

[SWA] Refresh/peer review Authentication-Authorization

Author: Stacyrch140

articles/static-web-apps/assign-roles-microsoft-graph.md

@@ -19,10 +19,10 @@ In this tutorial, you learn to:
 - Deploy a static web app.
 - Create an Azure Active Directory app registration.
 - Set up custom authentication with Azure Active Directory.
-- Configure a [serverless function](authentication-authorization.md?tabs=function#role-management) that queries the user's Active Directory group membership and returns a list of custom roles.
+- Configure a [serverless function](authentication-custom.md#manage-roles) that queries the user's Active Directory group membership and returns a list of custom roles.
 
 > [!NOTE]
-> This tutorial requires you to [use a function to assign roles](authentication-authorization.md?tabs=function#role-management). Function-based role management is currently in preview.
+> This tutorial requires you to [use a function to assign roles](authentication-custom.md#manage-roles). Function-based role management is currently in preview.
 
 ## Prerequisites
 

articles/static-web-apps/authentication-authorization.md

@@ -317,6 +317,188 @@ To use a custom identity provider, use the following URL patterns.
 
 If you are using Azure Active Directory, use `aad` as the value for the `<PROVIDER_NAME_IN_CONFIG>` placeholder.
 
+## Manage roles
+
+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:
+
+- **anonymous**: All users automatically belong to the _anonymous_ role.
+- **authenticated**: All users who are signed in belong to the _authenticated_ role.
+
+Beyond the built-in roles, you can assign custom roles to users, and reference them in the _staticwebapp.config.json_ file.
+
+# [Invitations](#tab/invitations)
+
+### Add a user to a role
+
+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.
+
+<a name="invitations" id="invitations"></a>
+
+#### Create an invitation
+
+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.
+
+<a name="provider-user-details" id="provider-user-details"></a>
+
+| Authorization provider | Exposes |
+| ---------------------- | ---------------- |
+| Azure AD | email address    |
+| GitHub                 | username         |
+| Twitter                | username         |
+
+Do the following steps to create an invitation.
+
+1. Go to a Static Web Apps resource in the [Azure portal](https://portal.azure.com).
+2. Under _Settings_, select **Role Management**.
+3. Select **Invite**.
+4. Select an _Authorization provider_ from the list of options.
+5. Add either the username or email address of the recipient in the _Invitee details_ box.
+   - For GitHub and Twitter, enter the username. For all others, enter the recipient's email address.
+6. Select the domain of your static site from the _Domain_ drop-down menu.
+   - The domain you select is the domain that appears in the invitation. If you have a custom domain associated with your site, choose the custom domain.
+7. Add a comma-separated list of role names in the _Role_ box.
+8. Enter the maximum number of hours you want the invitation to remain valid.
+   - The maximum possible limit is 168 hours, which is seven days.
+9. Select **Generate**.
+10. Copy the link from the _Invite link_ box.
+11. Email the invitation link to the user that you're granting access to.
+
+When the user selects the link in the invitation, they're prompted to sign in with their corresponding account. Once successfully signed in, the user is associated with the selected roles.
+
+> [!CAUTION]
+> Make sure your route rules don't conflict with your selected authentication providers. Blocking a provider with a route rule prevents users from accepting invitations.
+
+### Update role assignments
+
+1. Go to a Static Web Apps resource in the [Azure portal](https://portal.azure.com).
+1. Under _Settings_, select **Role Management**.
+2. Select the user in the list.
+3. Edit the list of roles in the _Role_ box.
+4. Select **Update**.
+
+### Remove user
+
+1. Go to a Static Web Apps resource in the [Azure portal](https://portal.azure.com).
+1. Under _Settings_, select **Role Management**.
+1. Locate the user in the list.
+1. Check the checkbox on the user's row.
+2. Select **Delete**.
+
+As you remove a user, keep in mind the following items:
+
+- Removing a user invalidates their permissions.
+- Worldwide propagation may take a few minutes.
+- If the user is added back to the app, the [`userId` changes](user-information.md).
+
+# [Function (preview)](#tab/function)
+
+Instead of using the built-in invitations system, you can use a serverless function to programmatically assign roles to users when they sign in.
+
+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.
+
+Example uses of this function include:
+
+- Query a database to determine which roles a user should be assigned
+- Call the [Microsoft Graph API](https://developer.microsoft.com/graph) to determine a user's roles based on their Active Directory group membership
+- Determine a user's roles based on claims returned by the identity provider
+
+> [!NOTE]
+> The ability to assign roles via a function is only available when [custom authentication](authentication-custom.md) is configured.
+>
+> When this feature is enabled, any roles assigned via the built-in invitations system are ignored.
+
+### Configure a function for assigning roles
+
+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.
+
+```json
+{
+  "auth": {
+    "rolesSource": "/api/GetRoles",
+    "identityProviders": {
+      // ...
+    }
+  }
+}
+```
+
+> [!NOTE]
+> Once configured, the role assignment function can no longer be accessed by external HTTP requests.
+
+### Create a function for assigning roles
+
+After you define the `rolesSource` property in your app's configuration, add an [API function](apis-functions.md) in your static web app at the specified path. You can use a managed function app or [bring your own function app](functions-bring-your-own.md).
+
+Each time a user successfully authenticates with an identity provider, the POST method calls the specified function. The function passes 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.
+
+See the following example payload from Azure AD:
+
+```json
+{
+  "identityProvider": "aad",
+  "userId": "72137ad3-ae00-42b5-8d54-aacb38576d76",
+  "userDetails": "[email protected]",
+  "claims": [
+      {
+          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
+          "val": "[email protected]"
+      },
+      {
+          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
+          "val": "Contoso"
+      },
+      {
+          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
+          "val": "Ellen"
+      },
+      {
+          "typ": "name",
+          "val": "Ellen Contoso"
+      },
+      {
+          "typ": "http://schemas.microsoft.com/identity/claims/objectidentifier",
+          "val": "7da753ff-1c8e-4b5e-affe-d89e5a57fe2f"
+      },
+      {
+          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
+          "val": "72137ad3-ae00-42b5-8d54-aacb38576d76"
+      },
+      {
+          "typ": "http://schemas.microsoft.com/identity/claims/tenantid",
+          "val": "3856f5f5-4bae-464a-9044-b72dc2dcde26"
+      },
+      {
+          "typ": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
+          "val": "[email protected]"
+      },
+      {
+          "typ": "ver",
+          "val": "1.0"
+      }
+  ],
+  "accessToken": "eyJ0eXAiOiJKV..."
+}
+```
+
+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.
+
+For example, to assign the user to the `Reader` and `Contributor` roles, return the following response:
+
+```json
+{
+  "roles": [
+    "Reader",
+    "Contributor"
+  ]
+}
+```
+
+If you don't want to assign any other roles to the user, return an empty `roles` array.
+
+To learn more, see [Tutorial: Assign custom roles with a function and Microsoft Graph](assign-roles-microsoft-graph.md).
+
+---
+
 ## Next steps
 
 > [!div class="nextstepaction"]

articles/static-web-apps/authentication-custom.md

@@ -353,7 +353,7 @@ In addition to IP address blocks, you can also specify [service tags](../virtual
 
 ## Authentication
 
-* [Default authentication providers](authentication-authorization.md#login), don't require settings in the configuration file. 
+* [Default authentication providers](authentication-authorization.md#set-up-sign-in), don't require settings in the configuration file. 
 * [Custom authentication providers](authentication-custom.md) use the `auth` section of the settings file.
 
 For details on how to restrict routes to authenticated users, see [Securing routes with roles](#securing-routes-with-roles).

articles/static-web-apps/configuration.md

@@ -157,12 +157,12 @@ sections:
       - question: |
           How many users can log in to my static web app?
         answer:
-          Static Web Apps doesn't have a limit on the number of users that can log in to your app. You can assign custom roles to up to 25 users using the built-in invitations system. If you need to assign custom roles to more users, you can use an [API function to programmatically assign roles](authentication-authorization.md?tabs=function#role-management).
+          Static Web Apps doesn't have a limit on the number of users that can log in to your app. You can assign custom roles to up to 25 users using the built-in invitations system. If you need to assign custom roles to more users, you can use an [API function to programmatically assign roles](authentication-custom.md#manage-roles).
           
       - question: |
           How do I use the retrieve a user's access token or claims from the identity provider?
         answer: |
-          You can retrieve the user's access token and claims when you use an [API function for role management](authentication-authorization.md?tabs=function#role-management).
+          You can retrieve the user's access token and claims when you use an [API function for role management](authentication-custom.md#manage-roles).
 
       - question: |
           Am I limited to using a single identity provider?

articles/static-web-apps/faq.yml

@@ -27,7 +27,7 @@ Azure Static Web Apps is available through two different plans, Free and Standar
 | Custom domains | 2 per app | 5 per app |
 | APIs via Azure Functions | Managed | Managed or<br>[Bring your own Functions app](functions-bring-your-own.md) |
 | Authentication provider integration | [Pre-configured](authentication-authorization.md)<br>(Service defined) | [Custom registrations](authentication-custom.md) |
-| [Assign custom roles with a function](authentication-authorization.md?tabs=function#role-management) | - | ✔ |
+| [Assign custom roles with a function](authentication-custom.md#manage-roles) | - | ✔ |
 | Private endpoints | - | ✔ |
 | [Service Level Agreement (SLA)](https://azure.microsoft.com/support/legal/sla/app-service-static/v1_0/) | None  | ✔ |
 

articles/static-web-apps/plans.md

@@ -24,7 +24,7 @@ The following quotas exist for Azure Static Web Apps.
 | Custom domains              | 2 per app        | 5 per app |
 | Allowed IP ranges           | Unavailable      | 25 |
 | Authorization (built-in roles) | Unlimited end-users that may authenticate with built-in `authenticated` role | Unlimited end-users that may authenticate with built-in `authenticated` role |
-| Authorization (custom roles) | Maximum of 25 end-users that may belong to custom roles via [invitations](authentication-authorization.md?tabs=invitations#role-management) | Maximum of 25 end-users that may belong to custom roles via [invitations](authentication-authorization.md?tabs=invitations#role-management), or unlimited end-users that may be assigned custom roles via [serverless function](authentication-authorization.md?tabs=function#role-management) |
+| Authorization (custom roles) | Maximum of 25 end-users that may belong to custom roles via [invitations](authentication-custom.md#manage-roles) | Maximum of 25 end-users that may belong to custom roles via [invitations](authentication-custom.md#manage-roles), or unlimited end-users that may be assigned custom roles via [serverless function](authentication-custom.md#manage-roles) |
 | Request Size Limit | 30 MB               | 30 MB |
 
 ## GitHub storage