Mengonfigurasi autentikasi ID Microsoft Entra untuk kluster Azure Cosmos DB untuk MongoDB vCore

2025-06-09
Berlaku untuk: ✅ MongoDB (vCore)

Dalam artikel ini, Anda mempelajari cara mengonfigurasi autentikasi ID Microsoft Entra untuk Azure Cosmos DB untuk MongoDB vCore. Panduan ini mengatur kluster Azure Cosmos DB untuk MongoDB vCore yang ada agar menggunakan otentikasi ID Microsoft Entra dengan identitas pribadi Anda (akun yang saat ini masuk). Autentikasi ID Microsoft Entra memungkinkan akses yang aman dan mulus ke database Anda dengan menggunakan identitas organisasi Anda yang sudah ada. Panduan ini membahas langkah-langkah untuk menyiapkan autentikasi, mendaftarkan pengguna atau perwakilan layanan, dan memvalidasi konfigurasi.

Prasyarat

Kluster Azure Cosmos DB untuk MongoDB (vCore) yang sudah ada.

Versi terbaru Azure CLI di Azure Cloud Shell.
- Jika Anda lebih suka menjalankan perintah referensi CLI secara lokal, masuk ke Azure CLI dengan menggunakan az login perintah .

Mendapatkan metadata identitas masuk

Pertama, dapatkan ID unik untuk identitas Anda yang sedang masuk.

Peroleh detail akun yang saat ini masuk menggunakan az ad signed-in-user.
```
az ad signed-in-user show
```

Perintah menghasilkan respons JSON yang berisi berbagai bidang.

{
  "@odata.context": "<https://graph.microsoft.com/v1.0/$metadata#users/$entity>",
  "businessPhones": [],
  "displayName": "Kai Carter",
  "givenName": "Kai",
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "jobTitle": "Senior Sales Representative",
  "mail": "<kai@adventure-works.com>",
  "mobilePhone": null,
  "officeLocation": "Redmond",
  "preferredLanguage": null,
  "surname": "Carter",
  "userPrincipalName": "<kai@adventure-works.com>"
}

Catat nilai id properti . Properti ini adalah pengidentifikasi unik untuk prinsipal Anda dan terkadang disebut sebagai ID prinsipal. Anda menggunakan nilai ini dalam rangkaian langkah berikutnya.

Mengonfigurasi kluster yang ada untuk autentikasi

Saat Anda membuat kluster Azure Cosmos DB for MongoDB vCore, kluster dikonfigurasi untuk autentikasi asli secara default. Gunakan Azure CLI untuk mengonfigurasi kluster yang ada untuk mendukung autentikasi ID Microsoft Entra. Kemudian, konfigurasikan kluster untuk memetakan pengguna ke identitas yang telah Anda gunakan saat masuk.

Sekarang, dapatkan authConfig atribut dari kluster yang sudah ada menggunakan az resource show.

az resource show \
    --resource-group "<resource-group-name>" \
    --name "<cluster-name>" \
    --resource-type "Microsoft.DocumentDB/mongoClusters" \
    --query "properties.authConfig" \
    --latest-include-preview

Amati output. Jika autentikasi ID Microsoft Entra tidak dikonfigurasi, output hanya menyertakan nilai NativeAuth dalam array allowedModes.
```
{
  "allowedModes": [
    "NativeAuth"
  ]
}
```

Kemudian, perbarui kluster yang ada dengan operasi HTTP PATCH dengan menambahkan nilai MicrosoftEntraID ke allowedModes.

az resource patch \
    --resource-group "<resource-group-name>" \
    --name "<cluster-name>" \
    --resource-type "Microsoft.DocumentDB/mongoClusters" \
    --properties '{"authConfig":{"allowedModes":["MicrosoftEntraID","NativeAuth"]}}' \
    --latest-include-preview

Petunjuk / Saran

Jika Anda menggunakan Azure Cloud Shell, Anda dapat mengunggah/mengunduh file langsung ke shell. Untuk informasi selengkapnya, lihat file terkelola di Azure Cloud Shell.

Selain itu, jika Anda lebih suka menggunakan Azure REST API secara langsung dengan az rest, gunakan perintah alternatif ini:

az rest \
    --method "PUT" \
    --url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>?api-version=2025-04-01-preview" \
    --body '{"location":"<cluster-region>","properties":{"authConfig":{"allowedModes":["MicrosoftEntraID","NativeAuth"]}}}'

Validasi bahwa konfigurasi berhasil dengan menggunakan az resource show lagi dan mengamati seluruh konfigurasi kluster yang mencakup properties.authConfig.

az resource show \
    --resource-group "<resource-group-name>" \
    --name "<cluster-name>" \
    --resource-type "Microsoft.DocumentDB/mongoClusters" \
    --latest-include-preview

{
  ...
  "properties": {
    ...
    "authConfig": {
      "allowedModes": [
        "MicrosoftEntraID",
        "NativeAuth"
      ]
    },
    ...
  },
  ...
}

Gunakan az resource create untuk membuat sumber daya baru jenis Microsoft.DocumentDB/mongoClusters/users. Buat nama sumber daya dengan menggabungkan nama kluster induk dan ID utama identitas Anda.

az resource create \
    --resource-group "<resource-group-name>" \
    --name "<cluster-name>/users/<principal-id>" \
    --resource-type "Microsoft.DocumentDB/mongoClusters/users" \
    --location "<cluster-region>" \
    --properties '{"identityProvider":{"type":"MicrosoftEntraID","properties":{"principalType":"User"}},"roles":[{"db":"admin","role":"dbOwner"}]}' \
    --latest-include-preview

Petunjuk / Saran

Misalnya, jika sumber daya induk Anda diberi nama example-cluster dan ID utama Anda adalah aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb, nama sumber dayanya adalah:

"example-cluster/users/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"

Selain itu, jika Anda mendaftarkan prinsipal layanan, seperti identitas terkelola, Anda akan mengganti nilai properti identityProvider.properties.principalType dengan ServicePrincipal.

Terakhir, jika Anda lebih suka menggunakan Azure REST API secara langsung dengan az rest, gunakan perintah alternatif ini:

az rest \
    --method "PUT" \
    --url "https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>/users/<principal-id>?api-version=2025-04-01-preview" \
    --body '{"location":"<cluster-region>","properties":{"identityProvider":{"type":"MicrosoftEntraID","properties":{"principalType":"User"}},"roles":[{"db":"admin","role":"dbOwner"}]}}'

Nota

Pengguna ID Microsoft Entra yang ditambahkan ke kluster akan menjadi selain pengguna DocumentDB asli yang ditentukan pada kluster yang sama. Kluster Azure Cosmos DB for MongoDB vCore dibuat dengan setidaknya satu pengguna DocumentDB asli bawaan. Anda dapat menambahkan lebih banyak pengguna DocumentDB asli setelah provisi kluster selesai.

Menyambungkan ke kluster

Anda dapat terhubung ke kluster menggunakan URI koneksi atau objek pengaturan kustom dari driver untuk bahasa pilihan Anda. Dalam salah satu opsi, skema harus diatur ke mongodb+srv untuk menyambungkan ke kluster. Host berada di *.global.mongocluster.cosmos.azure.com domain atau *.mongocluster.cosmos.azure.com tergantung pada apakah Anda menggunakan kluster saat ini atau titik akhir baca-tulis global. Skema +srv dan host *.global.* memastikan bahwa klien Anda tetap terhubung secara dinamis ke kluster yang sesuai untuk penulisan dalam konfigurasi multi-kluster, bahkan jika terjadi operasi pertukaran wilayah. Dalam konfigurasi kluster tunggal, Anda dapat menggunakan salah satu host secara tidak sembarangan.

Pengaturan tls harus diaktifkan juga. Pengaturan yang tersisa yang direkomendasikan adalah konfigurasi praktik terbaik.

Opsi	Nilai
skema	`mongodb+srv`
tuan rumah	`<cluster-name>.global.mongocluster.cosmos.azure.com` atau `<cluster-name>.mongocluster.cosmos.azure.com`
`tls`	`true`
`authMechanism`	`MONGODB-OIDC`
`retrywrites`	`false`
`maxIdleTimeMS`	`120000`

Pada halaman properti kluster di portal Microsoft Azure, di bawah Pengaturan, buka String koneksi. Halaman String koneksi berisi string koneksi untuk metode autentikasi yang diaktifkan pada kluster. String koneksi ID Microsoft Entra berada di bagian ID Microsoft Entra .

Global

mongodb+srv://<cluster-name>.global.mongocluster.cosmos.azure.com/?tls=true&authMechanism=MONGODB-OIDC&retrywrites=false&maxIdleTimeMS=120000

Kluster

mongodb+srv://<cluster-name>.mongocluster.cosmos.azure.com/?tls=true&authMechanism=MONGODB-OIDC&retrywrites=false&maxIdleTimeMS=120000

const AzureIdentityTokenCallback = async (params: OIDCCallbackParams, credential: TokenCredential): Promise<OIDCResponse> => {
    const tokenResponse: AccessToken | null = await credential.getToken(['https://ossrdbms-aad.database.windows.net/.default']);
    return {
        accessToken: tokenResponse?.token || '',
        expiresInSeconds: (tokenResponse?.expiresOnTimestamp || 0) - Math.floor(Date.now() / 1000)
    };
};

const clusterName: string = '<azure-cosmos-db-mongodb-vcore-cluster-name>';

const credential: TokenCredential = new DefaultAzureCredential();

const client = new MongoClient(
    `mongodb+srv://${clusterName}.global.mongocluster.cosmos.azure.com/`, {
    connectTimeoutMS: 120000,
    tls: true,
    retryWrites: true,
    authMechanism: 'MONGODB-OIDC',
    authMechanismProperties: {
        OIDC_CALLBACK: (params: OIDCCallbackParams) => AzureIdentityTokenCallback(params, credential),
        ALLOWED_HOSTS: ['*.azure.com']
    }
}
);

class AzureIdentityTokenCallback(OIDCCallback):
    def __init__(self, credential):
        self.credential = credential

    def fetch(self, context: OIDCCallbackContext) -> OIDCCallbackResult:
        token = self.credential.get_token(
            "https://ossrdbms-aad.database.windows.net/.default").token
        return OIDCCallbackResult(access_token=token)

clusterName = "<azure-cosmos-db-mongodb-vcore-cluster-name>"

credential = DefaultAzureCredential()
authProperties = {"OIDC_CALLBACK": AzureIdentityTokenCallback(credential)}

client = MongoClient(
    f"mongodb+srv://{clusterName}.global.mongocluster.cosmos.azure.com/",
    connectTimeoutMS=120000,
    tls=True,
    retryWrites=True,
    authMechanism="MONGODB-OIDC",
    authMechanismProperties=authProperties
)

string tenantId = "<microsoft-entra-tenant-id>";
string clusterName = "<azure-cosmos-db-mongodb-vcore-cluster-name>";

DefaultAzureCredential credential = new();
AzureIdentityTokenHandler tokenHandler = new(credential, tenantId);

MongoUrl url = MongoUrl.Create($"mongodb+srv://{clusterName}.global.mongocluster.cosmos.azure.com/");
MongoClientSettings settings = MongoClientSettings.FromUrl(url);
settings.UseTls = true;
settings.RetryWrites = false;
settings.MaxConnectionIdleTime = TimeSpan.FromMinutes(2);
settings.Credential = MongoCredential.CreateOidcCredential(tokenHandler);
settings.Freeze();

MongoClient client = new(settings);

internal sealed class AzureIdentityTokenHandler(
    TokenCredential credential,
    string tenantId
) : IOidcCallback
{
    private readonly string[] scopes = ["https://ossrdbms-aad.database.windows.net/.default"];

    public OidcAccessToken GetOidcAccessToken(OidcCallbackParameters parameters, CancellationToken cancellationToken)
    {
        AccessToken token = credential.GetToken(
            new TokenRequestContext(scopes, tenantId: tenantId),
            cancellationToken
        );

        return new OidcAccessToken(token.Token, token.ExpiresOn - DateTimeOffset.UtcNow);
    }

    public async Task<OidcAccessToken> GetOidcAccessTokenAsync(OidcCallbackParameters parameters, CancellationToken cancellationToken)
    {
        AccessToken token = await credential.GetTokenAsync(
            new TokenRequestContext(scopes, parentRequestId: null, tenantId: tenantId),
            cancellationToken
        );

        return new OidcAccessToken(token.Token, token.ExpiresOn - DateTimeOffset.UtcNow);
    }
}

Autentikasi ID Microsoft Entra di Azure Cosmos DB untuk gambaran umum MongoDB vCore
Periksa batasan ID Microsoft Entra di Azure Cosmos DB untuk MongoDB vCore
Menyambungkan menggunakan aplikasi konsol

Bagikan melalui

Mengonfigurasi autentikasi ID Microsoft Entra untuk kluster Azure Cosmos DB untuk MongoDB vCore

Prasyarat

Mendapatkan metadata identitas masuk

Mengonfigurasi kluster yang ada untuk autentikasi

Menyambungkan ke kluster

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: