Delen via

Een Azure Maps-account beveiligen met een SAS-token

  • Artikel

In dit artikel wordt beschreven hoe u een Azure Maps-account maakt met een veilig opgeslagen SAS-token dat u kunt gebruiken om de Azure Maps REST API aan te roepen.

Vereisten

  • Een Azure-abonnement. Als u nog geen Azure-account hebt, meldt u zich aan voor een gratis account.

  • Machtiging voor de rol van eigenaar voor het Azure-abonnement. U hebt de machtigingen van de eigenaar nodig voor het volgende:

    • Maak een sleutelkluis in Azure Key Vault.
    • Maak een door de gebruiker toegewezen beheerde identiteit.
    • Wijs de beheerde identiteit een rol toe.
    • Maak een Azure Maps-account.

  • Azure CLI is geïnstalleerd om de resources te implementeren.

Voorbeeldscenario: beveiligde opslag van SAS-token

Een SAS-tokenreferentie verleent het toegangsniveau dat wordt opgegeven aan iedereen die het bewaart, totdat het token verloopt of de toegang wordt ingetrokken. Toepassingen die gebruikmaken van SAS-tokenverificatie moeten de sleutels veilig opslaan.

In dit scenario wordt een SAS-token veilig opgeslagen als geheim in Key Vault en wordt het token gedistribueerd naar een openbare client. Gebeurtenissen in de levenscyclus van toepassingen kunnen nieuwe SAS-tokens genereren zonder actieve verbindingen te onderbreken die gebruikmaken van bestaande tokens.

Zie de handleiding voor ontwikkelaars van Azure Key Vault voor meer informatie over het configureren van Key Vault.

In het volgende voorbeeldscenario worden twee ARM-sjabloonimplementaties (Azure Resource Manager) gebruikt om de volgende stappen uit te voeren:

  1. Een sleutelkluis maken.
  2. Maak een door de gebruiker toegewezen beheerde identiteit.
  3. Wijs op rollen gebaseerd toegangsbeheer (RBAC) van Azure Maps Data Reader toe aan de door de gebruiker toegewezen beheerde identiteit.
  4. Maak een Azure Maps-account met een CORS-configuratie (Cross Origin Resource Sharing) en koppel de door de gebruiker toegewezen beheerde identiteit.
  5. Maak en sla een SAS-token op in de Azure-sleutelkluis.
  6. Haal het SAS-tokengeheim op uit de sleutelkluis.
  7. Maak een Azure Maps REST API-aanvraag die gebruikmaakt van het SAS-token.

Wanneer u klaar bent, ziet u rest API-resultaten van Azure Maps Search Address (Non-Batch) in PowerShell met Azure CLI. De Azure-resources worden geïmplementeerd met machtigingen om verbinding te maken met het Azure Maps-account. Er zijn besturingselementen voor maximale snelheidslimiet, toegestane regio's, localhost geconfigureerd CORS-beleid en Azure RBAC.

Implementatie van Azure-resources met Azure CLI

In de volgende stappen wordt beschreven hoe u een Azure Maps-account maakt en configureert met SAS-tokenverificatie. In dit voorbeeld wordt Azure CLI uitgevoerd in een PowerShell-exemplaar.

  1. Meld u aan bij uw Azure-abonnement met az login.

  2. Registreer Key Vault, Beheerde identiteiten en Azure Maps voor uw abonnement.

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

  3. Haal uw Microsoft Entra-object-id op.

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

  4. Maak een sjabloonbestand met de naam prereq.azuredeploy.json met de volgende inhoud:

    {
    "$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. Implementeer de vereiste resources die u in de vorige stap hebt gemaakt. Geef uw eigen waarde op voor <group-name>. Zorg ervoor dat u hetzelfde location gebruikt als het Azure Maps-account.

    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. Maak een sjabloonbestand azuredeploy.json om het Azure Maps-account, de roltoewijzing en het SAS-token in te richten.

    Notitie

    Buitengebruikstelling van Azure Maps Gen1-prijscategorie

    De prijscategorie Gen1 is nu afgeschaft en wordt buiten gebruik gesteld op 15-9-26. De prijscategorie Gen2 vervangt de prijscategorie Gen1 (zowel S0 als S1). Als voor uw Azure Maps-account een Gen1-prijscategorie is geselecteerd, kunt u overschakelen naar Gen2-prijzen voordat het buiten gebruik wordt gesteld, anders wordt deze automatisch bijgewerkt. Zie De prijscategorie van uw Azure Maps-account beheren voor meer informatie.

    {
    "$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",
                "secondaryKey"
            ],
            "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. Implementeer de sjabloon met de id-parameters uit de Key Vault en beheerde identiteitsbronnen die u in de vorige stap hebt gemaakt. Geef uw eigen waarde op voor <group-name>. Wanneer u het SAS-token maakt, stelt u de allowedRegions parameter eastusin op , westus2en westcentralus. Vervolgens kunt u deze locaties gebruiken om HTTP-aanvragen naar het us.atlas.microsoft.com eindpunt te verzenden.

    Belangrijk

    U slaat het SAS-token op in de sleutelkluis om te voorkomen dat de referenties worden weergegeven in de Azure-implementatielogboeken. Het SAS-tokengeheim tags bevat ook de naam van de begin-, verloop- en ondertekeningssleutel om aan te geven wanneer het SAS-token verloopt.

     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. Zoek en sla een kopie van het enkele SAS-tokengeheim op uit 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. Test het SAS-token door een aanvraag in te dienen bij een Azure Maps-eindpunt. In dit voorbeeld wordt aangegeven of uw aanvraagroutes naar de geografie in de us.atlas.microsoft.com VS moeten worden gerouteerd. Uw SAS-token staat regio's binnen de Geografie van de VS toe.

    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"

Voorbeeld van voltooid script

Als u het volledige voorbeeld wilt uitvoeren, moeten de volgende sjabloonbestanden zich in dezelfde map bevinden als de huidige PowerShell-sessie:

  • prereq.azuredeploy.json om de sleutelkluis en beheerde identiteit te maken.
  • azuredeploy.json om het Azure Maps-account te maken, de roltoewijzing en beheerde identiteit te configureren en het SAS-token op te slaan in de sleutelkluis.
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"

Praktijkvoorbeeld

U kunt aanvragen uitvoeren naar Azure Maps-API's van de meeste clients, zoals C#, Java of JavaScript. API-ontwikkelplatforms zoals Bruno of Postman kunnen een API-aanvraag converteren naar een eenvoudig codefragment van de client in vrijwel elke programmeertaal of elk framework dat u kiest. U kunt de gegenereerde codefragmenten in uw front-endtoepassingen gebruiken.

In het volgende kleine JavaScript-codevoorbeeld ziet u hoe u uw SAS-token kunt gebruiken met de JavaScript Fetch-API om Azure Maps-informatie op te halen en te retourneren. In het voorbeeld wordt get Search Address API versie 1.0 gebruikt. Geef uw eigen waarde op voor <your SAS token>.

Zorg ervoor dat dit voorbeeld werkt vanuit dezelfde oorsprong als de allowedOrigins API-aanroep. Als u bijvoorbeeld opgeeft https://contoso.com als de allowedOrigins API-aanroep, moet de HTML-pagina die als host fungeert voor het JavaScript-script zijn 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
  });

Resources opschonen

Wanneer u de Azure-resources niet meer nodig hebt, kunt u ze verwijderen:

az group delete --name {group-name}

Volgende stappen

Een quickstart-ARM-sjabloon implementeren om een Azure Maps-account te maken dat gebruikmaakt van een SAS-token:

Een Azure Maps-account maken

Zie voor meer gedetailleerde voorbeelden:

Verificatiescenario's voor Microsoft Entra-id

Zoek de metrische gegevens over API-gebruik voor uw Azure Maps-account:

Metrische gegevens over gebruik weergeven

Bekijk voorbeelden die laten zien hoe u Microsoft Entra ID integreert met Azure Maps:

Voorbeelden van Azure Maps