Installatiehandleiding: de Microsoft Entra SDK voor AgentID implementeren

De Microsoft Entra SDK voor Agent-ID is een kant-en-klare containerized authenticatiedienst die het verkrijgen van veilige tokens voor uw toepassingen stroomlijnt. Deze installatiehandleiding bevat stapsgewijze instructies voor het implementeren van de SDK-container in Kubernetes-, Docker- en Azure-omgevingen, waardoor u geen gevoelige referenties rechtstreeks in uw toepassingscode hoeft in te sluiten.

Vereiste voorwaarden

• Toegang tot Microsoft Artifact Registry
• Container-runtime (Docker, Kubernetes of containerservice)
• Registreer een nieuwe app in de Microsoft Entra-beheercentrum, geconfigureerd voor Accounts alleen in deze organisatiestructuur. Raadpleeg Een applicatie registreren voor meer details. Noteer de volgende waarden van de Overview pagina van de applicatie voor later gebruik.
  • Applicatie (client) ID
  • ID van de directory (tenant)
• Inloggegevens voor de applicatie:
  • Clientgeheim of certificaat dat veilig is opgeslagen (bijvoorbeeld Azure Key Vault)
• Voor Azure implementaties: Azure CLI of toegang tot Azure portal

Containerimage

De Microsoft Entra SDK voor Agent ID wordt gedistribueerd als een containerafbeelding vanuit het artefactregister

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

Implementatiepatronen

De Microsoft Entra SDK voor agent-id is ontworpen voor uitvoering als een aanvullende container naast uw toepassing. Hierdoor kan uw toepassing tokenverwerving en -beheer offloaden naar de SDK via HTTP-aanroepen en gevoelige referenties uit uw toepassingscode houden. Hier volgen algemene implementatiepatronen en moeten worden aangepast aan uw specifieke omgeving.

Kubernetes-patroon

Implementeer de Microsoft Entra SDK voor agent-id in dezelfde pod als uw toepassingscontainer voor beveiligde pod-lokale communicatie. Dit patroon zorgt ervoor dat de verificatieservice naast uw app wordt uitgevoerd, waardoor snelle op HTTP gebaseerde tokenverzameling wordt ingeschakeld terwijl referenties geïsoleerd blijven van uw toepassingscode:

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"

Kubernetes-implementatie

Zie Kubernetes in Azure zelfstudie: Een toepassing voorbereiden voor Azure Kubernetes Service (AKS) als u zich wilt richten op Azure Kubernetes Services. Dit patroon maakt gebruik van een implementatieresource voor het beheren van toepassings- en Microsoft Entra SDK voor agent-id-containers, waardoor schaalaanpassing en updates mogelijk zijn. De implementatie verwerkt ook statuscontroles en resourcetoewijzing, waardoor een veilige werking in productieomgevingen wordt gegarandeerd:

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

Wanneer u in een Docker-omgeving werkt, kunt u Docker Compose gebruiken om toepassingen met meerdere containers te definiëren en uit te voeren. In het volgende voorbeeld ziet u hoe u de Microsoft Entra SDK voor agent-id naast uw toepassingscontainer instelt in een lokale ontwikkelomgeving:

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 Kubernetes-service (AKS) met beheerde identiteit

Wanneer u implementeert in AKS, kunt u Azure Managed Identity gebruiken om de Microsoft Entra SDK voor agent-id te verifiëren zonder referenties in de configuratie op te slaan. Eerst moet u Microsoft Entra Workload-id inschakelen op uw AKS-cluster en een federatieve identiteitsreferentie maken voor uw beheerde identiteit. Configureer vervolgens de SDK voor het gebruik van de beheerde identiteit voor verificatie.

Stap 1: Beheerde identiteit maken

Een beheerde identiteit maken en de juiste machtigingen toewijzen

# 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)

Stap 2: Machtigingen toewijzen

De beheerde identiteit machtigingen verlenen voor toegang tot downstream-API's:

# 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

Stap 3: Workloadidentiteit configureren

Maak een serviceaccount met workload-identiteitsfederatie:

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

Stap 4: Implementeren met Workload Identity

In het volgende implementatievoorbeeld is de Microsoft Entra SDK voor agent-id geconfigureerd voor het gebruik van Microsoft Entra Workload-id voor verificatie met behulp van tokenprojectie op basis van bestanden. Het SignedAssertionFilePath referent leest het token uit het bestand dat wordt geprojecteerd door de workload identity webhook.

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"

Opmerking: De webhook van de workload-identiteit projecteert automatisch de federated token naar /var/run/secrets/azure/tokens/azure-identity-token of een omgevingsvariabele wanneer de pod het vereiste label en de annotatie van het serviceaccount heeft.

Netwerkconfiguratie

De juiste netwerkconfiguratie is essentieel om beveiligde communicatie tussen de Microsoft Entra SDK voor agent-id en externe services te garanderen terwijl onbevoegde toegang wordt beperkt. De juiste configuratie voorkomt beveiligingsproblemen en zorgt voor betrouwbare connectiviteit met Microsoft Entra ID eindpunten. Gebruik de volgende richtlijnen om netwerktoegang voor de SDK te configureren, afhankelijk van uw implementatieomgeving.

Alleen interne communicatie

Als u de Microsoft Entra SDK voor agent-id alleen wilt configureren voor interne pod-lokale communicatie, stelt u de eindpunt-URL in uw toepassing in zodat deze verwijst naar localhost of 127.0.0.1, afhankelijk van uw omgeving:

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

Netwerkbeleid

Als u de netwerktoegang verder wilt beperken, kunt u Kubernetes-netwerkbeleid implementeren om verkeer van en naar de SDK-container te beperken:

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

Gezondheidscontroles

De Microsoft Entra SDK voor Agent ID maakt een /health-eindpunt beschikbaar voor liveness- en gereedheidscontroles, om te garanderen dat de container veilig draait. Configureer uw implementatie om deze sondes op te nemen:

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

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

Vereisten voor middelen

De aanbevolen resourcetoewijzingen zijn als volgt, maar zorg ervoor dat deze worden aangepast op basis van de frequentie van het verkrijgen van tokens, het aantal geconfigureerde downstream-API's en de cachegroottevereisten:

Overwegingen met betrekking tot schaalvergroting

De Microsoft Entra SDK voor agent-id is ontworpen om te schalen met uw toepassing:

1. Staatloos ontwerp: elk SDK-exemplaar onderhoudt zijn eigen tokencache
2. Horizontaal schalen: schalen door meer toepassingspods toe te voegen (elk met een eigen SDK-exemplaar)
3. Cachewarming: Overweeg het implementeren van strategieën voor cacheverwarming voor scenario's met veel verkeer

Problemen met implementatie oplossen

Veelvoorkomende problemen die kunnen optreden, kunnen worden veroorzaakt door ongeldige configuratiewaarden, netwerkverbinding met Microsoft Entra ID of ontbrekende referenties of certificaten. Zorg ervoor dat de beheerde identiteit of service-principal beschikt over de juiste toepassingsmachtigingen, beheerderstoestemming (indien nodig) en juiste roltoewijzingen.

Hier volgen enkele veelvoorkomende stappen voor probleemoplossing die u kunnen helpen bij het oplossen van implementatieproblemen:

Container wordt niet gestart

Containerlogboeken controleren:

kubectl logs <pod-name> -c sidecar

Mislukkingen bij gezondheidscontrole

Controleer of de Microsoft Entra SDK voor agent-id reageert:

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

Raadpleeg de gids voor probleemoplossing voor gedetailleerdere stappen.

Verwante inhoud

• Configuratiereferentie
• Referentie voor eindpunten
• Aanbevolen beveiligingsprocedures
• Autorisatieheader valideren