Megosztás a következőn keresztül:

Azure Maps-fiók védelme SAS-jogkivonattal

  • Cikk

Ez a cikk azt ismerteti, hogyan hozhat létre Azure Maps-fiókot egy biztonságosan tárolt SAS-jogkivonattal, amellyel meghívhatja az Azure Maps REST API-t.

Előfeltételek

  • Azure-előfizetés. Ha még nem rendelkezik Azure-fiókkal, regisztráljon egy ingyenes fiókra.

  • Tulajdonosi szerepkör engedélye az Azure-előfizetésben. A tulajdonosi engedélyekre a következőkhöz van szüksége:

    • Hozzon létre egy kulcstartót az Azure Key Vaultban.
    • Hozzon létre egy felhasználó által hozzárendelt felügyelt identitást.
    • Rendeljen hozzá egy szerepkört a felügyelt identitáshoz.
    • Azure Maps-fiók létrehozása.

  • Az erőforrások üzembe helyezéséhez telepített Azure CLI.

Példaforgatókönyv: SAS-jogkivonat biztonságos tárolása

Az SAS-jogkivonat hitelesítő adatai az általa megadott hozzáférési szintet biztosítják bárkinek, aki birtokolja, amíg a jogkivonat le nem jár, vagy a hozzáférést vissza nem vonják. Az SAS-jogkivonat-hitelesítést használó alkalmazásoknak biztonságosan kell tárolniuk a kulcsokat.

Ez a forgatókönyv biztonságosan tárol egy SAS-jogkivonatot titkos kulcsként a Key Vaultban, és elosztja a jogkivonatot egy nyilvános ügyfélen. Az alkalmazás életciklus-eseményei új SAS-jogkivonatokat hozhatnak létre a meglévő jogkivonatokat használó aktív kapcsolatok megszakítása nélkül.

A Key Vault konfigurálásával kapcsolatos további információkért tekintse meg az Azure Key Vault fejlesztői útmutatóját.

Az alábbi példaforgatókönyv két Azure Resource Manager-sablon üzembe helyezését használja a következő lépések végrehajtásához:

  1. Kulcstartó létrehozása.
  2. Hozzon létre egy felhasználó által hozzárendelt felügyelt identitást.
  3. Azure-szerepköralapú hozzáférés-vezérlési (RBAC) Azure Maps-adatolvasó szerepkör hozzárendelése a felhasználó által hozzárendelt felügyelt identitáshoz.
  4. Hozzon létre egy Azure Maps-fiókot egy több forrásból származó erőforrásmegosztási (CORS) konfigurációval, és csatolja a felhasználó által hozzárendelt felügyelt identitást.
  5. SAS-jogkivonat létrehozása és mentése az Azure Key Vaultban.
  6. Kérje le az SAS-jogkivonat titkos kulcsát a kulcstartóból.
  7. Hozzon létre egy Azure Maps REST API-kérést, amely az SAS-jogkivonatot használja.

Ha végzett, látnia kell az Azure Maps Search Address (Non-Batch) REST API-eredményeit a PowerShellben az Azure CLI-vel. Az Azure-erőforrások üzembe helyezése engedélyekkel az Azure Maps-fiókhoz való csatlakozáshoz. A maximális sebességkorlát, az engedélyezett régiók, localhost a konfigurált CORS-szabályzat és az Azure RBAC vezérlői vannak.

Azure-erőforrások üzembe helyezése az Azure CLI-vel

Az alábbi lépések bemutatják, hogyan hozhat létre és konfigurálhat Azure Maps-fiókot SAS-jogkivonat-hitelesítéssel. Ebben a példában az Azure CLI egy PowerShell-példányban fut.

  1. Jelentkezzen be az Azure-előfizetésbe a következővel az login: .

  2. Regisztrálja a Key Vaultot, a felügyelt identitásokat és az Azure Mapset az előfizetéséhez.

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

  3. Kérje le a Microsoft Entra objektumazonosítóját.

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

  4. Hozzon létre egy prereq.azuredeploy.json nevű sablonfájlt a következő tartalommal:

    {
    "$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. Telepítse az előző lépésben létrehozott előfeltétel-erőforrásokat. Adja meg a saját értékét.<group-name> Ügyeljen arra, hogy ugyanazt location használja, mint az Azure Maps-fiókot.

    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. Hozzon létre egy sablonfájlt azuredeploy.json az Azure Maps-fiók, a szerepkör-hozzárendelés és az SAS-jogkivonat kiépítéséhez.

    Feljegyzés

    Azure Maps Gen1 tarifacsomag kivonása

    A Gen1 tarifacsomag elavult, és 26.09.15-én megszűnik. A Gen2 tarifacsomag az 1. generációs (S0 és S1) tarifacsomagot váltja fel. Ha az Azure Maps-fiókjában a Gen1 tarifacsomag van kiválasztva, a kivonás előtt átválthat Gen2-díjszabásra, ellenkező esetben az automatikusan frissül. További információ: Az Azure Maps-fiók tarifacsomagjának kezelése.

    {
    "$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. Helyezze üzembe a sablont a Key Vault azonosítóparamétereivel és az előző lépésben létrehozott felügyelt identitáserőforrásokkal. Adja meg a saját értékét.<group-name> Az SAS-jogkivonat létrehozásakor a paramétert a allowedRegions következőre eastusállítja: , westus2és westcentralus. Ezeket a helyeket használva HTTP-kéréseket kezdeményezhet a us.atlas.microsoft.com végpont felé.

    Fontos

    Az SAS-jogkivonatot a kulcstartóba mentve megakadályozhatja, hogy a hitelesítő adatai megjelenjenek az Azure üzembe helyezési naplóiban. Az SAS-jogkivonat titkos tags kódja tartalmazza a kezdő, a lejárati és az aláírókulcs nevét is, így megjelenítheti, hogy mikor jár le az SAS-jogkivonat.

     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. Keresse meg és mentse az egyetlen SAS-jogkivonat titkos kulcsának másolatát a Key Vaultból.

    $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. Tesztelje az SAS-jogkivonatot egy Azure Maps-végpontra irányuló kéréssel. Ez a példa azt határozza meg, hogy a us.atlas.microsoft.com kérése az USA földrajzi helyéhez legyen irányítva. Az SAS-jogkivonat lehetővé teszi az USA földrajzi régióinak használatát.

    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"

Teljes példa szkriptre

A teljes példa futtatásához a következő sablonfájloknak ugyanabban a könyvtárban kell lenniük, mint az aktuális PowerShell-munkamenet:

  • prereq.azuredeploy.json a kulcstartó és a felügyelt identitás létrehozásához.
  • azuredeploy.json az Azure Maps-fiók létrehozásához, a szerepkör-hozzárendelés és a felügyelt identitás konfigurálásához, valamint az SAS-jogkivonat kulcstartóban való tárolásához.
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"

Valós példa

Az Azure Maps API-khoz a legtöbb ügyféltől ( például C#, Java vagy JavaScript) irányuló kéréseket futtathat. Az OLYAN API-fejlesztési platformok, mint a Bruno vagy a Postman , szinte bármilyen választott programozási nyelven vagy keretrendszerben átalakíthatnak egy API-kérést egy alapszintű ügyfélkódrészletté. Használhatja a létrehozott kódrészleteket az előtérbeli alkalmazásokban.

Az alábbi kis JavaScript-kód példája bemutatja, hogyan használhatja SAS-jogkivonatát a JavaScript Fetch API-val az Azure Maps adatainak lekéréséhez és visszaadásához. A példa a Get Search Address API 1.0-s verzióját használja. Adja meg a saját értékét.<your SAS token>

Ahhoz, hogy ez a minta működjön, győződjön meg arról, hogy az API-hívás forrásától eltérő forrásból allowedOrigins futtatja. Ha például az API-hívásban adja meg https://contoso.com , allowedOrigins a JavaScript-szkriptet futtató HTML-lapnak kell lennie 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
  });

Az erőforrások eltávolítása

Ha már nincs szüksége az Azure-erőforrásokra, törölheti őket:

az group delete --name {group-name}

Következő lépések

Gyorsútmutató ARM-sablon üzembe helyezése SAS-jogkivonatot használó Azure Maps-fiók létrehozásához:

Azure Maps-fiók létrehozása

Részletesebb példákért lásd:

Hitelesítési forgatókönyvek a Microsoft Entra-azonosítóhoz

Az Azure Maps-fiók API-használati metrikáinak megkeresése:

Használati metrikák megtekintése

Ismerje meg a Microsoft Entra ID és az Azure Maps integrálását bemutató példákat:

Azure Maps-minták