Dela via


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:

  1. Skapa ett nyckelvalv.
  2. Skapa en användartilldelad hanterad identitet.
  3. Tilldela rollen Rollbaserad åtkomstkontroll i Azure Maps (RBAC) till den användartilldelade hanterade identiteten.
  4. Skapa ett Azure Maps-konto med en CORS-konfiguration (Cross Origin Resource Sharing) och bifoga den användartilldelade hanterade identiteten.
  5. Skapa och spara en SAS-token i Azure-nyckelvalvet.
  6. Hämta SAS-tokenhemligheten från nyckelvalvet.
  7. 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.

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

  2. 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
    
  3. 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")
    
  4. 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')]"
            }
        }
    }
    
    
  5. 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)
    
  6. 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]"
                }
            }
        ]
    }
    
  7. 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"
    
  8. 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)
    
  9. 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: