Skydda ett Azure Maps-konto med en SAS-token
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 sammalocation
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 parameternallowedRegions
tilleastus
,westus2
ochwestcentralus
. Du kan sedan använda dessa platser för att göra HTTP-begäranden tillus.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
});
Rensa resurser
När du inte längre behöver Azure-resurserna kan du ta bort dem:
az group delete --name {group-name}
Nästa steg
Distribuera en ARM-mall för snabbstart för att skapa ett Azure Maps-konto som använder en SAS-token:
Mer detaljerade exempel finns i:
Hitta API-användningsstatistiken för ditt Azure Maps-konto:
Utforska exempel som visar hur du integrerar Microsoft Entra-ID med Azure Maps: