Configurare l'autenticazione con Microsoft Entra ID per un cluster di Azure Cosmos DB vCore per MongoDB

2025-06-09
Si applica a: ✅ MongoDB (vCore)

In questo articolo, imparerai come configurare l'autenticazione di Microsoft Entra ID per un Azure Cosmos DB per MongoDB vCore. Questa guida consente di configurare un cluster vCore di Azure Cosmos DB per MongoDB per l'uso dell'autenticazione tramite Microsoft Entra ID con la tua identità utente (account al momento connesso). L'autenticazione di Microsoft Entra ID consente l'accesso sicuro e facile al database usando le identità esistenti dell'organizzazione. Questa guida illustra i passaggi per configurare l'autenticazione, registrare utenti o entità servizio e convalidare la configurazione.

Prerequisiti

Un cluster esistente di Azure Cosmos DB per MongoDB (vCore).

Versione più recente dell'interfaccia della riga di comando di Azure in Azure Cloud Shell.
- Se si preferisce eseguire i comandi CLI di riferimento in locale, accedere all'interfaccia della riga di comando di Azure usando il comando az login.

Ottenere i metadati di identità autenticata

Innanzitutto, ottieni l'identificatore univoco per l'identità attualmente connessa.

Ottenere i dettagli per l'account attualmente connesso usando az ad signed-in-user.
```
az ad signed-in-user show
```

Il comando restituisce una risposta JSON contenente vari campi.

{
  "@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>"
}

Registrare il valore della id proprietà . Questa proprietà è l'identificatore univoco per il principale e a volte viene definito ID principale. Questo valore viene usato nella serie successiva di passaggi.

Configurare un cluster esistente per l'autenticazione

Quando si crea un cluster vCore di Azure Cosmos DB per MongoDB, il cluster viene configurato per l'autenticazione nativa per impostazione predefinita. Usare l'interfaccia della riga di comando di Azure per configurare il cluster esistente per supportare l'autenticazione di Microsoft Entra ID. Quindi, configura il cluster per associare un utente alla tua identità di accesso.

Ora, ottieni la proprietà authConfig dal tuo cluster esistente utilizzando 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

Osservare l'output. Se l'autenticazione dell'ID Entra di Microsoft non è configurata, l'output include solo il NativeAuth valore nella allowedModes matrice.
```
{
  "allowedModes": [
    "NativeAuth"
  ]
}
```

Aggiornare quindi il cluster esistente con un'operazione HTTP PATCH aggiungendo il MicrosoftEntraID valore a 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

Suggerimento

Se si usa Azure Cloud Shell, è possibile caricare/scaricare file direttamente nella shell. Per altre informazioni, vedere File gestiti in Azure Cloud Shell.

Inoltre, se si preferisce usare direttamente l'API REST di Azure con az rest, usare questo comando alternativo:

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

Verificare che la configurazione sia riuscita usando az resource show di nuovo e osservando la configurazione dell'intero cluster che include 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"
      ]
    },
    ...
  },
  ...
}

Usare az resource create per creare una nuova risorsa di tipo Microsoft.DocumentDB/mongoClusters/users. Componi il nome della risorsa concatenando il nome del cluster padre e l'ID principale dell'identità.

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

Suggerimento

Ad esempio, se la vostra risorsa padre è chiamata example-cluster e il vostro ID principale era aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb, il nome della risorsa sarebbe:

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

Inoltre, se si registra un principale del servizio, come un'identità gestita, si dovrebbe sostituire il valore della proprietà identityProvider.properties.principalType con ServicePrincipal.

Infine, se si preferisce usare direttamente l'API REST di Azure con az rest, usare questo comando alternativo:

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

Annotazioni

Gli utenti di Microsoft Entra ID aggiunti al cluster saranno oltre agli utenti nativi di DocumentDB definiti nello stesso cluster. Viene creato un cluster vCore di Azure Cosmos DB per MongoDB con almeno un utente nativo di DocumentDB predefinito. È possibile aggiungere altri utenti nativi di DocumentDB al termine del provisioning del cluster.

Connettersi al cluster

È possibile connettersi al cluster usando un URI di connessione o un oggetto impostazioni personalizzato dal driver per la lingua preferita. In entrambe le opzioni, lo schema deve essere impostato su mongodb+srv per connettersi al cluster. L'host si trova nel *.global.mongocluster.cosmos.azure.com dominio o *.mongocluster.cosmos.azure.com a seconda che si usi il cluster corrente o l'endpoint di lettura/scrittura globale. Lo +srv schema e l'host assicurano che il *.global.* client sia connesso dinamicamente al cluster scrivibile appropriato in una configurazione multi-cluster anche se si verifica un'operazione di scambio di aree. In una configurazione a cluster singolo è possibile usare entrambi gli host in modo indiscriminato.

L'impostazione tls deve essere abilitata anche. Le impostazioni consigliate rimanenti sono le impostazioni di configurazione consigliate.

Opzione	Valore
schema	`mongodb+srv`
server	`<cluster-name>.global.mongocluster.cosmos.azure.com` o `<cluster-name>.mongocluster.cosmos.azure.com`
`tls`	`true`
`authMechanism`	`MONGODB-OIDC`
`retrywrites`	`false`
`maxIdleTimeMS`	`120000`

Nella pagina delle proprietà del cluster nel portale di Azure aprire Stringhe di connessione in Impostazioni. La pagina Stringhe di connessione contiene stringhe di connessione per i metodi di autenticazione abilitati nel cluster. Le stringhe di connessione microsoft Entra ID si trovano nella sezione Microsoft Entra ID .

Globale

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

Cluster

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

Panoramica dell'autenticazione di Microsoft Entra ID in Azure Cosmos DB per MongoDB vCore
Controllare le limitazioni dell'ID Microsoft Entra in Azure Cosmos DB per MongoDB vCore
Connettersi con un'applicazione console

Condividi tramite

Configurare l'autenticazione con Microsoft Entra ID per un cluster di Azure Cosmos DB vCore per MongoDB

Prerequisiti

Ottenere i metadati di identità autenticata

Configurare un cluster esistente per l'autenticazione

Connettersi al cluster

Contenuti correlati

Commenti e suggerimenti

Risorse aggiuntive