Guida all'installazione: Distribuire Microsoft Entra SDK per AgentID

Microsoft Entra SDK per AgentID è 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 distribuire il 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 Container Registry (MCR)
• Runtime del contenitore (Docker, Kubernetes o servizio di contenitori)
• Registrare una nuova app nell'interfaccia di amministrazione di Microsoft Entra, configurata solo per gli account 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 di Azure: Azure CLI o accesso al portale di Azure

Immagine del contenitore

Microsoft Entra SDK per AgentID viene distribuito in formato immagine container da MCR.

mcr.microsoft.com/entra-sdk/auth-sidecar:<tag>

Tag di versione

• latest - Versione stabile più recente
• <version> - Versioni specifiche (ad esempio, 1.0.0)
• <version>-preview - Versioni di anteprima

Modelli di distribuzione

Microsoft Entra SDK per AgentID è 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

Implementa l'SDK di Microsoft Entra per AgentID nello stesso pod del contenitore dell'applicazione per una comunicazione sicura locale al pod. 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 AgentID 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 Esercitazione su Kubernetes in Azure: Preparare un'applicazione per Azure Kubernetes Service (AKS) se si desidera rivolgersi ad Azure Kubernetes Services. Questo modello usa una risorsa di distribuzione per gestire l'applicazione e Microsoft Entra SDK per i contenitori AgentID, 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 AgentID insieme al contenitore dell'applicazione in un ambiente di sviluppo locale:

version: '3.8'

services:
  app:
    image: myregistry/myapp:latest
    ports:
      - "8080:8080"
    en - sidecar 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

Servizio Azure Kubernetes con identità gestita

Quando distribuisci su AKS, puoi utilizzare Azure Managed Identity per autenticare Microsoft Entra SDK per AgentID senza archiviare le credenziali nella configurazione. Prima di tutto, è necessario abilitare l'identità del carico di lavoro di Azure AD sul cluster AKS e creare una credenziale di identità federata per la tua 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, Microsoft Entra SDK per AgentID è configurato per l'uso dell'identità del carico di lavoro di Azure AD per l'autenticazione tramite 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 Microsoft Entra SDK per AgentID e i servizi esterni, limitando al tempo stesso l'accesso non autorizzato. Una configurazione corretta impedisce le vulnerabilità di sicurezza e garantisce una connettività affidabile agli endpoint dell'ID Entra di Microsoft. 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 AgentID 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

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 integrità

Microsoft Entra SDK per AgentID espone un endpoint /health per le sonde di vitalità e disponibilità, assicurando un'esecuzione sicura del contenitore. 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 delle risorse

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:

Considerazioni sul ridimensionamento

Microsoft Entra SDK per AgentID è progettato per la scalabilità con l'applicazione:

1. Progettazione senza stato: ogni istanza dell'SDK mantiene la propria cache dei token
2. Scalabilità orizzontale: ridimensionamento aggiungendo più pod dell'applicazione (ognuno con la propria istanza dell'SDK)
3. 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 dovuti a valori di configurazione non validi, alla connettività di rete all'ID Microsoft Entra o a 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 verifica dello stato di salute

Verificare che Microsoft Entra SDK per AgentID stia rispondendo:

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.

Passaggi successivi

• Configurare le impostazioni - Configurare la configurazione dell'identità
• Esaminare gli endpoint - Esplorare l'API HTTP
• Procedure consigliate per la sicurezza - Rafforzare l'implementazione
• Scegliere uno scenario : iniziare con un esempio guidato