Skydda ett Azure Maps-konto med en SAS-token

Artikel
08/08/2024

Den här artikeln beskriver hur du skapar ett Azure Maps-konto med en säkert lagrad SAS-token som du kan använda för att anropa Rest-API:et för Azure Maps.

Förutsättningar

En Azure-prenumeration. Om du inte redan har ett Azure-konto registrerar du dig för ett kostnadsfritt konto.
Ägarrollbehörighet för Azure-prenumerationen. Du behöver behörigheten Ägare för att:
- Skapa ett nyckelvalv i Azure Key Vault.
- Skapa en användartilldelad hanterad identitet.
- Tilldela den hanterade identiteten en roll.
- Skapa ett Azure Maps-konto.
Azure CLI installerat för att distribuera resurserna.

Exempelscenario: SÄKER LAGRING av SAS-token

En SAS-tokenautentiseringsuppgift ger den åtkomstnivå som anges för alla som har den, tills token upphör att gälla eller åtkomsten har återkallats. Program som använder SAS-tokenautentisering bör lagra nycklarna på ett säkert sätt.

Det här scenariot lagrar på ett säkert sätt en SAS-token som en hemlighet i Key Vault och distribuerar token till en offentlig klient. Programlivscykelhändelser kan generera nya SAS-token utan att avbryta aktiva anslutningar som använder befintliga token.

Mer information om hur du konfigurerar Key Vault finns i utvecklarhandboken för Azure Key Vault.

I följande exempelscenario används två DISTRIBUTIONer av Azure Resource Manager-mallar (ARM) för att utföra följande steg:

Skapa ett nyckelvalv.
Skapa en användartilldelad hanterad identitet.
Tilldela rollen Rollbaserad åtkomstkontroll i Azure Maps (RBAC) till den användartilldelade hanterade identiteten.
Skapa ett Azure Maps-konto med en CORS-konfiguration (Cross Origin Resource Sharing) och bifoga den användartilldelade hanterade identiteten.
Skapa och spara en SAS-token i Azure-nyckelvalvet.
Hämta SAS-tokenhemligheten från nyckelvalvet.
Skapa en AZURE Maps REST API-begäran som använder SAS-token.

När du är klar bör du se Azure Maps Search Address (Non-Batch) REST API-resultat på PowerShell med Azure CLI. Azure-resurserna distribueras med behörighet att ansluta till Azure Maps-kontot. Det finns kontroller för maximal hastighetsgräns, tillåtna regioner, localhost konfigurerad CORS-princip och Azure RBAC.

Azure-resursdistribution med Azure CLI

Följande steg beskriver hur du skapar och konfigurerar ett Azure Maps-konto med SAS-tokenautentisering. I det här exemplet körs Azure CLI i en PowerShell-instans.

Logga in på din Azure-prenumeration med az login.

Registrera Key Vault, hanterade identiteter och Azure Maps för din prenumeration.

az provider register --namespace Microsoft.KeyVault
az provider register --namespace Microsoft.ManagedIdentity
az provider register --namespace Microsoft.Maps

Hämta ditt Microsoft Entra-objekt-ID.

$id = $(az rest --method GET --url 'https://graph.microsoft.com/v1.0/me?$select=id' --headers 'Content-Type=application/json' --query "id")

Skapa en mallfil med namnet prereq.azuredeploy.json med följande innehåll:

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "location": {
            "type": "string",
            "defaultValue": "[resourceGroup().location]",
            "metadata": {
                "description": "Specifies the location for all the resources."
            }
        },
        "keyVaultName": {
            "type": "string",
            "defaultValue": "[concat('vault', uniqueString(resourceGroup().id))]",
            "metadata": {
                "description": "Specifies the name of the key vault."
            }
        },
        "userAssignedIdentityName": {
            "type": "string",
            "defaultValue": "[concat('identity', uniqueString(resourceGroup().id))]",
            "metadata": {
                "description": "The name for your managed identity resource."
            }
        },
        "objectId": {
            "type": "string",
            "metadata": {
                "description": "Specifies the object ID of a user, service principal, or security group in the Azure AD tenant for the vault. The object ID must be unique for the set of access policies. Get it by using Get-AzADUser or Get-AzADServicePrincipal cmdlets."
            }
        },
        "secretsPermissions": {
            "type": "array",
            "defaultValue": [
                "list",
                "get",
                "set"
            ],
            "metadata": {
                "description": "Specifies the permissions to secrets in the vault. Valid values are: all, get, list, set, delete, backup, restore, recover, and purge."
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.ManagedIdentity/userAssignedIdentities",
            "name": "[parameters('userAssignedIdentityName')]",
            "apiVersion": "2018-11-30",
            "location": "[parameters('location')]"
        },
        {
            "apiVersion": "2021-04-01-preview",
            "type": "Microsoft.KeyVault/vaults",
            "name": "[parameters('keyVaultName')]",
            "location": "[parameters('location')]",
            "properties": {
                "tenantId": "[subscription().tenantId]",
                "sku": {
                    "name": "Standard",
                    "family": "A"
                },
                "enabledForTemplateDeployment": true,
                "accessPolicies": [
                    {
                        "objectId": "[parameters('objectId')]",
                        "tenantId": "[subscription().tenantId]",
                        "permissions": {
                            "secrets": "[parameters('secretsPermissions')]"
                        }
                    }
                ]
            }
        }
    ],
    "outputs": {
        "userIdentityResourceId": {
            "type": "string",
            "value": "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName'))]"
        },
        "userAssignedIdentityPrincipalId": {
            "type": "string",
            "value": "[reference(parameters('userAssignedIdentityName')).principalId]"
        },
        "keyVaultName": {
            "type": "string",
            "value": "[parameters('keyVaultName')]"
        }
    }
}

Distribuera de nödvändiga resurser som du skapade i föregående steg. Ange ditt eget värde för <group-name>. Se till att använda samma location som Azure Maps-kontot.

az group create --name <group-name> --location "East US"
$outputs = $(az deployment group create --name ExampleDeployment --resource-group <group-name> --template-file "./prereq.azuredeploy.json" --parameters objectId=$id --query "[properties.outputs.keyVaultName.value, properties.outputs.userAssignedIdentityPrincipalId.value, properties.outputs.userIdentityResourceId.value]" --output tsv)

Skapa en mallfil azuredeploy.json för att etablera Azure Maps-kontot, rolltilldelningen och SAS-token.

Kommentar

Azure Maps Gen1-prisnivån dras tillbaka

Prisnivån Gen1 är nu inaktuell och dras tillbaka den 26-09-15. Prisnivån Gen2 ersätter prisnivån Gen1 (både S0 och S1). Om ditt Azure Maps-konto har valt prisnivån Gen1 kan du växla till Gen2-priser innan det dras tillbaka, annars uppdateras det automatiskt. Mer information finns i Hantera prisnivån för ditt Azure Maps-konto.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "location": {
            "type": "string",
            "defaultValue": "[resourceGroup().location]",
            "metadata": {
                "description": "Specifies the location for all the resources."
            }
        },
        "keyVaultName": {
            "type": "string",
            "metadata": {
                "description": "Specifies the resourceId of the key vault."
            }
        },
        "accountName": {
            "type": "string",
            "defaultValue": "[concat('map', uniqueString(resourceGroup().id))]",
            "metadata": {
                "description": "The name for your Azure Maps account."
            }
        },
        "userAssignedIdentityResourceId": {
            "type": "string",
            "metadata": {
                "description": "Specifies the resourceId for the user assigned managed identity resource."
            }
        },
        "userAssignedIdentityPrincipalId": {
            "type": "string",
            "metadata": {
                "description": "Specifies the resourceId for the user assigned managed identity resource."
            }
        },
        "pricingTier": {
            "type": "string",
            "allowedValues": [
                "S0",
                "S1",
                "G2"
            ],
            "defaultValue": "G2",
            "metadata": {
                "description": "The pricing tier for the account. Use S0 for small-scale development. Use S1 or G2 for large-scale applications."
            }
        },
        "kind": {
            "type": "string",
            "allowedValues": [
                "Gen1",
                "Gen2"
            ],
            "defaultValue": "Gen2",
            "metadata": {
                "description": "The pricing tier for the account. Use Gen1 for small-scale development. Use Gen2 for large-scale applications."
            }
        },
        "guid": {
            "type": "string",
            "defaultValue": "[guid(resourceGroup().id)]",
            "metadata": {
                "description": "Input string for new GUID associated with assigning built in role types."
            }
        },
        "startDateTime": {
            "type": "string",
            "defaultValue": "[utcNow('u')]",
            "metadata": {
                "description": "Current Universal DateTime in ISO 8601 'u' format to use as the start of the SAS token."
            }
        },
        "duration" : {
            "type": "string",
            "defaultValue": "P1Y",
            "metadata": {
                "description": "The duration of the SAS token. P1Y is maximum, ISO 8601 format is expected."
            }
        },
        "maxRatePerSecond": {
            "type": "int",
            "defaultValue": 500,
            "minValue": 1,
            "maxValue": 500,
            "metadata": {
                "description": "The approximate maximum rate per second the SAS token can be used."
            }
        },
        "signingKey": {
            "type": "string",
            "defaultValue": "primaryKey",
            "allowedValues": [
                "primaryKey",
                "seconaryKey"
            ],
            "metadata": {
                "description": "The specified signing key which will be used to create the SAS token."
            }
        },
        "allowedOrigins": {
            "type": "array",
            "defaultValue": [],
            "maxLength": 10,
            "metadata": {
                "description": "The specified application's web host header origins (example: https://www.azure.com) which the Azure Maps account allows for CORS."
            }
        }, 
        "allowedRegions": {
            "type": "array",
            "defaultValue": [],
            "metadata": {
                "description": "The specified SAS token allowed locations where the token may be used."
            }
        }
    },
    "variables": {
        "accountId": "[resourceId('Microsoft.Maps/accounts', parameters('accountName'))]",
        "Azure Maps Data Reader": "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '423170ca-a8f6-4b0f-8487-9e4eb8f49bfa')]",
        "sasParameters": {
            "signingKey": "[parameters('signingKey')]",
            "principalId": "[parameters('userAssignedIdentityPrincipalId')]",
            "maxRatePerSecond": "[parameters('maxRatePerSecond')]",
            "start": "[parameters('startDateTime')]",
            "expiry": "[dateTimeAdd(parameters('startDateTime'), parameters('duration'))]",
            "regions": "[parameters('allowedRegions')]"
        }
    },
    "resources": [
        {
            "name": "[parameters('accountName')]",
            "type": "Microsoft.Maps/accounts",
            "apiVersion": "2023-06-01",
            "location": "[parameters('location')]",
            "sku": {
                "name": "[parameters('pricingTier')]"
            },
            "kind": "[parameters('kind')]",
            "properties": {
                "cors": {
                    "corsRules": [
                        {
                            "allowedOrigins": "[parameters('allowedOrigins')]"
                        }
                    ]
                }
            },
            "identity": {
                "type": "UserAssigned",
                "userAssignedIdentities": {
                    "[parameters('userAssignedIdentityResourceId')]": {}
                }
            }
        },
        {
            "apiVersion": "2020-04-01-preview",
            "name": "[concat(parameters('accountName'), '/Microsoft.Authorization/', parameters('guid'))]",
            "type": "Microsoft.Maps/accounts/providers/roleAssignments",
            "dependsOn": [
                "[parameters('accountName')]"
            ],
            "properties": {
                "roleDefinitionId": "[variables('Azure Maps Data Reader')]",
                "principalId": "[parameters('userAssignedIdentityPrincipalId')]",
                "principalType": "ServicePrincipal"
            }
        },
        {
            "apiVersion": "2021-04-01-preview",
            "type": "Microsoft.KeyVault/vaults/secrets",
            "name": "[concat(parameters('keyVaultName'), '/', parameters('accountName'))]",
            "dependsOn": [
                "[variables('accountId')]"
            ],
            "tags": {
                "signingKey": "[variables('sasParameters').signingKey]",
                "start" : "[variables('sasParameters').start]",
                "expiry" : "[variables('sasParameters').expiry]"
            },
            "properties": {
                "value": "[listSas(variables('accountId'), '2023-06-01', variables('sasParameters')).accountSasToken]"
            }
        }
    ]
}

Distribuera mallen med ID-parametrarna från Key Vault och hanterade identitetsresurser som du skapade i föregående steg. Ange ditt eget värde för <group-name>. När du skapar SAS-token anger du parametern allowedRegions till eastus, westus2och westcentralus. Du kan sedan använda dessa platser för att göra HTTP-begäranden till us.atlas.microsoft.com slutpunkten.

Viktigt!

Du sparar SAS-token i nyckelvalvet för att förhindra att dess autentiseringsuppgifter visas i Azure-distributionsloggarna. SAS-tokenhemligheten innehåller också namnet på start-, förfallo- och signeringsnyckeln tags för att visa när SAS-token upphör att gälla.
```
 az deployment group create --name ExampleDeployment --resource-group <group-name> --template-file "./azuredeploy.json" --parameters keyVaultName="$($outputs[0])" userAssignedIdentityPrincipalId="$($outputs[1])" userAssignedIdentityResourceId="$($outputs[2])" allowedOrigins="['http://localhost']" allowedRegions="['eastus', 'westus2', 'westcentralus']" maxRatePerSecond="10"
```

Leta upp och spara en kopia av den enskilda SAS-tokenhemligheten från Key Vault.

$secretId = $(az keyvault secret list --vault-name $outputs[0] --query "[? contains(name,'map')].id" --output tsv)
$sasToken = $(az keyvault secret show --id "$secretId" --query "value" --output tsv)

Testa SAS-token genom att göra en begäran till en Azure Maps-slutpunkt. Det här exemplet anger us.atlas.microsoft.com för att säkerställa att dina begärandevägar till usa:s geografiska område. Din SAS-token tillåter regioner inom den amerikanska geografin.
```
az rest --method GET --url 'https://us.atlas.microsoft.com/search/address/json?api-version=1.0&query=1 Microsoft Way, Redmond, WA 98052' --headers "Authorization=jwt-sas $($sasToken)" --query "results[].address"
```

Exempel på fullständigt skript

Om du vill köra det fullständiga exemplet måste följande mallfiler finnas i samma katalog som den aktuella PowerShell-sessionen:

prereq.azuredeploy.json för att skapa nyckelvalvet och den hanterade identiteten.
azuredeploy.json för att skapa Azure Maps-kontot, konfigurera rolltilldelningen och den hanterade identiteten och lagra SAS-token i nyckelvalvet.

az login
az provider register --namespace Microsoft.KeyVault
az provider register --namespace Microsoft.ManagedIdentity
az provider register --namespace Microsoft.Maps

$id = $(az rest --method GET --url 'https://graph.microsoft.com/v1.0/me?$select=id' --headers 'Content-Type=application/json' --query "id")
az group create --name <group-name> --location "East US"
$outputs = $(az deployment group create --name ExampleDeployment --resource-group <group-name> --template-file "./prereq.azuredeploy.json" --parameters objectId=$id --query "[properties.outputs.keyVaultName.value, properties.outputs.userAssignedIdentityPrincipalId.value, properties.outputs.userIdentityResourceId.value]" --output tsv)
az deployment group create --name ExampleDeployment --resource-group <group-name> --template-file "./azuredeploy.json" --parameters keyVaultName="$($outputs[0])" userAssignedIdentityPrincipalId="$($outputs[1])" userAssignedIdentityResourceId="$($outputs[2])" allowedOrigins="['http://localhost']" allowedRegions="['eastus', 'westus2', 'westcentralus']" maxRatePerSecond="10"
$secretId = $(az keyvault secret list --vault-name $outputs[0] --query "[? contains(name,'map')].id" --output tsv)
$sasToken = $(az keyvault secret show --id "$secretId" --query "value" --output tsv)

az rest --method GET --url 'https://us.atlas.microsoft.com/search/address/json?api-version=1.0&query=1 Microsoft Way, Redmond, WA 98052' --headers "Authorization=jwt-sas $($sasToken)" --query "results[].address"

Verkligt exempel

Du kan köra begäranden till Azure Maps-API:er från de flesta klienter, till exempel C#, Java eller JavaScript. API-utvecklingsplattformar som Bruno eller Postman kan konvertera en API-begäran till ett grundläggande klientkodfragment i nästan vilket programmeringsspråk eller ramverk du vill. Du kan använda de genererade kodfragmenten i dina klientdelsprogram.

Följande lilla JavaScript-kodexempel visar hur du kan använda din SAS-token med JavaScript Fetch API för att hämta och returnera Azure Maps-information. I exemplet används API för hämta sökadress version 1.0. Ange ditt eget värde för <your SAS token>.

För att det här exemplet ska fungera måste du köra det från samma ursprung som allowedOrigins för API-anropet. Om du till exempel anger https://contoso.com som allowedOrigins i API-anropet ska HTML-sidan som är värd för JavaScript-skriptet vara https://contoso.com.

async function getData(url = 'https://us.atlas.microsoft.com/search/address/json?api-version=1.0&query=1 Microsoft Way, Redmond, WA 98052') {
  const response = await fetch(url, {
    method: 'GET',
    mode: 'cors',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'jwt-sas <your SAS token>',
    }
  });
  return response.json(); // parses JSON response into native JavaScript objects
}

postData('https://us.atlas.microsoft.com/search/address/json?api-version=1.0&query=1 Microsoft Way, Redmond, WA 98052')
  .then(data => {
    console.log(data); // JSON data parsed by `data.json()` call
  });