Secure a web application with user sign-in

The following guide pertains to an application that is hosted on web servers, maintains multiple business scenarios, and deploys to web servers. The application has the requirement to provide protected resources secured only to Azure AD users. The objective of the scenario is to enable the web application to authenticate to Azure AD and call Azure Maps REST APIs on behalf of the user.

To view your Azure Maps account authentication details in the Azure portal:

  1. Sign in to the Azure portal.

  2. Navigate to the Azure portal menu. Select All resources, and then select your Azure Maps account.

  3. Under Settings in the left pane, select Authentication.

    Authentication details.

Three values are created when the Azure Maps account is created. They're used to support two types of authentication in Azure Maps:

  • Azure Active Directory Authentication: The Client ID represents the account that is to be used for REST API requests. The Client ID value should be stored in application configuration, and then it should be retrieved before making Azure Maps HTTP requests that use Azure AD authentication.
  • Shared Key Authentication: The Primary Key and Secondary Key are used as the subscription key for Shared Key authentication. Shared Key authentication relies on passing the key generated by the Azure Maps account with each request to Azure Maps. We recommend that you regularly regenerate your keys. To maintain current connections during regeneration, two keys are provided. One key can be in use, while regenerating the other. When you regenerate your keys, you must update any applications that access this account to use the new keys. For more information, see Authentication with Azure Maps

Create an application registration in Azure AD

You must create the web application in Azure AD for users to sign in. This web application then delegates user access to Azure Maps REST APIs.

  1. In the Azure portal, in the list of Azure services, select Azure Active Directory > App registrations > New registration.

    A screenshot showing App registration.

  2. Enter a Name, choose a Support account type, provide a redirect URI that represents the url to which Azure AD issues the token, which is the url where the map control is hosted. For more information, see Azure AD Scenario: Web app that signs in users. Complete the provided steps from the Azure AD scenario.

  3. Once the application registration is complete, confirm that application sign-in works for users. Once sign-in works, the application can be granted delegated access to Azure Maps REST APIs.

  4. To assign delegatedÔÇ»API permissions to Azure Maps, go to the application and select API permissions > Add a permission. select Azure Maps in the APIs my organization uses list.

    A screenshot showing add app API permissions.

  5. Select the check box next to Access Azure Maps, and then select Add permissions.

    A screenshot showing select app API permissions.

  6. Enable the web application to call Azure Maps REST APIs by configuring the app registration with an application secret, For detailed steps, see A web app that calls web APIs: App registration. A secret is required to authenticate to Azure AD on-behalf of the user. The app registration certificate or secret should be stored in a secure store for the web application to retrieve to authenticate to Azure AD.

    • This step may be skipped if the application already has an Azure AD app registration and secret configured.

    Tip

    If the application is hosted in an Azure environment, we recommend using Managed identities for Azure resources and an Azure Key Vault instance to access secrets by acquiring an access token for accessing Azure Key Vault secrets or certificates. To connect to Azure Key Vault to retrieve secrets, see tutorial to connect through managed identity.

  7. Implement a secure token endpoint for the Azure Maps Web SDK to access a token.

    • For a sample token controller, see Azure Maps Azure AD Samples.
    • For a non-AspNetCore implementation or other, see Acquire token for the app from Azure AD documentation.
    • The secured token endpoint is responsible to return an access token for the authenticated and authorized user to call Azure Maps REST APIs.
  8. To configure Azure role-based access control (Azure RBAC) for users or groups, see grant role-based access for users.

  9. Configure the web application page with the Azure Maps Web SDK to access the secure token endpoint.

var map = new atlas.Map("map", {
        center: [-122.33, 47.64],
        zoom: 12,
        language: "en-US",
        authOptions: {
            authType: "anonymous",
            clientId: "<insert>",  // azure map account client id
            getToken: function (resolve, reject, map) {
                var xhttp = new XMLHttpRequest();
                xhttp.open("GET", "/api/token", true); // the url path maps to the token endpoint.
                xhttp.onreadystatechange = function () {
                    if (this.readyState === 4 && this.status === 200) {
                        resolve(this.responseText);
                    } else if (this.status !== 200) {
                        reject(this.responseText);
                    }
                };

                xhttp.send();
            }
        }
    });
    map.events.add("tokenacquired", function () {
        console.log("token acquired");
    });
    map.events.add("error", function (err) {
        console.log(JSON.stringify(err.error));
    });

Grant role-based access for users to Azure Maps

You can grant Azure role-based access control (Azure RBAC) by assigning an Azure AD group or security principal to one or more Azure Maps role definitions.

To view the available Azure role definitions for Azure Maps, see View built-in Azure Maps role definitions.

For detailed steps about how to assign an available Azure Maps role to the created managed identity or the service principal, see Assign Azure roles using the Azure portal

To efficiently manage the Azure Maps app and resource access of a large amount of users, see Azure AD Groups.

Important

For users to be allowed to authenticate to an application, the users must first be created in Azure AD. For more information, see Add or delete users using Azure AD.

To learn about how to effectively manage a large directory for users, see Azure AD.

Warning

Azure Maps built-in role definitions provide a very large authorization access to many Azure Maps REST APIs. To restrict APIs access to a minimum, see create a custom role definition and assign the system-assigned identity to the custom role definition. This enables the least privilege necessary for the application to access Azure Maps.

Next steps

Further understanding of web application scenario:

Find the API usage metrics for your Azure Maps account:

Explore samples that show how to integrate Azure AD with Azure Maps: