Konfigurera nyckellös autentisering med Microsoft Entra-ID

Azure AI Foundry Models stöder nyckellös auktorisering med Microsoft Entra-ID. Nyckellös auktorisering förbättrar säkerheten, förenklar användarupplevelsen, minskar driftkomplexiteten och ger robust efterlevnadsstöd för modern utveckling. Nyckellös auktorisering är ett starkt val för organisationer som använder säkra och skalbara identitetshanteringslösningar.

Den här artikeln beskriver hur du konfigurerar Microsoft Entra-ID för slutsatsdragning i Azure AI Foundry Models.

Förstå roller i resurskontexten i Azure

Microsoft Entra ID använder rollbaserad åtkomstkontroll (RBAC) för auktorisering. Roller är centrala för att hantera åtkomsten till dina molnresurser. En roll är en samling behörigheter som definierar vilka åtgärder som kan utföras på specifika Azure-resurser. Genom att tilldela roller till användare, grupper, tjänstens huvudnamn eller hanterade identiteter – gemensamt kallade säkerhetsobjekt – kontrollerar du deras åtkomst i Din Azure-miljö till specifika resurser.

När du tilldelar en roll anger du säkerhetsobjektet, rolldefinitionen och omfånget. Den här kombinationen kallas för en rolltilldelning. Azure AI Foundry Models är en funktion för Azure AI Services-resurserna och därför styr roller som tilldelats den specifika resursen åtkomsten för slutsatsdragning.

Du identifierar två olika typer av åtkomst till resurserna:

• Administrationsåtkomst: Åtgärder som rör administration av resursen. De ändrar vanligtvis tillståndet för resursen och dess konfiguration. I Azure är dessa åtgärder kontrollplansåtgärder och kan köras med hjälp av Azure-portalen, Azure CLI eller med infrastruktur som kod. Exempel är att skapa nya modelldistributioner, ändra konfigurationer för innehållsfiltrering, ändra versionen av modellen som hanteras eller ändra SKU:n för en distribution.

• Utvecklaråtkomst: Åtgärder som rör förbrukningen av resurserna. Till exempel att anropa API:et för chattens slutförande. Användaren kan dock inte ändra tillståndet för resursen och dess konfiguration.

I Azure utför Microsoft Entra-ID alltid administrationsåtgärder. Med roller som Cognitive Services-deltagare kan du utföra dessa åtgärder. Å andra sidan kan utvecklaråtgärder utföras med antingen åtkomstnycklar eller/och Microsoft Entra-ID. Med roller som Cognitive Services-användare kan du utföra dessa åtgärder.

Förutsättningar

För att slutföra den här artikeln behöver du:

• Ett Azure-abonnemang. Om du använder GitHub-modeller kan du uppgradera din upplevelse och skapa en Azure-prenumeration i processen. Läs Uppgradera från GitHub-modeller till Azure AI Foundry-modeller om så är fallet.

• Ett Azure AI Foundry-projekt. Den här typen av projekt hanteras under en Azure AI Foundry-resurs (kallades tidigare Azure AI Services-resurs). Om du inte har ett Foundry-projekt kan du läsa Skapa ett projekt för Azure AI Foundry (Foundry-projekt).

• Slutpunktens URL.

• Slutpunktens nyckel (om du väljer att använda API-nyckeln för autentisering).

• Ett konto med Microsoft.Authorization/roleAssignments/write och Microsoft.Authorization/roleAssignments/delete behörigheter, till exempel rollbaserad åtkomstkontroll för administratör .

• Om du vill tilldela en roll måste du ange tre element:

  • Säkerhetsobjekt: ditt användarkonto.
  • Rolldefinition: Cognitive Services-användarrollen .
  • Omfång: Azure AI Services-resursen.

• Om du vill skapa en anpassad rolldefinition i stället för att använda användarrollen Cognitive Services kontrollerar du att rollen har följande behörigheter:

  {
    "permissions": [
      {
        "dataActions": [
          "Microsoft.CognitiveServices/accounts/MaaS/*"
        ]
      }
    ]
  }
  

Konfigurera Microsoft Entra-ID för slutsatsdragning

Följ dessa steg för att konfigurera Microsoft Entra-ID för slutsatsdragning:

1. Gå till Azure-portalen och leta upp den Azure AI Foundry-resurs (kallades tidigare Azure AI Services-resurs) som du använder. Om du använder Azure AI Foundry med projekt eller hubbar kan du navigera till det genom att:

   1. Gå till Azure AI Foundry-portalen.

   2. På landningssidan väljer du Hanteringscenter.

   3. Gå till avsnittet Anslutna resurser och välj anslutningen till den Azure AI Foundry-resurs som du vill konfigurera. Om den inte visas väljer du Visa alla för att se den fullständiga listan.

      

   4. I avsnittet Anslutningsinformation går du till Resurs och väljer namnet på Azure-resursen. En ny sida öppnas.

   5. Nu är du i Azure-portalen där du kan hantera alla aspekter av själva resursen.

      

2. I den vänstra rutan väljer du Åtkomstkontroll (IAM) och sedan Lägg till>rolltilldelning.

   

   Tips/Råd

   Använd alternativet Visa min åtkomst för att kontrollera vilka roller som redan har tilldelats dig.

3. I Jobbfunktionsroller skriver du Cognitive Services-användare.

   

4. Välj rollen och välj Nästa.

5. På Medlemmar väljer du den användare eller grupp som du vill bevilja åtkomst till. Använd säkerhetsgrupper när det är möjligt eftersom de är enklare att hantera och underhålla.

   

6. Välj Nästa och slutför guiden.

7. Den valda användaren kan nu använda Microsoft Entra-ID för slutsatsdragning.

   Tips/Råd

   Det kan ta upp till fem minuter att sprida Azure-rolltilldelningar. När du arbetar med säkerhetsgrupper sker tillägg eller borttagning av användare från säkerhetsgruppen omedelbart.

Nyckelbaserad åtkomst är fortfarande möjlig för användare som redan har nycklar tillgängliga för dem. Om du vill återkalla nycklarna går du till Azure-portalen i det vänstra navigeringsfönstret och väljer Resurshanteringsnycklar>>Återskapa Key1 och Återskapa nyckel2.

Använda Microsoft Entra-ID i koden

När du har konfigurerat Microsoft Entra-ID i din resurs, uppdatera koden för att använda det när du konsumerar inference-slutpunkten. I följande exempel visas hur du använder en modell för chattavslut:

pip install azure-ai-inference

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
)

npm install @azure-rest/ai-inference

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";

const clientOptions = { credentials: { "https://cognitiveservices.azure.com" } };

const client = new ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new DefaultAzureCredential(),
    clientOptions,
);

dotnet add package Azure.AI.Inference --prerelease

dotnet add package Azure.Identity

using Azure;
using Azure.Identity;
using Azure.AI.Inference;

TokenCredential credential = new DefaultAzureCredential();
AzureAIInferenceClientOptions clientOptions = new AzureAIInferenceClientOptions();
BearerTokenAuthenticationPolicy tokenPolicy = new BearerTokenAuthenticationPolicy(credential, new string[] { "https://cognitiveservices.azure.com/.default" });
clientOptions.AddPolicy(tokenPolicy, HttpPipelinePosition.PerRetry);

ChatCompletionsClient client = new ChatCompletionsClient(
    new Uri("https://<resource>.services.ai.azure.com/models"),
    credential,
    clientOptions.
);

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-inference</artifactId>
    <version>1.0.0-beta.4</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.15.3</version>
</dependency>

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .buildClient();

POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json

az account get-access-token --resource https://cognitiveservices.azure.com --query "accessToken" --output tsv

Alternativ för autentiseringsuppgifter när du använder Microsoft Entra-ID

DefaultAzureCredential är en åsiktsbaserad, ordnad sekvens av mekanismer för autentisering till Microsoft Entra-ID. Varje autentiseringsmekanism är en klass som härleds från TokenCredential klassen och kallas för autentiseringsuppgifter. Vid körning DefaultAzureCredential försöker autentisera med hjälp av den första autentiseringsuppgiften. Om det misslyckas att erhålla en åtkomsttoken prövas nästa referens i sekvensen och så vidare, tills en åtkomsttoken framgångsrikt har erhållits. På så sätt kan din app använda olika autentiseringsuppgifter i olika miljöer utan att skriva miljöspecifik kod.

När föregående kod körs på din lokala utvecklingsarbetsstation letar den i miljövariablerna efter ett huvudnamn för programtjänsten eller lokalt installerade utvecklarverktyg, till exempel Visual Studio, för en uppsättning autentiseringsuppgifter för utvecklare. Du kan använda endera metoden för att autentisera appen till Azure-resurser under den lokala utvecklingen.

När den distribueras till Azure kan samma kod även autentisera din app till andra Azure-resurser. DefaultAzureCredential kan hämta miljöinställningar och hanterade identitetskonfigurationer för att autentisera till andra tjänster automatiskt.

Metodtips

• Använd deterministiska autentiseringsuppgifter i produktionsmiljöer: Överväg starkt att flytta från DefaultAzureCredential till någon av följande deterministiska lösningar i produktionsmiljöer:

  • En specifik TokenCredential implementering, till exempel ManagedIdentityCredential. Se Härledd lista för alternativ.
  • En avskalad ChainedTokenCredential implementering optimerad för Azure-miljön där appen körs. ChainedTokenCredential skapar i princip en specifik lista över godtagbara alternativ för autentiseringsuppgifter, till exempel ManagedIdentity för produktion och VisualStudioCredential för utveckling.

• Konfigurera systemtilldelade eller användartilldelade hanterade identiteter till de Azure-resurser där koden körs om möjligt. Konfigurera Microsoft Entra ID-åtkomst till dessa specifika identiteter.

Felsökning

Kontrollera att du har rätt behörigheter tilldelade innan du felsöker:

1. Gå till Azure-portalen och leta reda på den Azure AI Foundry-resurs (tidigare känd Azure AI Services-resurs) som du använder.

2. I den vänstra rutan väljer du Åtkomstkontroll (IAM) och sedan Kontrollera åtkomst.

3. Ange namnet på den användare eller identitet som du använder för att ansluta till tjänsten.

4. Kontrollera att rollen Cognitive Services-användare visas (eller en roll som innehåller de behörigheter som krävs enligt beskrivningen i Krav).

   Viktigt!

   Roller som Ägare eller Deltagare ger inte åtkomst via Microsoft Entra-ID.

5. Om rollen inte visas följer du stegen i den här guiden innan du fortsätter.

Följande tabell innehåller flera scenarier som kan hjälpa dig att felsöka Microsoft Entra-ID:

Använda Microsoft Entra-ID i projektet

Även när din resurs har Microsoft Entra ID konfigurerad kan dina projekt fortfarande använda nycklar för att hämta förutsägelser från resursen. När du använder Azure AI Foundry Playground används de autentiseringsuppgifter som är associerade med anslutningen i projektet.

Om du vill ändra det här beteendet uppdaterar du anslutningarna i dina projekt så att de använder Microsoft Entra-ID. Följ dessa steg:

1. Gå till Azure AI Foundry-portalen.

2. Gå till de projekt eller hubbar som använder Azure AI Foundry-resursen via en anslutning.

3. Välj Hanteringscenter.

4. Gå till avsnittet Anslutna resurser och välj anslutningen till den Azure AI Foundry-resurs som du vill konfigurera. Om den inte visas väljer du Visa alla för att se den fullständiga listan.

5. I avsnittet Anslutningsinformation bredvid Åtkomstinformation väljer du redigeringsikonen.

6. Under Autentisering ändrar du värdet till Microsoft Entra-ID.

7. Välj Uppdatera.

8. Anslutningen är nu konfigurerad för att fungera med Microsoft Entra-ID.

Inaktivera nyckelbaserad autentisering i resursen

Inaktivera nyckelbaserad autentisering när du implementerar Microsoft Entra-ID och fullständigt åtgärda kompatibilitets- eller reservproblem i alla program som använder tjänsten. Du kan bara inaktivera nyckelbaserad autentisering när du distribuerar med Bicep eller ARM.

Azure AI Foundry Models stöder nyckellös auktorisering med Microsoft Entra-ID. Nyckellös auktorisering förbättrar säkerheten, förenklar användarupplevelsen, minskar driftkomplexiteten och ger robust efterlevnadsstöd för modern utveckling. Nyckellös auktorisering är ett starkt val för organisationer som använder säkra och skalbara identitetshanteringslösningar.

Den här artikeln beskriver hur du konfigurerar Microsoft Entra-ID för slutsatsdragning i Azure AI Foundry Models.

Förstå roller i resurskontexten i Azure

Microsoft Entra ID använder rollbaserad åtkomstkontroll (RBAC) för auktorisering. Roller är centrala för att hantera åtkomsten till dina molnresurser. En roll är en samling behörigheter som definierar vilka åtgärder som kan utföras på specifika Azure-resurser. Genom att tilldela roller till användare, grupper, tjänstens huvudnamn eller hanterade identiteter – gemensamt kallade säkerhetsobjekt – kontrollerar du deras åtkomst i Din Azure-miljö till specifika resurser.

När du tilldelar en roll anger du säkerhetsobjektet, rolldefinitionen och omfånget. Den här kombinationen kallas för en rolltilldelning. Azure AI Foundry Models är en funktion för Azure AI Services-resurserna och därför styr roller som tilldelats den specifika resursen åtkomsten för slutsatsdragning.

Du identifierar två olika typer av åtkomst till resurserna:

• Administrationsåtkomst: Åtgärder som rör administration av resursen. De ändrar vanligtvis tillståndet för resursen och dess konfiguration. I Azure är dessa åtgärder kontrollplansåtgärder och kan köras med hjälp av Azure-portalen, Azure CLI eller med infrastruktur som kod. Exempel är att skapa nya modelldistributioner, ändra konfigurationer för innehållsfiltrering, ändra versionen av modellen som hanteras eller ändra SKU:n för en distribution.

• Utvecklaråtkomst: Åtgärder som rör förbrukningen av resurserna. Till exempel att anropa API:et för chattens slutförande. Användaren kan dock inte ändra tillståndet för resursen och dess konfiguration.

I Azure utför Microsoft Entra-ID alltid administrationsåtgärder. Med roller som Cognitive Services-deltagare kan du utföra dessa åtgärder. Å andra sidan kan utvecklaråtgärder utföras med antingen åtkomstnycklar eller/och Microsoft Entra-ID. Med roller som Cognitive Services-användare kan du utföra dessa åtgärder.

Förutsättningar

För att slutföra den här artikeln behöver du:

• Ett Azure-abonnemang. Om du använder GitHub-modeller kan du uppgradera din upplevelse och skapa en Azure-prenumeration i processen. Läs Uppgradera från GitHub-modeller till Azure AI Foundry-modeller om så är fallet.

• Ett Azure AI Foundry-projekt. Den här typen av projekt hanteras under en Azure AI Foundry-resurs (kallades tidigare Azure AI Services-resurs). Om du inte har ett Foundry-projekt kan du läsa Skapa ett projekt för Azure AI Foundry (Foundry-projekt).

• Slutpunktens URL.

• Slutpunktens nyckel (om du väljer att använda API-nyckeln för autentisering).

• Ett konto med Microsoft.Authorization/roleAssignments/write och Microsoft.Authorization/roleAssignments/delete behörigheter, till exempel rollbaserad åtkomstkontroll för administratör .

• Om du vill tilldela en roll måste du ange tre element:

  • Säkerhetsobjekt: ditt användarkonto.
  • Rolldefinition: Cognitive Services-användarrollen .
  • Omfång: Azure AI Services-resursen.

• Om du vill skapa en anpassad rolldefinition i stället för att använda användarrollen Cognitive Services kontrollerar du att rollen har följande behörigheter:

  {
    "permissions": [
      {
        "dataActions": [
          "Microsoft.CognitiveServices/accounts/MaaS/*"
        ]
      }
    ]
  }
  

• Installera Azure CLI.

• Identifiera följande information:

  • ditt prenumerations-ID för Azure

  • Namnet på din Azure AI Foundry-resurs (kallades tidigare Azure AI Services-resurs).

  • Resursgruppen där du distribuerade Azure AI Foundry-resursen.

Konfigurera Microsoft Entra-ID för slutsatsdragning

Följ dessa steg för att konfigurera Microsoft Entra-ID för slutsatsdragning:

1. Logga in på din Azure-prenumeration.

   az login
   

2. Om du har fler än en prenumeration väljer du den prenumeration där resursen finns.

   az account set --subscription "<subscription-id>"
   

3. Ange följande miljövariabler med namnet på den Azure AI Foundry-resurs som du planerar att använda och resursgruppen.

   ACCOUNT_NAME="<ai-services-resource-name>"
   RESOURCE_GROUP="<resource-group>"
   

4. Hämta det fullständiga namnet på resursen.

   RESOURCE_ID=$(az resource show -g $RESOURCE_GROUP -n $ACCOUNT_NAME --resource-type "Microsoft.CognitiveServices/accounts" --query id --output tsv)
   

5. Hämta objekt-ID:t för det säkerhetsobjekt som du vill tilldela behörigheter till. I följande exempel visas hur du hämtar objekt-ID:t som är associerat med:

   Ditt eget inloggade konto:

   OBJECT_ID=$(az ad signed-in-user show --query id --output tsv)
   

   En säkerhetsgrupp:

   OBJECT_ID=$(az ad group show --group "<group-name>" --query id --output tsv)
   

   Ett huvudnamn för tjänsten:

   OBJECT_ID=$(az ad sp show --id "<service-principal-guid>" --query id --output tsv)
   

6. Tilldela Cognitive Services User-rollen till tjänstens huvudobjekt (omfattar resursen). Genom att tilldela en roll ger du tjänstens huvudobjekt åtkomst till den här resursen.

   az role assignment create --assignee-object-id $OBJECT_ID --role "Cognitive Services User" --scope $RESOURCE_ID
   

7. Den valda användaren kan nu använda Microsoft Entra-ID för slutsatsdragning.

   Tips/Råd

   Tänk på att Azure-rolltilldelningar kan ta upp till fem minuter att sprida. Att lägga till eller ta bort användare från en säkerhetsgrupp sprids omedelbart.

Använda Microsoft Entra-ID i koden

När du har konfigurerat Microsoft Entra-ID i din resurs, uppdatera koden för att använda det när du konsumerar inference-slutpunkten. I följande exempel visas hur du använder en modell för chattavslut:

pip install azure-ai-inference

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
)

npm install @azure-rest/ai-inference

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";

const clientOptions = { credentials: { "https://cognitiveservices.azure.com" } };

const client = new ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new DefaultAzureCredential(),
    clientOptions,
);

dotnet add package Azure.AI.Inference --prerelease

dotnet add package Azure.Identity

using Azure;
using Azure.Identity;
using Azure.AI.Inference;

TokenCredential credential = new DefaultAzureCredential();
AzureAIInferenceClientOptions clientOptions = new AzureAIInferenceClientOptions();
BearerTokenAuthenticationPolicy tokenPolicy = new BearerTokenAuthenticationPolicy(credential, new string[] { "https://cognitiveservices.azure.com/.default" });
clientOptions.AddPolicy(tokenPolicy, HttpPipelinePosition.PerRetry);

ChatCompletionsClient client = new ChatCompletionsClient(
    new Uri("https://<resource>.services.ai.azure.com/models"),
    credential,
    clientOptions.
);

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-inference</artifactId>
    <version>1.0.0-beta.4</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.15.3</version>
</dependency>

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .buildClient();

POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json

az account get-access-token --resource https://cognitiveservices.azure.com --query "accessToken" --output tsv

Alternativ för autentiseringsuppgifter när du använder Microsoft Entra-ID

DefaultAzureCredential är en åsiktsbaserad, ordnad sekvens av mekanismer för autentisering till Microsoft Entra-ID. Varje autentiseringsmekanism är en klass som härleds från TokenCredential klassen och kallas för autentiseringsuppgifter. Vid körning DefaultAzureCredential försöker autentisera med hjälp av den första autentiseringsuppgiften. Om det misslyckas att erhålla en åtkomsttoken prövas nästa referens i sekvensen och så vidare, tills en åtkomsttoken framgångsrikt har erhållits. På så sätt kan din app använda olika autentiseringsuppgifter i olika miljöer utan att skriva miljöspecifik kod.

När föregående kod körs på din lokala utvecklingsarbetsstation letar den i miljövariablerna efter ett huvudnamn för programtjänsten eller lokalt installerade utvecklarverktyg, till exempel Visual Studio, för en uppsättning autentiseringsuppgifter för utvecklare. Du kan använda endera metoden för att autentisera appen till Azure-resurser under den lokala utvecklingen.

När den distribueras till Azure kan samma kod även autentisera din app till andra Azure-resurser. DefaultAzureCredential kan hämta miljöinställningar och hanterade identitetskonfigurationer för att autentisera till andra tjänster automatiskt.

Metodtips

• Använd deterministiska autentiseringsuppgifter i produktionsmiljöer: Överväg starkt att flytta från DefaultAzureCredential till någon av följande deterministiska lösningar i produktionsmiljöer:

  • En specifik TokenCredential implementering, till exempel ManagedIdentityCredential. Se Härledd lista för alternativ.
  • En avskalad ChainedTokenCredential implementering optimerad för Azure-miljön där appen körs. ChainedTokenCredential skapar i princip en specifik lista över godtagbara alternativ för autentiseringsuppgifter, till exempel ManagedIdentity för produktion och VisualStudioCredential för utveckling.

• Konfigurera systemtilldelade eller användartilldelade hanterade identiteter till de Azure-resurser där koden körs om möjligt. Konfigurera Microsoft Entra ID-åtkomst till dessa specifika identiteter.

Felsökning

Kontrollera att du har rätt behörigheter tilldelade innan du felsöker:

1. Gå till Azure-portalen och leta reda på den Azure AI Foundry-resurs (tidigare känd Azure AI Services-resurs) som du använder.

2. I den vänstra rutan väljer du Åtkomstkontroll (IAM) och sedan Kontrollera åtkomst.

3. Ange namnet på den användare eller identitet som du använder för att ansluta till tjänsten.

4. Kontrollera att rollen Cognitive Services-användare visas (eller en roll som innehåller de behörigheter som krävs enligt beskrivningen i Krav).

   Viktigt!

   Roller som Ägare eller Deltagare ger inte åtkomst via Microsoft Entra-ID.

5. Om rollen inte visas följer du stegen i den här guiden innan du fortsätter.

Följande tabell innehåller flera scenarier som kan hjälpa dig att felsöka Microsoft Entra-ID:

Azure AI Foundry Models stöder nyckellös auktorisering med Microsoft Entra-ID. Nyckellös auktorisering förbättrar säkerheten, förenklar användarupplevelsen, minskar driftkomplexiteten och ger robust efterlevnadsstöd för modern utveckling. Nyckellös auktorisering är ett starkt val för organisationer som använder säkra och skalbara identitetshanteringslösningar.

Den här artikeln beskriver hur du konfigurerar Microsoft Entra-ID för slutsatsdragning i Azure AI Foundry Models.

Förstå roller i resurskontexten i Azure

Microsoft Entra ID använder rollbaserad åtkomstkontroll (RBAC) för auktorisering. Roller är centrala för att hantera åtkomsten till dina molnresurser. En roll är en samling behörigheter som definierar vilka åtgärder som kan utföras på specifika Azure-resurser. Genom att tilldela roller till användare, grupper, tjänstens huvudnamn eller hanterade identiteter – gemensamt kallade säkerhetsobjekt – kontrollerar du deras åtkomst i Din Azure-miljö till specifika resurser.

När du tilldelar en roll anger du säkerhetsobjektet, rolldefinitionen och omfånget. Den här kombinationen kallas för en rolltilldelning. Azure AI Foundry Models är en funktion för Azure AI Services-resurserna och därför styr roller som tilldelats den specifika resursen åtkomsten för slutsatsdragning.

Du identifierar två olika typer av åtkomst till resurserna:

• Administrationsåtkomst: Åtgärder som rör administration av resursen. De ändrar vanligtvis tillståndet för resursen och dess konfiguration. I Azure är dessa åtgärder kontrollplansåtgärder och kan köras med hjälp av Azure-portalen, Azure CLI eller med infrastruktur som kod. Exempel är att skapa nya modelldistributioner, ändra konfigurationer för innehållsfiltrering, ändra versionen av modellen som hanteras eller ändra SKU:n för en distribution.

• Utvecklaråtkomst: Åtgärder som rör förbrukningen av resurserna. Till exempel att anropa API:et för chattens slutförande. Användaren kan dock inte ändra tillståndet för resursen och dess konfiguration.

I Azure utför Microsoft Entra-ID alltid administrationsåtgärder. Med roller som Cognitive Services-deltagare kan du utföra dessa åtgärder. Å andra sidan kan utvecklaråtgärder utföras med antingen åtkomstnycklar eller/och Microsoft Entra-ID. Med roller som Cognitive Services-användare kan du utföra dessa åtgärder.

Förutsättningar

För att slutföra den här artikeln behöver du:

• Ett Azure-abonnemang. Om du använder GitHub-modeller kan du uppgradera din upplevelse och skapa en Azure-prenumeration i processen. Läs Uppgradera från GitHub-modeller till Azure AI Foundry-modeller om så är fallet.

• Ett Azure AI Foundry-projekt. Den här typen av projekt hanteras under en Azure AI Foundry-resurs (kallades tidigare Azure AI Services-resurs). Om du inte har ett Foundry-projekt kan du läsa Skapa ett projekt för Azure AI Foundry (Foundry-projekt).

• Slutpunktens URL.

• Slutpunktens nyckel (om du väljer att använda API-nyckeln för autentisering).

• Ett konto med Microsoft.Authorization/roleAssignments/write och Microsoft.Authorization/roleAssignments/delete behörigheter, till exempel rollbaserad åtkomstkontroll för administratör .

• Om du vill tilldela en roll måste du ange tre element:

  • Säkerhetsobjekt: ditt användarkonto.
  • Rolldefinition: Cognitive Services-användarrollen .
  • Omfång: Azure AI Services-resursen.

• Om du vill skapa en anpassad rolldefinition i stället för att använda användarrollen Cognitive Services kontrollerar du att rollen har följande behörigheter:

  {
    "permissions": [
      {
        "dataActions": [
          "Microsoft.CognitiveServices/accounts/MaaS/*"
        ]
      }
    ]
  }
  

• Installera Azure CLI.

• Identifiera följande information:

  • ditt prenumerations-ID för Azure

Om den här självstudiekursen

Exemplet i den här artikeln baseras på kodexempel på lagringsplatsen Azure-Samples/azureai-model-inference-bicep . Om du vill köra kommandona lokalt utan att kopiera eller klistra in filinnehåll använder du följande kommandon för att klona lagringsplatsen och gå till mappen för kodningsspråket:

git clone https://github.com/Azure-Samples/azureai-model-inference-bicep

Filerna för det här exemplet finns i:

cd azureai-model-inference-bicep/infra

Förstå resurserna

I den här självstudien skapar du följande resurser:

• En Azure AI Foundry-resurs (kallades tidigare Azure AI Services-resurs) med nyckelåtkomst inaktiverad. För enkelhetens skull distribuerar den här mallen inte modeller.
• En rolltilldelning för ett visst säkerhetsobjekt med rollen Cognitive Services-användare.

Använd följande tillgångar för att skapa dessa resurser:

1. Använd mallen modules/ai-services-template.bicep för att beskriva din Azure AI Foundry-resurs:

   modules/ai-services-template.bicep

   @description('Location of the resource.')
   param location string = resourceGroup().location
   
   @description('Name of the Azure AI Services account.')
   param accountName string
   
   @description('The resource model definition representing SKU')
   param sku string = 'S0'
   
   @description('Whether or not to allow keys for this account.')
   param allowKeys bool = true
   
   @allowed([
     'Enabled'
     'Disabled'
   ])
   @description('Whether or not public endpoint access is allowed for this account.')
   param publicNetworkAccess string = 'Enabled'
   
   @allowed([
     'Allow'
     'Deny'
   ])
   @description('The default action for network ACLs.')
   param networkAclsDefaultAction string = 'Allow'
   
   resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
     name: accountName
     location: location
     identity: {
       type: 'SystemAssigned'
     }
     sku: {
       name: sku
     }
     kind: 'AIServices'
     properties: {
       customSubDomainName: accountName
       publicNetworkAccess: publicNetworkAccess
       networkAcls: {
         defaultAction: networkAclsDefaultAction
       }
       disableLocalAuth: allowKeys
     }
   }
   
   output endpointUri string = 'https://${account.outputs.name}.services.ai.azure.com/models'
   output id string = account.id
   

   Tips/Råd

   Den här mallen accepterar parametern allowKeys . Ställ in den på false för att inaktivera nyckelåtkomst i resursen. Den här konfigurationen är valfri.

2. Använd mallen modules/role-assignment-template.bicep för att beskriva en rolltilldelning i Azure:

   modules/role-assignment-template.bicep

   @description('Specifies the role definition ID used in the role assignment.')
   param roleDefinitionID string
   
   @description('Specifies the principal ID assigned to the role.')
   param principalId string
   
   @description('Specifies the resource ID of the resource to assign the role to.')
   param scopeResourceId string = resourceGroup().id
   
   var roleAssignmentName= guid(principalId, roleDefinitionID, scopeResourceId)
   resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
     name: roleAssignmentName
     properties: {
       roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionID)
       principalId: principalId
     }
   }
   
   output name string = roleAssignment.name
   output resourceId string = roleAssignment.id
   

Skapa resurserna

Följ dessa steg i konsolen:

1. Definiera huvuddistributionen:

   deploy-entra-id.bicep

   @description('Location to create the resources in')
   param location string = resourceGroup().location
   
   @description('Name of the resource group to create the resources in')
   param resourceGroupName string = resourceGroup().name
   
   @description('Name of the AI Services account to create')
   param accountName string = 'azurei-models-dev'
   
   @description('ID of the developers to assign the user role to')
   param securityPrincipalId string
   
   module aiServicesAccount 'modules/ai-services-template.bicep' = {
     name: 'aiServicesAccount'
     scope: resourceGroup(resourceGroupName)
     params: {
       accountName: accountName
       location: location
       allowKeys: false
     }
   }
   
   module roleAssignmentDeveloperAccount 'modules/role-assignment-template.bicep' = {
     name: 'roleAssignmentDeveloperAccount'
     scope: resourceGroup(resourceGroupName)
     params: {
       roleDefinitionID: 'a97b65f3-24c7-4388-baec-2e87135dc908' // Azure Cognitive Services User
       principalId: securityPrincipalId
     }
   }
   
   output endpoint string = aiServicesAccount.outputs.endpointUri
   

2. Logga in på Azure:

   az login
   

3. Kontrollera att du har rätt prenumeration:

   az account set --subscription "<subscription-id>"
   

4. Kör utrullningen:

   RESOURCE_GROUP="<resource-group-name>"
   SECURITY_PRINCIPAL_ID="<your-security-principal-id>"
   
   az deployment group create \
     --resource-group $RESOURCE_GROUP \
     --parameters securityPrincipalId=$SECURITY_PRINCIPAL_ID \
     --template-file deploy-entra-id.bicep
   

5. Mallen visar slutpunkten för Azure AI Foundry Models som du kan använda för att utnyttja någon av de modellimplementeringar du skapade.

Använda Microsoft Entra-ID i koden

När du har konfigurerat Microsoft Entra-ID i din resurs, uppdatera koden för att använda det när du konsumerar inference-slutpunkten. I följande exempel visas hur du använder en modell för chattavslut:

pip install azure-ai-inference

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
)

npm install @azure-rest/ai-inference

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";

const clientOptions = { credentials: { "https://cognitiveservices.azure.com" } };

const client = new ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new DefaultAzureCredential(),
    clientOptions,
);

dotnet add package Azure.AI.Inference --prerelease

dotnet add package Azure.Identity

using Azure;
using Azure.Identity;
using Azure.AI.Inference;

TokenCredential credential = new DefaultAzureCredential();
AzureAIInferenceClientOptions clientOptions = new AzureAIInferenceClientOptions();
BearerTokenAuthenticationPolicy tokenPolicy = new BearerTokenAuthenticationPolicy(credential, new string[] { "https://cognitiveservices.azure.com/.default" });
clientOptions.AddPolicy(tokenPolicy, HttpPipelinePosition.PerRetry);

ChatCompletionsClient client = new ChatCompletionsClient(
    new Uri("https://<resource>.services.ai.azure.com/models"),
    credential,
    clientOptions.
);

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-inference</artifactId>
    <version>1.0.0-beta.4</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.15.3</version>
</dependency>

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .buildClient();

POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json

az account get-access-token --resource https://cognitiveservices.azure.com --query "accessToken" --output tsv

Alternativ för autentiseringsuppgifter när du använder Microsoft Entra-ID

DefaultAzureCredential är en åsiktsbaserad, ordnad sekvens av mekanismer för autentisering till Microsoft Entra-ID. Varje autentiseringsmekanism är en klass som härleds från TokenCredential klassen och kallas för autentiseringsuppgifter. Vid körning DefaultAzureCredential försöker autentisera med hjälp av den första autentiseringsuppgiften. Om det misslyckas att erhålla en åtkomsttoken prövas nästa referens i sekvensen och så vidare, tills en åtkomsttoken framgångsrikt har erhållits. På så sätt kan din app använda olika autentiseringsuppgifter i olika miljöer utan att skriva miljöspecifik kod.

När föregående kod körs på din lokala utvecklingsarbetsstation letar den i miljövariablerna efter ett huvudnamn för programtjänsten eller lokalt installerade utvecklarverktyg, till exempel Visual Studio, för en uppsättning autentiseringsuppgifter för utvecklare. Du kan använda endera metoden för att autentisera appen till Azure-resurser under den lokala utvecklingen.

När den distribueras till Azure kan samma kod även autentisera din app till andra Azure-resurser. DefaultAzureCredential kan hämta miljöinställningar och hanterade identitetskonfigurationer för att autentisera till andra tjänster automatiskt.

Metodtips

• Använd deterministiska autentiseringsuppgifter i produktionsmiljöer: Överväg starkt att flytta från DefaultAzureCredential till någon av följande deterministiska lösningar i produktionsmiljöer:

  • En specifik TokenCredential implementering, till exempel ManagedIdentityCredential. Se Härledd lista för alternativ.
  • En avskalad ChainedTokenCredential implementering optimerad för Azure-miljön där appen körs. ChainedTokenCredential skapar i princip en specifik lista över godtagbara alternativ för autentiseringsuppgifter, till exempel ManagedIdentity för produktion och VisualStudioCredential för utveckling.

• Konfigurera systemtilldelade eller användartilldelade hanterade identiteter till de Azure-resurser där koden körs om möjligt. Konfigurera Microsoft Entra ID-åtkomst till dessa specifika identiteter.

Felsökning

Kontrollera att du har rätt behörigheter tilldelade innan du felsöker:

1. Gå till Azure-portalen och leta reda på den Azure AI Foundry-resurs (tidigare känd Azure AI Services-resurs) som du använder.

2. I den vänstra rutan väljer du Åtkomstkontroll (IAM) och sedan Kontrollera åtkomst.

3. Ange namnet på den användare eller identitet som du använder för att ansluta till tjänsten.

4. Kontrollera att rollen Cognitive Services-användare visas (eller en roll som innehåller de behörigheter som krävs enligt beskrivningen i Krav).

   Viktigt!

   Roller som Ägare eller Deltagare ger inte åtkomst via Microsoft Entra-ID.

5. Om rollen inte visas följer du stegen i den här guiden innan du fortsätter.

Följande tabell innehåller flera scenarier som kan hjälpa dig att felsöka Microsoft Entra-ID:

Inaktivera nyckelbaserad autentisering i resursen

Inaktivera nyckelbaserad autentisering när du implementerar Microsoft Entra-ID och fullständigt åtgärda kompatibilitets- eller reservproblem i alla program som använder tjänsten. Ändra egenskapen disableLocalAuth för att inaktivera nyckelbaserad autentisering:

modules/ai-services-template.bicep

@description('Location of the resource.')
param location string = resourceGroup().location

@description('Name of the Azure AI Services account.')
param accountName string

@description('The resource model definition representing SKU')
param sku string = 'S0'

@description('Whether or not to allow keys for this account.')
param allowKeys bool = true

@allowed([
  'Enabled'
  'Disabled'
])
@description('Whether or not public endpoint access is allowed for this account.')
param publicNetworkAccess string = 'Enabled'

@allowed([
  'Allow'
  'Deny'
])
@description('The default action for network ACLs.')
param networkAclsDefaultAction string = 'Allow'

resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
  name: accountName
  location: location
  identity: {
    type: 'SystemAssigned'
  }
  sku: {
    name: sku
  }
  kind: 'AIServices'
  properties: {
    customSubDomainName: accountName
    publicNetworkAccess: publicNetworkAccess
    networkAcls: {
      defaultAction: networkAclsDefaultAction
    }
    disableLocalAuth: allowKeys
  }
}

output endpointUri string = 'https://${account.outputs.name}.services.ai.azure.com/models'
output id string = account.id