Referentieketens in de Azure Identity-clientbibliotheek voor Go

De Azure Identity clientbibliotheek biedt referenties— openbare typen om de TokenCredential- interface van de Azure Core-bibliotheek te implementeren. Een referentie vertegenwoordigt een afzonderlijke verificatiestroom voor het verkrijgen van een toegangstoken van Microsoft Entra ID. Deze referenties kunnen worden gekoppeld om een geordende reeks verificatiemechanismen te vormen die moeten worden geprobeerd.

Hoe een gekoppelde inloggegevens werkt

Tijdens runtime probeert een referentieketen te verifiëren met behulp van de eerste referentie van de reeks. Als deze referentie geen toegangstoken kan verkrijgen, wordt de volgende referentie in de reeks geprobeerd, enzovoort, totdat een toegangstoken is verkregen. In het volgende sequentiediagram ziet u dit gedrag:

Waarom referentieketens gebruiken

Een gekoppelde referentie kan de volgende voordelen bieden:

• omgevingsbewustzijn: selecteert automatisch de meest geschikte referentie op basis van de omgeving waarin de app wordt uitgevoerd. Zonder deze code moet u als volgt code schrijven:

  // Set up credential based on environment (Azure or local development)
  if os.Getenv("WEBSITE_HOSTNAME") != "" {
      clientID := azidentity.ClientID("abcd1234-...")
      opts := azidentity.ManagedIdentityCredentialOptions{ID: clientID}
      cred, err := azidentity.NewManagedIdentityCredential(&opts)
  
      if err != nil {
        // TODO: handle error
      }
  }
  else {
      // Use Azure CLI Credential
      credential, err = azidentity.NewAzureCLICredential(nil)
  
      if err != nil {
        // TODO: handle error
      }
  }
  

• naadloze overgangen: uw app kan overstappen van lokale ontwikkeling naar uw faserings- of productieomgeving zonder verificatiecode te wijzigen.

• Verbeterde veerkracht: bevat een terugvalmechanisme dat overschakelt naar de volgende credential wanneer de vorige geen toegangstoken kan verkrijgen.

Hoe een gekoppelde referentie te kiezen

Met Go zijn er twee opties voor het koppelen van referenties:

• Een vooraf geconfigureerde keten gebruiken: gebruik de vooraf geconfigureerde keten die door het DefaultAzureCredential type is geïmplementeerd. Zie de sectie DefaultAzureCredential-overzicht voor deze aanpak.
• Een aangepaste referentieketen bouwen: Begin met een lege keten en neem alleen op wat u nodig hebt. Zie de sectie ChainedTokenCredential-overzicht voor deze benadering.

Overzicht van DefaultAzureCredential

DefaultAzureCredential- is een vooraf geconfigureerde, vooraf geconfigureerde keten van referenties. Het is ontworpen om veel omgevingen te ondersteunen, samen met de meest voorkomende verificatiestromen en ontwikkelhulpprogramma's. In grafische vorm ziet de onderliggende keten er als volgt uit:

De volgorde waarin DefaultAzureCredential probeert referenties te gebruiken.

Bevelen	Geloofsbrief	Beschrijving
1	Omgeving	Leest een verzameling omgevingsvariabelen om te bepalen of een toepassingsservice-principal (toepassingsgebruiker) is geconfigureerd voor de app. Zo ja, dan gebruikt DefaultAzureCredential deze waarden om de app te verifiëren bij Azure. Deze methode wordt meestal gebruikt in serveromgevingen, maar kan ook worden gebruikt bij het lokaal ontwikkelen.
2	Workload-identiteit	Als de app is geïmplementeerd op een Azure-host waarvoor workloadidentiteit is ingeschakeld, verifieert u dat account.
3	beheerde identiteit	Als de app is geïmplementeerd op een Azure-host waarvoor Managed Identity is ingeschakeld, verifieert u de app bij Azure met behulp van die beheerde identiteit.
4	Azure CLI-	Als de ontwikkelaar is geverifieerd bij Azure met behulp van de opdracht az login van Azure CLI, moet u de app verifiëren bij Azure met hetzelfde account.
5	Azure Developer CLI-	Als de ontwikkelaar zich met de azd auth login-opdracht van Azure Developer CLI heeft aangemeld bij Azure, gebruik dat account voor verificatie.

In de eenvoudigste vorm kunt u de parameterloze versie van DefaultAzureCredential als volgt gebruiken:

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
    )

// create a credential
credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    // TODO: handle error
}

// create a Blob service client 
accountURL := "https://<my_account_name>.blob.core.windows.net"
client, err := azblob.NewClient(accountURL, credential, nil)
if err != nil {
    // TODO: handle error
}

Overzicht ChainedTokenCredential

ChainedTokenCredential is een lege keten waaraan u referenties toevoegt om aan de eisen van uw app te voldoen. Bijvoorbeeld:

managed, err := azidentity.NewManagedIdentityCredential(nil)
if err != nil {
  // handle error
}

azCLI, err := azidentity.NewAzureCLICredential(nil)
if err != nil {
  // handle error
}

chain, err := azidentity.NewChainedTokenCredential([]azcore.TokenCredential{managed, azCLI}, nil)
if err != nil {
  // handle error
}

In het voorgaande codevoorbeeld wordt een aangepaste referentieketen gemaakt die bestaat uit twee referenties. ManagedIdentityCredential wordt eerst geprobeerd, gevolgd door AzureCliCredential, indien nodig. In grafische vorm ziet de keten er als volgt uit:

Tip

Voor betere prestaties optimaliseert u de volgorde van referenties in ChainedTokenCredential voor uw productieomgeving. Referenties die zijn bedoeld voor gebruik in de lokale ontwikkelomgeving, moeten als laatste worden toegevoegd.

Gebruiksrichtlijnen voor DefaultAzureCredential

DefaultAzureCredential is ongetwijfeld de eenvoudigste manier om aan de slag te gaan met de Azure Identity-clientbibliotheek, maar met dat gemak komen ook compromissen. Zodra u uw app in Azure hebt geïmplementeerd, moet u de verificatievereisten van de app begrijpen. Daarom kunt u het beste overstappen van DefaultAzureCredential naar een van de volgende oplossingen:

• Een specifieke referentie-implementatie, zoals ManagedIdentityCredential.
• Een geparseerde ChainedTokenCredential implementatie die is geoptimaliseerd voor de Azure-omgeving waarin uw app wordt uitgevoerd.

Dit is de reden waarom:

• Problemen met foutopsporing: wanneer de verificatie mislukt, kan het lastig zijn om fouten op te sporen en de foutopsporingsreferentie te identificeren. U moet logboekregistratie inschakelen om de voortgang te zien van de ene referentie naar de volgende en de succes-/foutstatus van elke referentie. Zie Fouten opsporen in een gekoppelde referentievoor meer informatie.
• Prestatieoverhead: het proces waarbij meerdere referenties opeenvolgend worden geprobeerd, kan leiden tot prestatieoverhead. Een beheerde identiteit is bijvoorbeeld niet beschikbaar wanneer deze wordt uitgevoerd op een lokale ontwikkelcomputer. Daarom mislukt ManagedIdentityCredential altijd in de lokale ontwikkelomgeving, tenzij deze expliciet is uitgeschakeld via de bijbehorende eigenschap exclude-voorvoegsel.
• onvoorspelbaar gedrag: DefaultAzureCredential controleert op de aanwezigheid van bepaalde omgevingsvariabelen. Het is mogelijk dat iemand deze omgevingsvariabelen kan toevoegen of wijzigen op systeemniveau op de hostcomputer. Deze wijzigingen zijn globaal van toepassing en wijzigen daarom het gedrag van DefaultAzureCredential tijdens runtime in elke app die op die computer wordt uitgevoerd.

Fouten opsporen in een gekoppeld toegangsbewijs

Als u een onverwacht probleem wilt vaststellen of wilt weten wat een gekoppelde referentie doet, logboekregistratie inschakelen in uw app. U kunt de logboeken desgewenst filteren op alleen de gebeurtenissen die zijn verzonden uit de Azure Identity-clientbibliotheek. Bijvoorbeeld:

import azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log"
// print log output to stdout
azlog.SetListener(func(event azlog.Event, s string) {
    fmt.Println(s)
})
// include only azidentity credential logs
azlog.SetEvents(azidentity.EventAuthentication)

Zie de gids voor probleemoplossingvoor hulp bij het oplossen van fouten van specifieke referentietypen.