SAS belirteci ile bir Azure Haritalar hesabının güvenliğini sağlama

Makale
10/18/2023

Bu makalede, Azure Haritalar REST API'sini çağırmak için kullanabileceğiniz güvenli bir şekilde depolanmış SAS belirtecine sahip bir Azure Haritalar hesabının nasıl oluşturulacağı açıklanır.

Ön koşullar

Azure aboneliği. Henüz bir Azure hesabınız yoksa ücretsiz bir hesap için kaydolun.
Azure aboneliğinde sahip rolü izni. Aşağıdakiler için Sahip izinlerine sahip olmanız gerekir:
- Azure Key Vault'ta bir anahtar kasası oluşturun.
- Kullanıcı tarafından atanmış bir yönetilen kimlik oluşturun.
- Yönetilen kimliğe bir rol atayın.
- bir Azure Haritalar hesabı oluşturun.
Kaynakları dağıtmak için Azure CLI yüklendi .

Örnek senaryo: SAS belirteci güvenli depolama

SAS belirteci kimlik bilgileri, belirtecin süresi dolana veya erişim iptal edilene kadar, belirteci tutan herkese belirttiği erişim düzeyini verir. SAS belirteci kimlik doğrulaması kullanan uygulamaların anahtarları güvenli bir şekilde depolaması gerekir.

Bu senaryo, SAS belirtecini Key Vault'ta gizli dizi olarak güvenli bir şekilde depolar ve belirteci bir genel istemciye dağıtır. Uygulama yaşam döngüsü olayları, mevcut belirteçleri kullanan etkin bağlantıları kesintiye uğratmadan yeni SAS belirteçleri oluşturabilir.

Key Vault'un yapılandırılması hakkında daha fazla bilgi için bkz . Azure Key Vault geliştirici kılavuzu.

Aşağıdaki örnek senaryoda aşağıdaki adımları gerçekleştirmek için iki Azure Resource Manager (ARM) şablonu dağıtımı kullanılmaktadır:

Anahtar kasası oluşturma.
Kullanıcı tarafından atanmış bir yönetilen kimlik oluşturun.
Kullanıcı tarafından atanan yönetilen kimliğe Azure rol tabanlı erişim denetimi (RBAC) Azure Haritalar Veri Okuyucusu rolü atayın.
Çıkış Noktaları Arası Kaynak Paylaşımı (CORS) yapılandırmasıyla bir Azure Haritalar hesabı oluşturun ve kullanıcı tarafından atanan yönetilen kimliği ekleyin.
Azure anahtar kasasında SAS belirteci oluşturun ve kaydedin.
Anahtar kasasından SAS belirteci gizli dizisini alın.
SAS belirtecini kullanan bir Azure Haritalar REST API isteği oluşturun.

bitirdiğinizde Azure CLI ile PowerShell'de Azure Haritalar Search Address (Non-Batch) REST API sonuçlarını görmeniz gerekir. Azure kaynakları, Azure Haritalar hesabına bağlanma izinleri ile dağıtılır. Maksimum hız sınırı, izin verilen bölgeler, localhost yapılandırılmış CORS ilkesi ve Azure RBAC denetimleri vardır.

Azure CLI ile Azure kaynak dağıtımı

Aşağıdaki adımlarda SAS belirteci kimlik doğrulamasıyla Azure Haritalar hesabı oluşturma ve yapılandırma adımları açıklanmaktadır. Bu örnekte, Azure CLI bir PowerShell örneğinde çalışır.

ile az loginAzure aboneliğinizde oturum açın.

Aboneliğiniz için Key Vault, Yönetilen Kimlikler ve Azure Haritalar kaydedin.

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

Microsoft Entra nesne kimliğinizi alın.

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

Aşağıdaki içeriğe sahip prereq.azuredeploy.json adlı bir şablon dosyası oluşturun:

{
    "$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')]"
        }
    }
}

Önceki adımda oluşturduğunuz önkoşul kaynaklarını dağıtın. için <group-name>kendi değerinizi sağlayın. Azure Haritalar hesabıyla aynı location olduğundan emin olun.

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)

Azure Haritalar hesabını, rol atamasını ve SAS belirtecini sağlamak için azuredeploy.json şablon dosyası oluşturun.

Dekont

1. Nesil fiyatlandırma katmanını kullanımdan kaldırmayı Azure Haritalar

1. Nesil fiyatlandırma katmanı artık kullanım dışıdır ve 15.09.26 tarihinde kullanımdan kaldırılacaktır. 2. Nesil fiyatlandırma katmanı, 1. Nesil (hem S0 hem de S1) fiyatlandırma katmanının yerini alır. Azure Haritalar hesabınızda 1. Nesil fiyatlandırma katmanı seçiliyse kullanımdan kaldırılmadan önce 2. Nesil fiyatlandırmasına geçebilirsiniz, aksi takdirde otomatik olarak güncelleştirilir. Daha fazla bilgi için bkz. Azure Haritalar hesabınızın fiyatlandırma katmanını yönetme.

{
    "$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]"
            }
        }
    ]
}

Şablonu Key Vault'taki kimlik parametreleriyle ve önceki adımda oluşturduğunuz yönetilen kimlik kaynaklarıyla dağıtın. için <group-name>kendi değerinizi sağlayın. SAS belirtecini oluştururken parametresini allowedRegions , westus2ve westcentralusolarak eastusayarlarsınız. Ardından uç noktaya HTTP istekleri göndermek için bu konumları us.atlas.microsoft.com kullanabilirsiniz.

Önemli

Kimlik bilgilerinin Azure dağıtım günlüklerinde görünmesini önlemek için SAS belirtecini anahtar kasasına kaydedersiniz. SAS belirteci gizli dizileri tags , SAS belirtecinin süresinin ne zaman dolacağını göstermek için başlangıç, süre sonu ve imzalama anahtarı adını da içerir.
```
 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"
```

Anahtar Kasası'ndan tek sas belirteci gizli dizisinin bir kopyasını bulun ve kaydedin.

$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)

Azure Haritalar uç noktasına istekte bulunarak SAS belirtecini test edin. Bu örnek, isteğinizin ABD coğrafyasına yönlendirdiğinden emin olmak için öğesini belirtir us.atlas.microsoft.com . SAS belirteciniz ABD coğrafyası içindeki bölgelere izin verir.
```
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"
```

Tam betik örneği

Tam örneği çalıştırmak için aşağıdaki şablon dosyalarının geçerli PowerShell oturumuyla aynı dizinde olması gerekir:

anahtar kasasını ve yönetilen kimliği oluşturmak için prereq.azuredeploy.json .
azuredeploy.json dosyasını kullanarak Azure Haritalar hesabı oluşturun, rol atamasını ve yönetilen kimliği yapılandırın ve SAS belirtecini anahtar kasasında depolayın.

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"

Gerçek dünya örneği

C#, Java veya JavaScript gibi çoğu istemciden Azure Haritalar API'lerine yönelik istekleri çalıştırabilirsiniz. Postman , bir API isteğini seçtiğiniz neredeyse tüm programlama dillerinde veya çerçevelerde temel bir istemci kodu parçacığına dönüştürür. Bu oluşturulan kod parçacığını ön uç uygulamalarınızda kullanabilirsiniz.

Aşağıdaki küçük JavaScript kod örneği, Azure Haritalar bilgileri almak ve döndürmek için Sas belirtecinizi JavaScript Getirme API'siyle nasıl kullanabileceğinizi gösterir. Örnekte Arama Adresi API'sinin sürüm 1.0'ı kullanılır. için <your SAS token>kendi değerinizi sağlayın.

Bu örneğin çalışması için API çağrısıyla aynı kaynaktan allowedOrigins çalıştırdığınızdan emin olun. Örneğin, API çağrısında olarak sağlarsanızhttps://contoso.com, JavaScript betiğini barındıran HTML sayfası olmalıdırhttps://contoso.com.allowedOrigins

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
  });

Kaynakları temizleme

Azure kaynaklarına artık ihtiyacınız kalmadığında bunları silebilirsiniz:

az group delete --name {group-name}

Sonraki adımlar

SAS belirteci kullanan bir Azure Haritalar hesabı oluşturmak için hızlı başlangıç ARM şablonu dağıtın:

Azure Haritalar hesabı oluşturma

Daha ayrıntılı örnekler için bkz:

Microsoft Entra Id için kimlik doğrulama senaryoları

Azure Haritalar hesabınız için API kullanım ölçümlerini bulun:

Kullanım ölçümlerini görüntüleme

Microsoft Entra ID'yi Azure Haritalar ile tümleştirmeyi gösteren örnekleri keşfedin:

Azure Haritalar örnekleri

Aracılığıyla paylaş