Guida all'installazione: Distribuire Microsoft Entra SDK per AgentID

L'SDK di Microsoft Entra per l'ID agente è un servizio di autenticazione in contenitori pronto per la distribuzione che semplifica l'acquisizione sicura dei token per le applicazioni. Questa guida all'installazione fornisce istruzioni dettagliate per la distribuzione del contenitore SDK in ambienti Kubernetes, Docker e Azure, eliminando la necessità di incorporare le credenziali sensibili direttamente nel codice dell'applicazione.

Prerequisiti

Accesso a Microsoft Artifact Registry
Runtime del contenitore (Docker, Kubernetes o servizio di contenitori)
Registrare una nuova app nella Interfaccia di amministrazione di Microsoft Entra configurata per Account solo in questa directory organizzativa. Per altri dettagli, vedere Registrare un'applicazione . Registrare i valori seguenti dalla pagina Panoramica dell'applicazione per usarli in un secondo momento:
- ID applicazione (cliente)
- ID della directory (cliente)
Credenziali per l'applicazione:
- Segreto client o certificato archiviato in modo sicuro (ad esempio, Azure Key Vault)
Per le distribuzioni Azure: interfaccia della riga di comando di Azure o l'accesso a Azure portale

Immagine del contenitore

L'SDK di Microsoft Entra per l'ID agente viene distribuito come immagine del contenitore dal registro artefatti

mcr.microsoft.com/entra-sdk/auth-sidecar

Modelli di distribuzione

L'SDK di Microsoft Entra per l'ID agente è progettato per l'esecuzione come contenitore complementare insieme all'applicazione. In questo modo l'applicazione può scaricare l'acquisizione e la gestione dei token nell'SDK tramite chiamate HTTP e mantenere le credenziali riservate fuori dal codice dell'applicazione. Di seguito sono riportati i modelli di distribuzione comuni e devono essere adattati all'ambiente specifico.

Modello Kubernetes

Distribuire l'SDK di Microsoft Entra per l'ID agente nello stesso pod del contenitore dell'applicazione per la comunicazione pod-locale sicura. Questo modello garantisce che il servizio di autenticazione venga eseguito insieme all'app, abilitando l'acquisizione rapida di token basati su HTTP mantenendo le credenziali isolate dal codice dell'applicazione:

apiVersion: v1
kind: Pod
metadata:
  # Your application container
  name: myapp
spec:
  containers:
  - name: app
    image: myregistry/myapp:latest
    ports:
    - containerPort: 8080
    env:
    - name: SIDECAR_URL
      value: "http://localhost:5000"
  # Microsoft Entra SDK for Agent ID container
  - name: sidecar
    image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
    ports:
    - containerPort: 5000
    env:
    - name: AzureAd__TenantId
      value: "your-tenant-id"
    - name: AzureAd__ClientId
      value: "your-client-id"
    - name: AzureAd__ClientCredentials__0__SourceType
      value: "KeyVault"
    - name: AzureAd__ClientCredentials__0__KeyVaultUrl
      value: "https://your-keyvault.vault.azure.net"
    - name: AzureAd__ClientCredentials__0__KeyVaultCertificateName
      value: "your-cert-name"

Distribuzione di Kubernetes

Vedere Kubernetes nell'esercitazione Azure: Preparare un'applicazione per Servizio Azure Kubernetes (AKS) se si vuole specificare come destinazione Azure Servizi Kubernetes. Questo modello usa una risorsa di distribuzione per gestire l'applicazione e Microsoft Entra SDK per i contenitori ID agente, consentendo il ridimensionamento e gli aggiornamenti. La distribuzione gestisce anche i controlli di integrità e l'allocazione delle risorse, garantendo operazioni sicure negli ambienti di produzione:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      serviceAccountName: myapp-sa
      containers:
      - name: app
        image: myregistry/myapp:latest
        ports:
        - containerPort: 8080
        env:
        - name: SIDECAR_URL
          value: "http://localhost:5000"
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
      
      - name: sidecar
        image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
        ports:
        - containerPort: 5000
        env:
        - name: AzureAd__TenantId
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: tenant-id
        - name: AzureAd__ClientId
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: client-id
        - name: AzureAd__Instance
          value: "https://login.microsoftonline.com/"
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "256Mi"
            cpu: "250m"
        livenessProbe:
          httpGet:
            path: /health
            port: 5000
          initialDelaySeconds: 10
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 5000
          initialDelaySeconds: 5
          periodSeconds: 5

Docker Compose

Quando si lavora in un ambiente Docker, è possibile usare Docker Compose per definire ed eseguire applicazioni multi-contenitore. L'esempio seguente illustra come configurare Microsoft Entra SDK per l'ID agente insieme al contenitore dell'applicazione in un ambiente di sviluppo locale:

version: '3.8'

services:
  app:
    image: myregistry/myapp:latest
    ports:
      - "8080:8080"
    environment:
      - AzureAd__TenantId=${TENANT_ID}
      - AzureAd__ClientId=${CLIENT_ID}
      - AzureAd__ClientCredentials__0__SourceType=ClientSecret
      - AzureAd__ClientCredentials__0__ClientSecret=${CLIENT_SECRET}
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

Azure servizio Kubernetes con identità gestita

Quando si esegue la distribuzione nel servizio Azure Kubernetes, è possibile usare Azure identità gestita per autenticare Microsoft Entra SDK per l'ID agente senza archiviare le credenziali nella configurazione. Prima di tutto è necessario abilitare ID dei carichi di lavoro di Microsoft Entra nel cluster del servizio Azure Kubernetes e creare una credenziale di identità federata per l'identità gestita. Configurare quindi l'SDK per l'uso dell'identità gestita per l'autenticazione.

Passaggio 1: Creare un'identità gestita

Creare un'identità gestita e assegnargli le autorizzazioni appropriate

# Create managed identity
az identity create \
  --resource-group myResourceGroup \
  --name myapp-identity

# Get the identity details
IDENTITY_CLIENT_ID=$(az identity show \
  --resource-group myResourceGroup \
  --name myapp-identity \
  --query clientId -o tsv)

IDENTITY_OBJECT_ID=$(az identity show \
  --resource-group myResourceGroup \
  --name myapp-identity \
  --query principalId -o tsv)

Passaggio 2: Assegnare le autorizzazioni

Concedere le autorizzazioni di identità gestita per accedere alle API downstream:

# Example: Grant permission to call Microsoft Graph
az ad app permission add \
  --id $IDENTITY_CLIENT_ID \
  --api 00000003-0000-0000-c000-000000000000 \
  --api-permissions e1fe6dd8-ba31-4d61-89e7-88639da4683d=Scope

Passaggio 3: Configurare l'identità del carico di lavoro

Creare un account del servizio con la federazione dell'identità del carico di lavoro:

export AKS_OIDC_ISSUER=$(az aks show \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --query "oidcIssuerProfile.issuerUrl" -o tsv)

az identity federated-credential create \
  --name myapp-federated-identity \
  --identity-name myapp-identity \
  --resource-group myResourceGroup \
  --issuer $AKS_OIDC_ISSUER \
  --subject system:serviceaccount:default:myapp-sa

Passaggio 4: Implementare con Workload Identity

Nell'esempio di distribuzione seguente, l'SDK di Microsoft Entra per l'ID agente è configurato per l'uso di ID dei carichi di lavoro di Microsoft Entra per l'autenticazione usando la proiezione di token basata su file. Il SignedAssertionFilePath tipo di credenziale legge il token dal file proiettato dal webhook identity del carico di lavoro:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: myapp-sa
  namespace: default
  annotations:
    azure.workload.identity/client-id: "<MANAGED_IDENTITY_CLIENT_ID>"

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp-deployment
spec:
  template:
    metadata:
      labels:
        azure.workload.identity/use: "true"
    spec:
      serviceAccountName: myapp-sa
      containers:
      - name: app
        image: myregistry/myapp:latest
        env:
        - name: SIDECAR_URL
          value: "http://localhost:5000"
      
      - name: sidecar
        image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
        ports:
        - containerPort: 5000
        env:
        - name: AzureAd__TenantId
          value: "your-tenant-id"
        - name: AzureAd__ClientId
          value: "<MANAGED_IDENTITY_CLIENT_ID>"
        
        # Workload Identity credentials - uses file-based token projection
        - name: AzureAd__ClientCredentials__0__SourceType
          value: "SignedAssertionFilePath"

Nota: il webhook di identità del carico di lavoro proietta automaticamente il token federato in /var/run/secrets/azure/tokens/azure-identity-token o una variabile di ambiente quando il pod ha l'etichetta e l'annotazione dell'account del servizio necessari.

Configurazione di rete

La configurazione di rete corretta è essenziale per garantire la comunicazione sicura tra l'SDK Microsoft Entra per l'ID agente e i servizi esterni, limitando al tempo stesso l'accesso non autorizzato. Una configurazione corretta impedisce le vulnerabilità di sicurezza e garantisce connettività affidabile agli endpoint Microsoft Entra ID. Usare le linee guida seguenti per configurare l'accesso di rete per l'SDK, a seconda dell'ambiente di distribuzione.

Solo comunicazione interna

Per configurare Microsoft Entra SDK per l'ID agente solo per la comunicazione locale dei pod interna, impostare l'URL dell'endpoint nell'applicazione in modo che punti a localhost o 127.0.0.1, a seconda dell'ambiente:

containers:
- name: sidecar
  env:
  - name: Kestrel__Endpoints__Http__Url
    value: "http://127.0.0.1:5000" # Same pod, localhost communication

Attenzione

Non esporre mai l'SDK di Microsoft Entra per l'ID agente esternamente tramite LoadBalancer o Ingress. Deve essere accessibile solo dal contenitore dell'applicazione.

Criteri di rete

Per limitare ulteriormente l'accesso alla rete, è consigliabile implementare criteri di rete Kubernetes per limitare il traffico da e verso il contenitore SDK:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: sidecar-network-policy
spec:
  podSelector:
    matchLabels:
      app: myapp
  policyTypes:
  - Ingress
  - Egress
  ingress:
  # No external ingress rules - only pod-local communication
  egress:
  - to:
    - namespaceSelector:
        matchLabels:
          name: kube-system
    ports:
    - protocol: TCP
      port: 53  # DNS
  - to:
    - podSelector: {}
  - to:
    # Allow outbound to Microsoft Entra ID
    ports:
    - protocol: TCP
      port: 443

Controlli di salute

L'SDK di Microsoft Entra per l'ID agente espone un endpoint /health per i probe di attività e conformità, assicurandosi che il contenitore sia in esecuzione in modo sicuro. Configura la distribuzione per includere queste sonde:

livenessProbe:
  httpGet:
    path: /health
    port: 5000
  initialDelaySeconds: 10
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health
    port: 5000
  initialDelaySeconds: 5
  periodSeconds: 5

Requisiti risorsa

Le allocazioni di risorse consigliate sono le seguenti, ma assicurarsi di adattarsi in base alla frequenza di acquisizione dei token, al numero di API downstream configurate e ai requisiti di dimensioni della cache:

Profilo risorsa	Memoria	CPU (unità centrale di elaborazione)
Minimo	128Mi	100m
Raccomandato	256Mi	250m
Traffico elevato	512Mi	500 m

Considerazioni sulla scalabilità

L'SDK di Microsoft Entra per l'ID agente è progettato per la scalabilità con l'applicazione:

Progettazione senza stato: ogni istanza dell'SDK mantiene la propria cache dei token
Scalabilità orizzontale: ridimensionamento aggiungendo più pod dell'applicazione (ognuno con la propria istanza dell'SDK)
Riscaldamento cache: prendere in considerazione l'implementazione di strategie di riscaldamento della cache per scenari ad alto traffico

Risoluzione dei problemi di distribuzione

I problemi comuni che possono verificarsi potrebbero essere causati da valori di configurazione non validi, connettività di rete a Microsoft Entra ID o credenziali o certificati mancanti. Verificare che l'identità gestita o l'entità servizio disponga delle autorizzazioni applicative corrette, del consenso amministrativo concesso (se necessario) e delle assegnazioni di ruolo corrette.

Di seguito sono riportati alcuni passaggi comuni per la risoluzione dei problemi di distribuzione:

Il contenitore non verrà avviato

Controllare i log dei contenitori:

kubectl logs <pod-name> -c sidecar

Errori di Controllo integrità

Verificare che l'SDK di Microsoft Entra per l'ID agente risponda:

kubectl exec <pod-name> -c sidecar -- curl http://localhost:5000/health

Per i passaggi più dettagliati sulla risoluzione dei problemi, vedere la guida alla risoluzione dei problemi.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-04-19