Tutorial: Assign custom roles with a function and Microsoft Graph

This article demonstrates how to use a function to query Microsoft Graph and assign custom roles to a user based on their Active Directory group membership.

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 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. Function-based role management is currently in preview.

Prerequisites

  • Active Azure account: If you don't have one, you can create an account for free.
  • You must have sufficient permissions to create an Azure Active Directory application.

Create a GitHub repository

  1. Navigate to the following location to create a new repository:

  2. Name your repository my-custom-roles-app.

  3. Select Create repository from template.

Deploy the static web app to Azure

  1. In a new browser window, navigate to the Azure portal and sign in with your Azure account.

  2. Select Create a resource in the top left corner.

  3. Type static web apps in the search box.

  4. Select Static Web App.

  5. Select Create.

  6. Configure your Azure Static Web App with the following information:

    Input Value Notes
    Subscription Select your Azure subscription
    Resource group Create a new one named my-custom-roles-app-group
    Name my-custom-roles-app
    Hosting plan Standard Customizing authentication and assigning roles using a function require the Standard plan
    Region Select a region closest to you
    Deployment details Select GitHub as the source
  7. Select the Sign-in with GitHub button and authenticate with GitHub.

  8. Select the name of the Organization where you created the repository.

  9. Select my-custom-roles-app from the Repository drop-down.

  10. Select main from the Branch drop-down.

  11. In the Build Details section, add configuration details for this app.

    Input Value Notes
    Build presets Custom
    App location frontend Folder in the repository containing the app
    API location api Folder in the repository containing the API
    Output location This app has no build output
  12. Select Review + create. Then select Create to create the static web app and initiate the first deployment.

  13. Select Go to resource to open your new static web app.

  14. In the overview section, locate your application's URL. Copy this value into a text editor as you'll need this URL to set up Active Directory authentication and test the app.

Create an Azure Active Directory application

  1. In the Azure portal, search for and navigate to Azure Active Directory.

  2. In the menu bar, select App registrations.

  3. Select + New registration to open the Register an application page

  4. Enter a name for the application. For example, MyStaticWebApp.

  5. For Supported account types, select Accounts in this organizational directory only.

  6. For Redirect URIs, select Web and enter the Azure Active Directory login authentication callback of your static web app. For example, <YOUR_SITE_URL>/.auth/login/aad/callback.

    Replace <YOUR_SITE_URL> with the URL of your static web app.

    Create an app registration

  7. Select Register.

  8. After the app registration is created, copy the Application (client) ID and Directory (tenant) ID in the Essentials section to a text editor. You'll need these values to configure Active Directory authentication in your static web app.

Enable ID tokens

  1. Select Authentication in the menu bar.

  2. In the Implicit grant and hybrid flows section, select ID tokens (used for implicit and hybrid flows).

    Enable ID tokens

    This configuration is required by Static Web Apps to authenticate your users.

  3. Select Save.

Create a client secret

  1. Select Certificates & secrets in the menu bar.

  2. In the Client secrets section, select + New client secret.

  3. Enter a name for the client secret. For example, MyStaticWebApp.

  4. Leave the default of 6 months for the Expires field.

    Note

    You must rotate the secret before the expiration date by generating a new secret and updating your app with its value.

  5. Select Add.

  6. Note the Value of the client secret you created. You'll need this value to configure Active Directory authentication in your static web app.

    Create a client secret

Configure Active Directory authentication

  1. In a browser, open the GitHub repository containing the static web app you deployed. Navigate to the app's configuration file at frontend/staticwebapp.config.json. It contains the following section:

    "auth": {
      "rolesSource": "/api/GetRoles",
      "identityProviders": {
        "azureActiveDirectory": {
          "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
          "registration": {
            "openIdIssuer": "https://login.microsoftonline.com/<YOUR_AAD_TENANT_ID>",
            "clientIdSettingName": "AAD_CLIENT_ID",
            "clientSecretSettingName": "AAD_CLIENT_SECRET"
          },
          "login": {
            "loginParameters": [
              "resource=https://graph.microsoft.com"
            ]
          }
        }
      }
    },
    

    Note

    To obtain an access token for Microsoft Graph, the loginParameters field must be configured with resource=https://graph.microsoft.com.

  2. Select the Edit button to update the file.

  3. Update the openIdIssuer value of https://login.microsoftonline.com/<YOUR_AAD_TENANT_ID> by replacing <YOUR_AAD_TENANT_ID> with the directory (tenant) ID of your Azure Active Directory.

  4. Select Commit directly to the main branch and select Commit changes.

  5. A GitHub Actions run triggers to update the static web app.

  6. Navigate to your static web app resource in the Azure portal.

  7. Select Configuration in the menu bar.

  8. In the Application settings section, add the following settings:

    Name Value
    AAD_CLIENT_ID Your Active Directory application (client) ID
    AAD_CLIENT_SECRET Your Active Directory application client secret value
  9. Select Save.

Verify custom roles

The sample application contains a serverless function (api/GetRoles/index.js) that queries Microsoft Graph to determine if a user is in a pre-defined group. Based on the user's group memberships, the function assigns custom roles to the user. The application is configured to restrict certain routes based on these custom roles.

  1. In your GitHub repository, navigate to the GetRoles function located at api/GetRoles/index.js. Near the top, there is a roleGroupMappings object that maps custom user roles to Azure Active Directory groups.

  2. Click the Edit button.

  3. Update the object with group IDs from your Azure Active Directory tenant.

    For instance, if you have groups with IDs 6b0b2fff-53e9-4cff-914f-dd97a13bfbd6 and b6059db5-9cef-4b27-9434-bb793aa31805, you would update the object to:

    const roleGroupMappings = {
      'admin': '6b0b2fff-53e9-4cff-914f-dd97a13bfbd6',
      'reader': 'b6059db5-9cef-4b27-9434-bb793aa31805'
    };
    

    The GetRoles function is called whenever a user is successfully authenticated with Azure Active Directory. The function uses the user's access token to query their Active Directory group membership from Microsoft Graph. If the user is a member of any groups defined in the roleGroupMappings object , the corresponding custom roles are returned by the function.

    In the above example, if a user is a member of the Active Directory group with ID b6059db5-9cef-4b27-9434-bb793aa31805, they are granted the reader role.

  4. Select Commit directly to the main branch and select Commit changes.

  5. A GitHub Actions run triggers to update the static web app.

  6. When the deployment is complete, you can verify your changes by navigating to the app's URL.

  7. Log in to your static web app using Azure Active Directory.

  8. When you are logged in, the sample app displays the list of roles that you are assigned based on your identity's Active Directory group membership. Depending on these roles, you are permitted or prohibited to access some of the routes in the app.

Clean up resources

Clean up the resources you deployed by deleting the resource group.

  1. From the Azure portal, select Resource group from the left menu.

  2. Enter the resource group name in the Filter by name field.

  3. Select the resource group name you used in this tutorial.

  4. Select Delete resource group from the top menu.

Next steps