مشاركة عبر

تأمين حساب خرائط Azure باستخدام رمز SAS المميز

  • مقالة

توضح هذه المقالة كيفية إنشاء حساب خرائط Azure برمز SAS مخزن بشكل آمن يمكنك استخدامه لاستدعاء واجهة برمجة تطبيقات REST لخرائط Azure.

المتطلبات الأساسية

  • اشتراك Azure. إذا لم يكن لديك حساب Azure بالفعل، فقم بالتسجيل للحصول على حساب مجاني.

  • أذونات دور المالك على اشتراك Azure. تحتاج إلى أذونات المالك من أجل:

    • إنشاء مخزن رئيسي في Azure Key Vault.
    • إنشاء هوية مُدارة يُعينها المستخدم.
    • تعيين دور للهوية المدارة.
    • أنشئ حساب خرائط Azure.

  • تم تثبيت Azure CLI لتوزيع الموارد.

مثال على السيناريو: التخزين الآمن لرمز SAS المميز

تمنح بيانات اعتماد رمز SAS المميز مستوى الوصول الذي تحدده لأي شخص يحتفظ به، حتى تنتهي صلاحية الرمز المميز أو يتم إبطال الوصول. يجب أن تخزن التطبيقات التي تستخدم مصادقة رمز SAS المميز المفاتيح بشكل آمن.

يخزن هذا السيناريو بأمان رمز SAS المميز باعتباره سرًا في Key Vault، ويوزع الرمز المميز في عميل عام. يمكن أن تنشئ أحداث دورة حياة التطبيق رموز SAS مميزة جديدة دون مقاطعة الاتصالات النشطة التي تستخدم الرموز المميزة الموجودة.

لمزيد من المعلومات حول تكوين Key Vault، راجع دليل مطور Azure Key Vault.

يستخدم السيناريو المثال التالي اثنتين من عمليات توزيع قالب Azure Resource Manager (ARM) للقيام بالخطوات التالية:

  1. إنشاء مخزن رئيسي.
  2. إنشاء هوية مُدارة يُعينها المستخدم.
  3. تعيين التحكم في الوصول المستند إلى دور Azure (RBAC) المسمى قارئ بيانات خرائط Azure إلى الهوية المدارة المعينة من قبل المستخدم.
  4. إنشاء حساب خرائط Azure مع تكوين مشاركة الموارد عبر المصادر (CORS) وإرفاق الهوية المدارة المعينة من قِبل المستخدم.
  5. إنشاء رمز SAS المميز وحفظه في مخزن مفاتيح Azure.
  6. استرداد سر رمز SAS المميز من مخزن المفاتيح.
  7. إنشاء طلب واجهة برمجة تطبيقات REST لخرائط Azure يستخدم رمز SAS المميز.

عند الانتهاء، يجب أن تشاهد نتائج واجهة برمجة تطبيقات REST Search Address (Non-Batch) لخرائط Azure على PowerShell باستخدام Azure CLI. يتم توزيع موارد Azure بأذونات للاتصال بحساب خرائط Azure. هناك عناصر تحكم للحد الأقصى للمعدل والمناطق المسموح بها ونهج CORS الذي تم تكوينه localhost وAzure RBAC.

توزيع موارد Azure باستخدام Azure CLI

تصف الخطوات التالية كيفية إنشاء حساب خرائط Azure وتكوينه باستخدام مصادقة رمز SAS المميز. في هذا المثال، يتم تشغيل Azure CLI في مثيل PowerShell.

  1. قم بتسجيل الدخول إلى اشتراكك في Azure باستخدام az login.

  2. سجِّل Key Vault والهويات المدارة وخرائط Azure لاشتراكك.

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

  3. استرداد معرف كائن Microsoft Entra.

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

  4. قم بإنشاء ملف قالب باسم prereq.azuredeploy.json بالمحتوى التالي:

    {
    "$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. وزِّع الموارد الأساسية التي قمت بإنشائها في الخطوة السابقة. قم بتوفير القيمة الخاصة بك لـ <group-name>. تأكد من استخدام نفس location كحساب خرائط Azure.

    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. أنشئ ملف قالب azuredeploy.json لتوفير حساب خرائط Azure وتعيين الدور ورمز SAS المميز.

    إشعار

    إيقاف مستوى تسعير خرائط Azure Gen1

    تم الآن إهمال مستوى تسعير Gen1 وسيتم إيقافه في 9/15/26. يحل مستوى تسعير Gen2 محل مستوى تسعير Gen1 (كل من S0 وS1). إذا تم تحديد مستوى تسعير Gen1 لحساب خرائط Azure الخاص بك، يمكنك التبديل إلى تسعير Gen2 قبل إيقافه، وإلا تحديثه تلقائيا. لمزيد من المعلومات، راجع إدارة مستوى التسعير لحساب خرائط Azure الخاص بك.

    {
    "$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. وزِّع القالب باستخدام معلمات المعرف من Key Vault وموارد الهوية المدارة التي أنشأتها في الخطوة السابقة. قم بتوفير القيمة الخاصة بك لـ <group-name>. عند إنشاء رمز SAS المميز، يمكنك تعيين المعلمة allowedRegions إلى eastus وwestus2 وwestcentralus. يمكنك بعد ذلك استخدام هذه المواقع لتقديم طلبات HTTP إلى نقطة نهاية us.atlas.microsoft.com.

    هام

    يمكنك حفظ رمز SAS المميز في مخزن المفاتيح لمنع بيانات الاعتماد الخاصة به من الظهور في سجلات توزيع Azure. يحتوي سر رمز SAS المميز tags أيضاً على اسم مفتاح البدء وانتهاء الصلاحية والتوقيع، لإظهار وقت انتهاء صلاحية رمز SAS المميز.

     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. حدد موقع نسخة من سر رمز SAS المميز الفردي، واحفظه من 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. اختبر رمز SAS المميز عن طريق تقديم طلب إلى نقطة نهاية خرائط Azure. يحدد هذا المثال us.atlas.microsoft.com لضمان توجيه طلبك إلى جغرافيا الولايات المتحدة. يسمح رمز SAS المميز الخاص بك بالمناطق داخل جغرافيا الولايات المتحدة.

    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"

مثال البرنامج النصي الكامل

لتشغيل المثال الكامل، يجب أن تكون ملفات القالب التالية في نفس الدليل، مثل جلسة عمل PowerShell الحالية:

  • prereq.azuredeploy.json لإنشاء مخزن مفاتيح وهوية مدارة.
  • azuredeploy.json لإنشاء حساب خرائط Azure وتكوين تعيين الدور والهوية المدارة وتخزين رمز SAS المميز في مخزن المفاتيح.
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"

مثال من العالم الحقيقي

يمكنك تشغيل الطلبات إلى واجهة برمجة التطبيقات لخرائط Azure من معظم العملاء، مثل C#، أو Java، أو JavaScript. يمكن لمنصات تطوير واجهة برمجة التطبيقات مثل bruno أو Postman تحويل طلب واجهة برمجة التطبيقات إلى قصاصة برمجية أساسية للعميل في أي لغة برمجة أو إطار عمل تختاره تقريبا. يمكنك استخدام القصاصات البرمجية التي تم إنشاؤها في تطبيقات الواجهة الأمامية.

يوضح مثال التعليمات البرمجية JavaScript الصغير التالي كيف يمكنك استخدام رمز SAS المميز الخاص بك باستخدام واجهة برمجة تطبيقات Fetch لـ JavaScript للحصول على معلومات خرائط Azure وإعادتها. يستخدم المثال Get Search Address API الإصدار 1.0. قم بتوفير القيمة الخاصة بك لـ <your SAS token>.

لكي يعمل هذا النموذج، تأكد من تشغيله من داخل نفس الأصل، مثل allowedOrigins لاستدعاء واجهة برمجة التطبيقات. على سبيل المثال، إذا قمت بتوفير https://contoso.com كـ allowedOrigins في استدعاء واجهة برمجة التطبيقات، يجب أن تكون صفحة HTML التي تستضيف البرنامج النصي JavaScript هي 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
  });

تنظيف الموارد

عندما لم تعد بحاجة إلى موارد Azure، يمكنك حذفها:

az group delete --name {group-name}

الخطوات التالية

وزِّع قالب ARM لبدء التشغيل السريع لإنشاء حساب خرائط Azure يستخدم رمز SAS المميز:

أنشئ حساب خرائط Azure

للحصول على أمثلة أكثر تفصيلاً، راجع:

سيناريوهات المصادقة لمعرف Microsoft Entra

ابحث عـن مقاييس استخدام واجهة برمجة التطبيقات لحساب خرائط Azure:

عرض مقاييس الاستخدام

استكشف العينات التي توضح كيفية دمج معرف Microsoft Entra مع خرائط Azure:

عينات خرائط Azure الخاصة