Edit

Menggunakan identitas terkelola yang ditetapkan sistem untuk mengakses data Azure Cosmos DB

  • Bagaimana

BERLAKU UNTUK: NoSQL

Dalam artikel ini, Anda akan menyiapkan solusi canggih, agnostik rotasi kunci untuk mengakses kunci Azure Cosmos DB menggunakan identitas terkelola dan kontrol akses berbasis peran bidang data. Contoh dalam artikel ini menggunakan Azure Functions, tetapi Anda bisa menggunakan layanan apa pun yang mendukung identitas terkelola.

Anda akan mempelajari cara membuat aplikasi fungsi yang dapat mengakses data Azure Cosmos DB tanpa perlu menyalin tombol DB Azure Cosmos apa pun. Aplikasi fungsi akan terpicu saat permintaan HTTP dibuat dan kemudian mencantumkan semua database yang ada.

Prasyarat

  • Akun Azure dengan langganan aktif. Buat akun secara gratis.

  • API Azure Cosmos DB yang ada untuk akun NoSQL. Membuat API Azure Cosmos DB untuk akun NoSQL

  • Aplikasi fungsi Azure Functions yang ada. Membuat fungsi pertama Anda di portal Azure

  • Azure Functions Core Tools

  • Untuk melakukan langkah-langkah dalam artikel ini, instal Azure CLI dan masuk ke Azure.

    Pemeriksaan prasyarat

    1. Di terminal atau jendela perintah, simpan nama aplikasi fungsi Azure Functions Anda, akun Azure Cosmos DB, dan grup sumber daya sebagai variabel shell bernama functionName, cosmosName, dan resourceGroupName.

      # Variable for function app name
functionName="msdocs-function-app"

# Variable for Azure Cosmos DB account name
cosmosName="msdocs-cosmos-app"

# Variable for resource group name
resourceGroupName="msdocs-cosmos-functions-dotnet-identity"

      Catatan

      Variabel-variabel ini akan digunakan kembali pada langkah selanjutnya. Contoh ini mengasumsikan nama akun Azure Cosmos DB Anda adalah msdocs-cosmos-app, nama aplikasi fungsi Anda adalah msdocs-function-app dan nama grup sumber daya Anda adalah msdocs-cosmos-functions-dotnet-identity.

    2. Lihat properti aplikasi fungsi menggunakan perintah az functionapp show.

      az functionapp show \
    --resource-group $resourceGroupName \
    --name $functionName

    3. Lihat properti identitas terkelola yang ditetapkan sistem untuk aplikasi fungsi Anda menggunakan az webapp identity show.

      az webapp identity show \
    --resource-group $resourceGroupName \
    --name $functionName

    4. Lihat properti akun Azure Cosmos DB menggunakan az cosmosdb show.

      az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $cosmosName

Membuat API Azure Cosmos DB untuk database NoSQL

Pada langkah ini, Anda akan membuat dua database.

  1. Di jendela terminal atau perintah, buat database products baru menggunakan az cosmosdb sql database create.

    az cosmosdb sql database create \
    --resource-group $resourceGroupName \
    --name products \
    --account-name $cosmosName

  2. Buat database customers baru.

    az cosmosdb sql database create \
    --resource-group $resourceGroupName \
    --name customers \
    --account-name $cosmosName

Mendapatkan API Azure Cosmos DB untuk titik akhir NoSQL

Dalam langkah ini, Anda akan mengkueri titik akhir dokumen untuk API untuk akun NoSQL.

  1. Gunakan az cosmosdb show dengan parameter kueri yang diatur ke documentEndpoint. Catat hasilnya. Anda akan menggunakan nilai ini di langkah selanjutnya.

    az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $cosmosName \
    --query documentEndpoint

cosmosEndpoint=$(
    az cosmosdb show \
        --resource-group $resourceGroupName \
        --name $cosmosName \
        --query documentEndpoint \
        --output tsv
)

echo $cosmosEndpoint

    Catatan

    Variabel ini akan digunakan kembali pada langkah selanjutnya.

Memberikan akses ke akun Azure Cosmos DB Anda

Dalam langkah ini, Anda akan menetapkan peran ke identitas terkelola yang ditetapkan sistem aplikasi fungsi. Azure Cosmos DB memiliki beberapa peran bawaan yang dapat Anda tetapkan ke identitas terkelola untuk akses sarana kontrol. Untuk akses data-plane, Anda akan membuat peran kustom baru dengan akses untuk membaca metadata.

Tip

Untuk informasi selengkapnya tentang pentingnya akses hak istimewa minimal, lihat artikel Ekspos lebih rendah akun dengan hak istimewa.

  1. Gunakan az cosmosdb show dengan parameter kueri yang diatur ke id. Simpan hasilnya dalam variabel shell bernama scope.

    scope=$(
    az cosmosdb show \
        --resource-group $resourceGroupName \
        --name $cosmosName \
        --query id \
        --output tsv
)

echo $scope

    Catatan

    Variabel ini akan digunakan kembali pada langkah selanjutnya.

  2. Gunakan az webapp identity show dengan parameter kueri yang diatur ke principalId. Simpan hasilnya dalam variabel shell bernama principal.

    principal=$(
    az webapp identity show \
        --resource-group $resourceGroupName \
        --name $functionName \
        --query principalId \
        --output tsv
)

echo $principal

  3. Buat file JSON baru dengan konfigurasi peran kustom baru.

    {
    "RoleName": "Read Azure Cosmos DB Metadata",
    "Type": "CustomRole",
    "AssignableScopes": ["/"],
    "Permissions": [{
        "DataActions": [
            "Microsoft.DocumentDB/databaseAccounts/readMetadata"
        ]
    }]
}

    Tip

    Anda dapat membuat file di Azure Cloud Shell menggunakan editor touch <filename> bawaan (code .). Untuk informasi selengkapnya, lihat Editor Azure Cloud Shell

  4. Gunakan az cosmosdb sql role definition create untuk membuat definisi peran baru bernama Read Azure Cosmos DB Metadata menggunakan objek JSON kustom.

    az cosmosdb sql role definition create \
    --resource-group $resourceGroupName \
    --account-name $cosmosName \
    --body @definition.json

    Catatan

    Dalam contoh ini, definisi peran ditentukan dalam file bernama definition.json.

  5. Gunakan az role assignment create untuk menetapkan peran Read Azure Cosmos DB Metadata ke identitas terkelola yang ditetapkan sistem.

    az cosmosdb sql role assignment create \
    --resource-group $resourceGroupName \
    --account-name $cosmosName \
    --role-definition-name "Read Azure Cosmos DB Metadata" \
    --principal-id $principal \
    --scope $scope

Mengakses kunci Azure Cosmos DB secara terprogram

Kami sekarang memiliki aplikasi fungsi yang memiliki identitas terkelola yang ditetapkan sistem dengan peran kustom. Aplikasi fungsi berikut akan meminta akun Azure Cosmos DB untuk daftar database.

  1. Buat proyek fungsi lokal dengan parameter --dotnet dalam folder bernama csmsfunc. Ubah direktori shell Anda

    func init csmsfunc --dotnet

cd csmsfunc

  2. Buat fungsi baru dengan parameter templat diatur ke httptrigger dan nama diatur ke readdatabases.

    func new --template httptrigger --name readdatabases

  3. Tambahkan paket Azure.Identity dan Microsoft.Azure.Cosmos NuGet ke proyek .NET. Bangun proyek menggunakan dotnet build.

    dotnet add package Azure.Identity

dotnet add package Microsoft.Azure.Cosmos

dotnet build

  4. Buka kode fungsi di lingkungan pengembang terintegrasi (IDE).

    Tip

    Jika Anda menggunakan Azure CLI secara lokal atau di Azure Cloud Shell, Anda dapat membuka Visual Studio Code.

    code .

  5. Ganti kode dalam file readdatabases.cs dengan contoh implementasi fungsi ini. Simpan file yang diperbarui.

    using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Azure.Identity;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Cosmos;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;

namespace csmsfunc
{
    public static class readdatabases
    {
        [FunctionName("readdatabases")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequest req,
            ILogger log)
        {
            log.LogTrace("Start function");

            CosmosClient client = new CosmosClient(
                accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT", EnvironmentVariableTarget.Process),
                new DefaultAzureCredential()
            );

            using FeedIterator<DatabaseProperties> iterator = client.GetDatabaseQueryIterator<DatabaseProperties>();

            List<(string name, string uri)> databases = new();
            while(iterator.HasMoreResults)
            {
                foreach(DatabaseProperties database in await iterator.ReadNextAsync())
                {
                    log.LogTrace($"[Database Found]\t{database.Id}");
                    databases.Add((database.Id, database.SelfLink));
                }
            }

            return new OkObjectResult(databases);
        }
    }
}

(Opsional) Menjalankan fungsi secara lokal

Di lingkungan lokal, kelas DefaultAzureCredential akan menggunakan berbagai kredensial lokal untuk menentukan identitas saat ini. Meskipun menjalankan secara lokal tidak diperlukan untuk petunjuk, Anda dapat mengembangkan secara lokal menggunakan identitas Anda sendiri atau perwakilan layanan.

  1. Dalam file local.settings.json, tambahkan setelan baru bernama COSMOS_ENDPOINT di objek Nilai. Nilai pengaturan harus menjadi titik akhir dokumen yang Anda rekam sebelumnya dalam panduan cara ini.

    ...
"Values": {
    ...
    "COSMOS_ENDPOINT": "https://msdocs-cosmos-app.documents.azure.com:443/",
    ...
}
...

    Catatan

    Objek JSON ini telah dipersingkat untuk keringkasan. Objek JSON ini juga menyertakan nilai sampel yang mengasumsikan nama akun Anda adalah msdocs-cosmos-app.

  2. Jalankan aplikasi fungsi

    func start

Menyebarkan ke Azure

Setelah diterbitkan, DefaultAzureCredential kelas akan menggunakan kredensial dari lingkungan atau identitas terkelola. Untuk panduan ini, identitas terkelola yang ditetapkan sistem akan digunakan sebagai kredensial untuk konstruktor CosmosClient.

  1. Atur COSMOS_ENDPOINT pengaturan pada aplikasi fungsi yang sudah disebarkan di Azure.

    az functionapp config appsettings set \
    --resource-group $resourceGroupName \
    --name $functionName \
    --settings "COSMOS_ENDPOINT=$cosmosEndpoint"

  2. Sebarkan aplikasi fungsi Anda ke Azure dengan menggunakan kembali variabel shell functionName:

    func azure functionapp publish $functionName

  3. Menguji fungsi di portal Azure.

Konten terkait