Přihlašování uživatelů a volání následných rozhraní API pomocí sady Microsoft Entra ID Auth SDK (sidecar) v Pythonu

V tomto rychlém startu pomocí ukázkové webové aplikace zjistíte, jak přihlásit uživatele nebo agenty a volat podřízená rozhraní API pomocí vlastní identity. Ukázková aplikace používá sadu Microsoft Entra ID Auth SDK (sidecar) k ověření tokenů uživatele pro delegovaný přístup a používá identitu aplikace pro komunikaci mezi službami s podřízenými rozhraními API, jako je Microsoft Graph.

Požadavky

  • Nainstalujte správce balíčků UV. UV je rychlý instalační program balíčku Python a překladač napsaný v Rustu.

  • Nainstalujte Docker Desktop.

  • Účet Azure s aktivním předplatným. Pokud ho ještě nemáte, vytvořte si účet zdarma.

  • Tento účet Azure musí mít oprávnění ke správě aplikací. Následující role Microsoft Entra obsahují požadovaná oprávnění:

    • Správce aplikace
    • Vývojář aplikací
  • Součást pracovního týmu. Můžete použít výchozí adresář nebo nastavit nového nájemníka.

Vytvoření a konfigurace aplikace Microsoft Entra

Pokud chcete dokončit zbytek rychlého startu, musíte nejprve zaregistrovat aplikaci v Microsoft Entra ID.

Vytvoření registrace aplikace

Pokud chcete vytvořit registraci aplikace, postupujte takto:

  1. Přihlaste se k Centrum pro správu Microsoft Entra alespoň jako Application Developer.

  2. Pokud máte přístup k více tenantům, pomocí ikony Nastavení v horní nabídce přepněte na tenanta, ve kterém chcete aplikaci zaregistrovat.

  3. Přejděte na Entra ID>Registrace aplikací a vyberte Nová registrace.

  4. Zadejte smysluplný název aplikace, například identity-client-app. Uživatelé aplikace uvidí tento název a můžete ho kdykoli změnit. Můžete mít více registrací aplikací se stejným názvem.

  5. V části Podporované typy účtůzadejte, kdo může aplikaci používat. Vyberte jenom účty v tomto organizačním adresáři pro většinu aplikací. Další informace o jednotlivých možnostech najdete v tabulce.

    Typy podporovaných účtů Description
    Účty jen v tomto organizačním adresáři Pro aplikace pro jednoho tenanta, které mohou používat pouze uživatelé (nebo hosté) v rámci vašeho tenanta .
    Účty v libovolném organizačním adresáři U aplikací multitenant chcete, aby uživatelé v jakémkoli tenantovi Microsoft Entra mohli vaši aplikaci používat. Ideální pro aplikace typu software jako služba (SaaS), které chcete poskytnout více organizacím.
    Účty v jakémkoli organizačním adresáři a osobní účty Microsoft Pro aplikace multitenant, které podporují účty Microsoft organizacni a osobni (například Skype, Xbox, Live, Hotmail).
    Osobní účty Microsoft Pro aplikace používané pouze osobními účty Microsoft (například Skype, Xbox, Live, Hotmail).
  6. Výběrem možnosti Zaregistrovat dokončete registraci aplikace.

    Screenshot administračního centra Microsoft Entra ve webovém prohlížeči, zobrazující podokno Registrace aplikace.

  7. Zobrazí se stránka Přehled aplikace. Na stránce Přehled aplikace si poznamenejte následující hodnoty pro pozdější použití:

    • ID aplikace (klienta)
    • ID adresáře (klienta)

    Snímek obrazovky z administračního centra Microsoft Entra ve webovém prohlížeči, zobrazující podokno Přehled registrace aplikace.

Přidejte URI pro přesměrování

Ukázková aplikace v Pythonu používá interaktivní ověřování s průběhem přihlašování pomocí prohlížeče. Nakonfigurujte URI přesměrování pro zpracování odpovědi autentizace:

  1. V registraci aplikace v části Spravovat vyberte Ověřování.
  2. Vyberte Přidat platformu.
  3. Vyberte Mobilní a desktopové aplikace.
  4. V části Vlastní identifikátory URI přesměrování zadejte http://localhost.
  5. Vyberte a nakonfigurujte.

Přidání přihlašovacích údajů klienta

Sada Microsoft Entra ID Auth SDK (sidecar) používá přihlašovací údaje klienta k ověření a získání tokenů pro podřízená rozhraní API. Pro místní vývoj a testování použijte certifikát podepsaný svým držitelem k ověřování.

Vygenerovat samopodepsaný certifikát

Spusťte PowerShell jako správce a pomocí následujících příkazů vygenerujte certifikát podepsaný svým držitelem:

# Generate a self-signed certificate
$cert = New-SelfSignedCertificate `
    -Subject "CN=AgentID-Client-Certificate" `
    -CertStoreLocation "Cert:\CurrentUser\My" `
    -KeyExportPolicy Exportable `
    -KeySpec Signature `
    -KeyLength 2048 `
    -KeyAlgorithm RSA `
    -HashAlgorithm SHA256 `
    -NotAfter (Get-Date).AddDays(7)

# Export public key (CER) for upload to Azure
$cerPath = "agentid-client-certificate.cer"
Export-Certificate -Cert $cert -FilePath $cerPath

# Export private key (PFX) for the Entra ID Auth SDK (sidecar) container
# Replace <your-pfx-password> with a strong password and store it securely (for example, in a secret store).
$pfxPath = "agentid-client-certificate.pfx"
$certPassword = ConvertTo-SecureString -String "<your-pfx-password>" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath $pfxPath -Password $certPassword

Write-Host "Certificate generated successfully!"
Write-Host "CER file (public key): $cerPath"
Write-Host "PFX file (private key): $pfxPath"
Write-Host "Certificate Thumbprint: $($cert.Thumbprint)"

Zaznamenejte kryptografický otisk certifikátu zobrazený ve výstupu PowerShellu. Potřebujete ho k ověření certifikátu v Centrum pro správu Microsoft Entra odpovídá certifikátu nainstalovanému místně.

Nahrání certifikátu do Microsoft Entra ID

Pomocí následujícího postupu nahrajte soubor .cer vytvořený v aktuálním adresáři do Centrum pro správu Microsoft Entra:

  1. Otevření registrace aplikace v Centrum pro správu Microsoft Entra
  2. V části Spravovat vyberte Certifikáty a tajné kódy.
  3. Na kartě Certifikáty vyberte Nahrát certifikát.
  4. Vyberte soubor .cer, který jste vygenerovali (například agentid-client-cert.cer).
  5. Zadejte popis (například "AgentID Local Development Certificate").
  6. Vyberte Přidat.
  7. Poznamenejte si zobrazený kryptografický otisk certifikátu (měl by se shodovat s kryptografickým otiskem certifikátu z vaší generace certifikátu).

Poznámka:

V produkčních prostředích použijte certifikáty vydané důvěryhodnou certifikační autoritou (CA) a uložte je do Azure Key Vault s přístupem ke spravované identitě. Certifikáty podepsané svým držitelem používejte pouze pro místní vývoj a testování.

Konfigurace oprávnění API

Pomocí těchto kroků nakonfigurujte delegovaná oprávnění pro Microsoft Graph. S těmito oprávněními může klientská aplikace provádět operace jménem přihlášeného uživatele, například čtení e-mailu.

  1. V registraci aplikace v části Manage vyberte oprávnění API>Přidat oprávnění>Microsoft Graph.
  2. Vyberte Delegovaná oprávnění. Microsoft Graph zpřístupňuje mnoho oprávnění, přičemž nejčastěji se zobrazuje v horní části seznamu.
  3. V části Vybrat oprávnění vyberte a přidejte User.Read.

Konfigurace oprávnění aplikace

Pokud chcete otestovat toky pouze pro aplikace, ve kterých sada SDK Entra ID Auth (sidecar) volá rozhraní API s využitím vlastní identity (bez kontextu uživatele), nakonfigurujte oprávnění aplikace:

  1. Ze stránky oprávnění API vyberte Přidat oprávnění>.
  2. Vyberte Oprávnění aplikace.
  3. V části Vybrat oprávnění vyhledejte a vyberte User.Read.All.
  4. Vyberte Přidat oprávnění.
  5. Vyberte Udělit souhlas správce pro [Vašeho tenanta] a potvrďte.

Poznámka:

Oprávnění aplikace vyžadují souhlas správce. Bez tohoto kroku selžou koncové body pouze pro aplikaci v testovací části.

Zveřejnění rozhraní API (pro testování ověřování tokenů)

Chcete-li volat koncový bod /validate sady Entra ID Auth SDK (sidecar) pomocí tokenů vydaných speciálně pro vaši aplikaci (pomocí oboru api://<application-client-id>/access_as_user), musíte tento krok dokončit. Pokud testujete jenom Microsoft Graph scénáře s delegovanými oprávněními, můžete tuto část přeskočit. Pokud chcete zveřejnit rozhraní API obsahující požadované obory, postupujte takto:

  1. V části Spravovat vyberte Zveřejnit rozhraní API.

  2. V horní části stránky vyberte Přidat vedle identifikátoru URI ID aplikace. Tato hodnota je ve výchozím nastavení api://<application-client-id>. Identifikátor URI ID aplikace funguje jako předpona pro obory, na které budete odkazovat v kódu rozhraní API, a musí být globálně jedinečný. Vyberte Uložit.

  3. Vyberte Přidat obor , jak je znázorněno níže:

    Screenshot podokna Vystavení rozhraní API registrace aplikace v podokně Centrum pro správu Microsoft Entra.

  4. Dále zadejte atributy oboru v podokně Přidat obor následujícím způsobem:

    • Název oboru: access_as_user
    • Kdo může souhlasit: Správci a uživatelé
    • Zobrazovaný název souhlasu správce: Přístup k sadě Entra ID Auth SDK (sidecar) jménem uživatele
    • Popis souhlasu správce: Povolit přístup k rozhraním API sady SDK Auth Entra ID (sidecar) jménem přihlášeného uživatele
    • Stav: Povoleno
  5. Vyberte Přidat rozsah.

Spusťte sadu SDK pro ověřování Microsoft Entra ID (sidecar)

Microsoft Entra ID Auth SDK (sidecar) je kontejnerizovaná webová služba, která zajišťuje získávání tokenů, jejich ověřování a zabezpečené volání navazujícího rozhraní API. Běží jako doprovodný kontejner společně s vaší aplikací, takže můžete logiku identity přesměrovat na vyhrazenou službu.

Vytvoření konfiguračního souboru

Sada Entra ID Auth SDK (sidecar) vyžaduje konfigurační soubor pro připojení k Microsoft Entra aplikaci. Vytvořte nový adresář pro konfiguraci a vytvořte appsettings.json soubor:

# Create a directory for the Entra ID Auth SDK (sidecar) configuration
New-Item -ItemType Directory -Path "agentid-config" -Force
cd agentid-config

# Create the appsettings.json file
New-Item -ItemType File -Path "appsettings.json"

Otevřete appsettings.json v preferovaném textovém editoru a přidejte následující konfiguraci a nahraďte zástupné hodnoty podrobnostmi o aplikaci Microsoft Entra:

{
    "AzureAd": {
        "Instance": "https://login.microsoftonline.com/",
        "TenantId": "YOUR_TENANT_ID_HERE",
        "ClientId": "YOUR_CLIENT_ID_HERE",
        "ClientCredentials": [
            {
                "SourceType": "Path",
                "CertificateStorePath": "agentid-client-certificate.pfx",
                "CertificateDistinguishedName": "<your-pfx-password>"
            }
        ]
    },
    "DownstreamApis": {
        "me": {
            "BaseUrl": "https://graph.microsoft.com/v1.0/",
            "RelativePath": "me",
            "Scopes": [ "User.Read" ]
        }
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning"
        }
    },
    "AllowedHosts": "*"
}

Stáhněte a spusťte kontejner Entra ID Auth SDK (sidecar)

Sada Entra ID Auth SDK (sidecar) je k dispozici jako předem připravená image kontejneru ze služby Microsoft Container Registry (MCR). Před stažením image kontejneru ověřte, že Docker Desktop běží. Pokud Docker není spuštěný, otevřete Docker Desktop a počkejte, až se zobrazí stav Docker Desktop je spuštěný.

Přejděte do konfiguračního adresáře a spusťte následující příkazy:

# Navigate to your config directory
cd agentid-config

# Pull the Entra ID Auth SDK (sidecar) container image from MCR
docker pull mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-rc.2-azurelinux3.0-distroless

# Run the container
docker run -d `
    --name agentid-sdk `
    -p 5178:8080 `
    -e ASPNETCORE_ENVIRONMENT=Development `
    mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-rc.2-azurelinux3.0-distroless

# Copy configuration files into the container
docker cp appsettings.json agentid-sdk:/app/appsettings.json
docker cp agentid-client-certificate.pfx agentid-sdk:/app/agentid-client-certificate.pfx

# Restart the container to apply the configuration
docker restart agentid-sdk

Poznámka:

Pro hostitele Windows použijte variantu kontejneru Windows: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-rc.2-windows

Kontejner sady Entra ID Auth SDK (sidecar) můžete spravovat pomocí následujících příkazů Dockeru:

  • Zobrazení protokolů kontejneru: docker logs agentid-sdk
  • Zobrazení protokolů v reálném čase: docker logs -f agentid-sdk
  • Zastavte kontejner: docker stop agentid-sdk
  • Znovu spusťte kontejner: docker start agentid-sdk
  • Odeberte kontejner: docker rm agentid-sdk

Ověřte, že je kontejner spuštěný.

Pomocí volání koncového bodu/healthz kontroly stavu můžete ověřit, jestli kontejner sady Entra ID Auth SDK (sidecar) běží správně:

Invoke-RestMethod -Uri "http://localhost:5178/healthz" -ErrorAction SilentlyContinue

Tento koncový bod rozhraní vrací Healthy, což potvrzuje, že sada SDK pro ověřování Entra ID (sidecar) běží správně a je připraven k obsluze požadavků. Během testování neukončujte Entra ID Auth SDK (sidecar). Kontejner musí běžet na pozadí, aby veškerá volání autentizace a API z aplikace Python fungovala.

Spuštění ukázkové aplikace Python

Ukázková aplikace Python ukazuje, jak používat sadu Microsoft Entra ID Auth SDK (sidecar) pro ověřování a volání rozhraní API. Sada SDK Entra ID Auth (sidecar) běží jako lokální webová služba a funguje jako proxy server pro ověřování. Ověřuje tokeny uživatelů a volá podřízená rozhraní API, jako je Microsoft Graph vaším jménem.

Ukázka obsahuje Python skripty, které zobrazují dva vzory ověřování:

  • Delegovaná oprávnění: Sada Entra ID Auth SDK (sidecar) ověřuje token uživatele a volá rozhraní API jménem přihlášeného uživatele.
  • Oprávnění aplikace: Sada ENTRA ID Auth SDK (sidecar) používá k volání rozhraní API bez kontextu uživatele vlastní identitu.

Tento přístup centralizuje správu tokenů a přístup k rozhraní API v jedné službě, kterou vaše aplikace můžou využívat prostřednictvím jednoduchých požadavků HTTP.

Klonování nebo stažení ukázkové aplikace Python

Načtěte ukázkovou aplikaci Python a extrahujte ji do místního adresáře. Případně naklonujte úložiště tak, že otevřete příkazový řádek, přejdete do požadovaného umístění projektu a spustíte následující příkaz:

git clone https://github.com/AzureAD/microsoft-identity-web.git
cd microsoft-identity-web/tests/DevApps/SidecarAdapter/python

Ukázková aplikace obsahuje následující Python skripty:

  • get_token.py – získává přístupové tokeny uživatelů prostřednictvím Identity a ověřování Microsoftu (MSAL).
  • main.py – Rozhraní příkazového řádku, které volá koncové body sady SDK Entra ID Auth (sidecar) a zobrazuje odpovědi ve formátu JSON.
  • MicrosoftIdentityWebSidecarClient.py – obálka HTTP klienta pro koncové body /Validate, /AuthorizationHeader a /DownstreamApi sady SDK Entra ID Auth (sidecaru).

Skripty Python používají parametr me při volání koncových bodů sady Entra ID Auth SDK (sidecar). Tento parametr odkazuje na konfiguraci podřízeného rozhraní API s názvem "me" v sadě Entra ID Auth SDK (sidecar)sappsettings.json:

"DownstreamApis": {
    "me": {
        "BaseUrl": "https://graph.microsoft.com/v1.0/",
        "RelativePath": "me",
        "Scopes": [ "User.Read" ]
    }
}

Když zavoláte koncový bod sady Entra ID Auth SDK (sidecar) s parametremme, sada SDK použije základní adresu URL a relativní cestu z konfigurace k vytvoření úplného koncového bodu rozhraní API, vyžádá zadané obory a zavolá koncový bod Microsoft Graph /me k načtení profilu přihlášeného uživatele. Můžete přidat další konfigurace podřízených rozhraní API do appsettings.json s různými názvy a koncovými body pro volání dalších rozhraní API.

Testování interakce mezi sadou MICROSOFT ENTRA ID Auth SDK (sidecar) a aplikací Python

Tento rychlý start ukazuje vzor třívrstvého ověřování:

  1. Ověření uživatele: Přístupový token uživatele získáte pomocí knihovny MSAL pro Python. Tento token prokáže identitu uživatele.
  2. Ověření tokenu: Sada Entra ID Auth SDK (sidecar) ověří token uživatele, aby se zajistilo, že je ověřovací a vydaný pro vaši aplikaci.
  3. Výměna tokenů: Sada SDK Entra ID Auth (sidecar) používá tok On-Behalf-Of (OBO) k výměně uživatelského tokenu za nový token určený pro Microsoft Graph a poté volá rozhraní API.

V případě scénářů jen pro aplikace obchází sada Entra ID Auth SDK (sidecar) ověřování uživatelů a k získání tokenů používá vlastní přihlašovací údaje klienta. Sada SDK tuto logiku ověřování centralizuje, takže vaše Python aplikace potřebuje provádět jednoduché požadavky HTTP bez nutnosti spravovat složité toky OAuth.

Získání přístupového tokenu uživatele

Před testováním koncových bodů sady Entra ID Auth SDK (sidecar) získejte platný přístupový token. Skript get_token.py používá Python knihovnu MSAL k interaktivnímu získání tokenů prostřednictvím toku přihlašování založeného na prohlížeči.

Obory tokenů a cílové skupiny:

Rozsah, který požadujete, určuje cílovou skupinu tokenu (aud nárok), který musí odpovídat koncovému bodu, na který voláte:

  • Pro testování ověřování tokenů použijte api://<client-id>/access_as_user k otestování koncového /validate bodu.
  • Pro testování Microsoft Graph získejte nový token s oborem User.Read pro testování koncových bodů /authorizationheader a /downstreamapi

Pomocí následujících příkazů nastavte konfigurační proměnné a získejte token:

# Set your configuration
$clientId = "YOUR_CLIENT_ID_HERE"
$tenantId = "YOUR_TENANT_ID_HERE"
$authority = "https://login.microsoftonline.com/$tenantId"

# For testing Entra ID Auth SDK (sidecar) APIs (if you exposed the API)
$scope = "api://$clientId/access_as_user"

# Or for testing Microsoft Graph directly
# $scope = "User.Read"

# Acquire token
$token = uv run --with msal get_token.py --client-id $clientId --authority $authority --scope $scope

Když spustíte příkaz získání tokenu, skript zahájí interaktivní tok přihlášení založený na prohlížeči. K tomuto ověřování v prohlížeči dochází pouze při prvním spuštění. Po úspěšném ověření se token místně ukládá do mezipaměti pro následné použití. Přístupový token se pak vytiskne do konzoly a uloží se do proměnné PowerShellu $token pro použití v následných příkazech.

Otestování koncových bodů sady Microsoft Entra ID Auth SDK (sidecar) s delegovanými oprávněními

Po získání platného tokenu uživatele můžete otestovat základní koncové body sady Entra ID Auth SDK (sidecar). Tyto operace používají delegovaná oprávnění, takže sada SDK funguje jménem přihlášeného uživatele.

Nejprve nastavte základní adresu URL sady SDK:

$side_car_url = "http://localhost:5178"

1. Ověření tokenu uživatele

Koncový /validate bod vyžaduje token vydaný speciálně pro vaši aplikaci pomocí api://<client-id>/access_as_user rozsahu. Než otestujete ověření tokenu, ujistěte se, že jste dokončili kroky v části Zveřejnění rozhraní API. K volání koncového /validate bodu použijte následující příkaz.

uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" validate

Očekávaná odpověď:

Koncový bod /validate zkontroluje platnost tokenu a extrahuje informace o nárocích.

{
  "protocol": "Bearer",
  "token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6...",
  "claims": {
    "aud": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "iss": "https://login.microsoftonline.com/...",
    "name": "Your Name",
    "upn": "your.email@domain.com"
  }
}

Tato odpověď potvrzuje, že:

  • Formát tokenu je správný (nosný token)
  • Token vydává očekávaná autorita.
  • Cílová skupina (aud) odpovídá vaší aplikaci
  • Deklarace identity uživatele jsou přítomné a platné.

2. Získání autorizační hlavičky pro Microsoft Graph

Koncový /authorizationheader bod načte správně formátovanou autorizační hlavičku pro volání podřízených rozhraní API:

uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" get-auth-header me

Tento koncový bod:

  • Ověří příchozí token uživatele.
  • Získá nový token pro Microsoft Graph jménem uživatele.
  • Vrátí formátovanou autorizační hlavičku.

3. Volání rozhraní Microsoft Graph prostřednictvím sady SDK pro ověřování Microsoft Entra ID (sidecar)

Koncový bod /downstreamapi volá Microsoft Graph přímo a vrátí odpověď:

uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" invoke-downstream me

Očekávaná odpověď:

{
  "statusCode": 200,
  "headers": {...},
  "content": {
    "displayName": "Your Name",
    "mail": "your.email@domain.com",
    "userPrincipalName": "your.email@domain.com"
  }
}

Parametr me odpovídá konfiguraci podřízeného rozhraní API, kterou jste definovali v appsettings.json. SDK pro ověřování Entra ID (sidecar):

  1. Ověří token uživatele.
  2. Získá nový token pro Microsoft Graph pomocí toku on-behalf-of (OBO).
  3. Zavolá koncový bod /me na Microsoft Graph
  4. Vrátí data profilu uživatele.

4. Přepsat výchozí obory a zadat text požadavku

Volání rozhraní API můžete přizpůsobit přepsáním výchozích oborů nakonfigurovaných v appsettings.json nebo poskytnutím textu požadavku pro operace zápisu.

uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" --scope <scopes> invoke-downstream <api-name> --body-file <path-to-file>

Tento přístup je užitečný v těchto případech:

  • Testování různých úrovní oprávnění Můžete například zadat různé obory, jako je --scope User.Read Mail.Read , a požádat o další oprávnění.
  • Podřízené rozhraní API vyžaduje, aby obory nebyly ve výchozím nastavení nakonfigurované.
  • Potřebujete dynamicky požádat o další oprávnění.
  • Při volání API, která vyžadují text požadavku (například při vytváření nebo aktualizaci prostředků), můžete přidat volitelný parametr --body-file, který se používá v operacích POST/PUT.

Testování koncových bodů pouze pro aplikaci

Sada SDK Microsoft Entra ID Auth (sidecar) také podporuje toky určené pouze pro aplikace. V těchto tocích používá sada SDK Entra ID Auth (sidecar) identitu vlastní aplikace namísto toho, aby jednala jménem uživatele. Tyto koncové body nevyžadují autorizační hlavičku uživatele.

Poznámka:

Toky pouze pro aplikace vyžadují, aby registrace aplikace měla oprávnění aplikace (například User.Read.All) v Microsoft Entra ID, ne pouze delegovaná oprávnění. Než budete moct tyto koncové body otestovat, musí správce udělit souhlas s těmito oprávněními.

Získejte autorizační hlavičku bez kontextu uživatele

Pomocí tohoto endpointu načtěte autorizační hlavičku pro volání Microsoft Graphu pomocí vlastní identity Entra ID Auth SDK (sidecar):

uv run --with requests main.py --base-url $side_car_url get-auth-header-unauth me

Tento koncový bod:

  • K ověřování používá přihlašovací údaje klienta sady Entra ID Auth SDK (sidecar) (identita aplikace).
  • Získá přístupový token jen pro aplikaci pro Microsoft Graph
  • Vrátí autorizační hlavičku.

Volání Microsoft Graph bez kontextu uživatele

Pomocí tohoto koncového bodu můžete volat Microsoft Graph přímo pomocí identity sady Entra ID Auth SDK (sidecar):

uv run --with requests main.py --base-url $side_car_url invoke-downstream-unauth me

Tento příklad ukazuje komunikaci mezi službami, kde:

  • Do toku ověřování není zapojen žádný uživatel.
  • Entra ID Auth SDK (sidecar) se ověřuje pomocí vlastního ID klienta a certifikátu.
  • Volání rozhraní API používá oprávnění aplikace, nikoli delegovaná oprávnění.
  • Tento model je ideální pro služby na pozadí, dávkové zpracování nebo automatizované úlohy.

Vysvětlení odpovědí

Struktura odpovědi na ověření tokenu

Odpověď na ověření poskytuje podrobné informace o tokenu:

Obor Description
protocol Schéma ověřování (vždy "Bearer") pro tokeny OAuth 2.0
token Původní přístupový token (zkrácený v příkladech)
claims Páry klíč-hodnota extrahované z datové části tokenu
claims.aud Zamýšlená cílová skupina (ID klienta)
claims.iss Vystavitel tokenu (Microsoft Entra ID)
claims.name Zobrazované jméno přihlášeného uživatele
claims.upn Hlavní název uživatele (e-mailová adresa)

Microsoft Graph struktura odpovědi volání

Obor Description
statusCode Stavový kód HTTP z Microsoft Graph (200 = úspěch)
headers Hlavičky odpovědi z volání rozhraní API
content Skutečná data vrácená Microsoft Graph
content.displayName Zobrazované jméno uživatele v adresáři
content.mail E-mailová adresa uživatele
content.userPrincipalName UPN uživatele

Řešení běžných problémů

Pokud při testování koncových bodů sady SDK Microsoft Entra ID Auth (sidecar) narazíte na chyby, podívejte se na následující řešení běžných problémů:

Problém Solution
Chyby "Připojení odmítnuto" Ověřte, že je spuštěný kontejner Entra ID Auth SDK (sidecar): docker ps -a. Pokud se ve stavu kontejneru zobrazuje stav Konec, zkontrolujte protokoly: docker logs agentid-sdk. Restartujte kontejner: docker start agentid-sdk a otestujte koncový bod stavu: Invoke-RestMethod -Uri "http://localhost:5178/healthz".
Kontejner vrátí vnitřní chybu serveru 500. Zobrazit protokoly kontejneru pro podrobnosti o chybách: docker logs agentid-sdk. Běžné příčiny: neplatný kód JSON v appsettings.jsonnesprávné cestě k certifikátu, nesprávné heslo certifikátu nebo chybějící hodnoty TenantId/ClientId.
Chyby kvůli nenalezení certifikátu Ujistěte se, že se soubor PFX zkopíroval správně: docker exec agentid-sdk ls -la /app/agentid-client-certificate.pfx. Pokud chybí, zkopírujte ho znovu: docker cp agentid-client-certificate.pfx agentid-sdk:/app/agentid-client-certificate.pfx a restartujte: docker restart agentid-sdk.
Chyby "Neplatný token" nebo "Ověření publika selhalo" Ujistěte se, že publikum vašeho tokenu (aud nárok) odpovídá vašemu ID klienta. /validate Pro koncový bod použijte api://<client-id>/access_as_user obor. Pro Microsoft Graph volání použijte User.Read. Vymažte mezipaměť tokenů: Remove-Item -Path "$env:USERPROFILE\.msal_token_cache.bin" -ErrorAction SilentlyContinue.
appsettings.json se nenačítá Ověřte, že se soubor zkopíroval do kontejneru: docker exec agentid-sdk cat /app/appsettings.json. Ujistěte se, že je JSON platný (bez komentářů, správné syntaxe). Pokud soubor chybí nebo je nesprávný, zkopírujte ho znovu a restartujte kontejner.
Kontejner se po změnách konfigurace nespustí. Zastavte a odeberte kontejner: docker stop agentid-sdk && docker rm agentid-sdk. Spusťte kontejner znovu s aktualizovanými konfiguračními soubory podle části „Stažení a spuštění kontejneru Entra ID Auth SDK (sidecar)“.