Hızlı Başlangıç Kılavuzu: Microsoft Entra SDK'sını Python'da Aracı Kimliği için kullanarak kullanıcıların oturum açmasını sağlayın ve aşağı akış API'leri çağırın.

Bu hızlı başlangıçta, kullanıcı veya aracılarda oturum açmayı ve kendi kimliğini kullanarak aşağı akış API'lerini çağırmayı öğrenmek için örnek bir web uygulaması kullanacaksınız. Örnek uygulama, yetkilendirilmiş erişim için kullanıcı belirteçlerini doğrulamak üzere Microsoft Entra SDK'sını ve Microsoft Graph gibi son nokta API'leriyle hizmetler arası iletişim için uygulama kimliğini kullanır.

Önkoşullar

UV paket yöneticisini yükleyin. UV, Rust ile yazılmış hızlı bir Python paket yükleyicisi ve çözümleyicidir.
Docker Desktop'ı yükleyin.
Etkin aboneliği olan bir Azure hesabı. Henüz bir hesabınız yoksa, ücretsiz bir hesap oluşturun .
Bu Azure hesabının uygulamaları yönetme izinleri olmalıdır. Aşağıdaki Microsoft Entra rollerinden herhangi biri gerekli izinleri içerir:
- Uygulama Yöneticisi
- Uygulama Geliştirici
Çalışma amaçlı kiracı. Varsayılan Dizininizi kullanabilir veya yeni bir kiracı ayarlayabilirsiniz.

Microsoft Entra uygulamanızı oluşturma ve yapılandırma

Hızlı başlangıcın geri kalanını tamamlamak için önce bir uygulamayı Microsoft Entra ID'a kaydetmeniz gerekir.

Uygulama kaydı oluşturma

Uygulama kaydını oluşturmak için şu adımları izleyin:

En azından bir Application Developer olarak Microsoft Entra yönetim merkezi'a oturum açın.
Birden çok kiracıya erişiminiz varsa, uygulamayı kaydetmek istediğiniz kiracıya geçmek için üst menüdeki Ayarlar simgesini kullanın.
Entra ID>Uygulama kayıtları adresine gidin ve Yeni kayıt öğesini seçin.
Uygulamanız için identity-client-app gibi anlamlı bir Ad girin. Uygulama kullanıcıları bu adı görür ve istediğiniz zaman değiştirebilirsiniz. Aynı isimde birden fazla uygulama kaydınız olabilir.

Desteklenen hesap türlerialtında uygulamayı kimlerin kullanabileceğini belirtin. Çoğu uygulama için bu kuruluş dizinindeki Hesaplar'ı seçin. Her seçenek hakkında daha fazla bilgi için tabloya bakın.

Desteklenen hesap türleri	Description
Yalnızca bu kuruluş dizinindeki hesaplar	Yalnızca kiracınızda kullanıcılar (veya konuklar) tarafından kullanılmak üzere tek kiracılı uygulamalar için.
Herhangi bir kuruluş dizinindeki hesaplar	multitenant uygulamaları için ve any Microsoft Entra kiracılarındaki kullanıcıların uygulamanızı kullanabilmesini istiyorsunuz. Birden çok kuruluşa sağlamayı planladığınız hizmet olarak yazılım (SaaS) uygulamaları için idealdir.
Herhangi bir kuruluş dizinindeki ve kişisel Microsoft hesaplarındaki hesaplar	multitenant hem kurumsal hem de kişisel Microsoft hesaplarını (örneğin, Skype, Xbox, Live, Hotmail) destekleyen uygulamalar için.
Genel Microsoft hesapları	Yalnızca kişisel Microsoft hesapları (örneğin, Skype, Xbox, Live, Hotmail) tarafından kullanılan uygulamalar için.

Uygulama kaydını tamamlamak için Kaydet'i seçin.
Uygulamanın Genel Bakış sayfası görüntülenir. Daha sonra kullanmak üzere uygulamaya Genel Bakış sayfasından aşağıdaki değerleri kaydedin:
- Uygulama (istemci) kimliği
- Dizin (kullanıcı) kimliği

Yeniden yönlendirme URI'sini ekleme

Python örnek uygulaması, tarayıcı tabanlı oturum açma akışıyla etkileşimli kimlik doğrulaması kullanır. Kimlik doğrulama yanıtını işlemek için yeniden yönlendirme URI'sini yapılandırın:

Uygulama kaydınızda Yönet'in altında Kimlik Doğrulama'yı seçin.
Platform ekle'yi seçin.
Mobil ve masaüstü uygulamaları'nı seçin.
Özel yeniden yönlendirme URI'leri bölümüne girinhttp://localhost.
'i seçin ve'i yapılandırın.

İstemci kimlik bilgileri ekleme

Aracı Kimliği için Microsoft Entra SDK'sı, aşağı akış API'leri için kimlik doğrulaması yapmak ve belirteçleri almak için istemci kimlik bilgilerini kullanır. Yerel geliştirme ve test için kimlik doğrulaması için otomatik olarak imzalanan bir sertifika kullanın.

Otomatik olarak imzalanan sertifika oluşturma

PowerShell'i yönetici olarak çalıştırın ve otomatik olarak imzalanan bir sertifika oluşturmak için aşağıdaki komutları kullanın:

# 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 Agent ID SDK 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)"

PowerShell çıkışında görüntülenen sertifika parmak izini kaydedin. Microsoft Entra yönetim merkezindeki sertifikanın yerel olarak yüklenen sertifikayla eşleşip eşleşmediğini doğrulamak için bunu kullanmanız gerekir.

Sertifikayı Microsoft Entra ID'a yükleme

Geçerli dizininizde oluşturulan .cer dosyasını Microsoft Entra yönetim merkezi yüklemek için şu adımları izleyin:

Uygulama kaydınızı Microsoft Entra yönetim merkezi açın
Yönet altında Sertifikalar ve gizli anahtarlar'ı seçin.
Sertifikalar sekmesinde Sertifikayı karşıya yükle'yi seçin.
.cer Oluşturduğunuz dosyayı seçin (örneğin, agentid-client-cert.cer).
Bir açıklama sağlayın (örneğin, "AgentID Yerel Geliştirme Sertifikası").
Add (Ekle) seçeneğini belirleyin.
Görüntülenen sertifika Parmak İzi'ni kaydedin (sertifika oluşturma işleminizdeki sertifikayla eşleşmelidir).

Uyarı

Üretim ortamları için, güvenilen bir Sertifika Yetkilisi (CA) tarafından verilen sertifikaları kullanın ve yönetilen kimlik erişimi olan Azure Key Vault depolayın. Otomatik olarak imzalanan sertifikaları yalnızca yerel geliştirme ve test için kullanın.

API izinlerini yapılandırma

Microsoft Graph için temsilci izinlerini yapılandırmak için bu adımları izleyin. Bu izinlerle, istemci uygulamanız oturum açmış kullanıcı adına e-postasını okuma gibi işlemler gerçekleştirebilir.

Uygulama kaydınızda, Manage altında API izinleri> İzin ekle>Microsoft Graph öğesini seçin.
Atanan izinler'i seçin. Microsoft Graph, en yaygın olarak kullanılanların listenin en üstünde gösterildiği birçok izni sunar.
İzinleri seç'in altında User.Read öğesini seçin ve ekleyin.

Uygulama izinlerini yapılandırma

Aracı Kimliği SDK'sının API'leri kendi kimliğini (kullanıcı bağlamı olmadan) kullanarak çağırdığı yalnızca uygulama akışlarını test etmek için uygulama izinlerini yapılandırın:

API izinleri sayfasında İzin ekle>Microsoft Graph öğesini seçin.
Uygulama izinleri'ni seçin.
İzinleri seçin'in altında User.Read.All öğesini arayın ve seçin.
İzinler ekle'yi seçin.
[Kiracınız] için yönetici onayı ver'i seçin ve onaylayın.

Uyarı

Uygulama izinleri için yönetici onayı gerekir. Bu adım olmadan, test bölümündeki yalnızca uygulama uç noktaları başarısız olur.

API'yi kullanıma sunma (belirteç doğrulama testi için)

Aracı Kimliği SDK'sının /validate uç noktasını uygulamanız için özel olarak verilen belirteçlerle çağırmak için (kapsamı kullanarak api://<application-client-id>/access_as_user) bu adımı tamamlamanız gerekir. Yalnızca temsilci izinlerine sahip Microsoft Graph senaryoları test ediyorsanız bu bölümü atlayabilirsiniz. Gerekli kapsamları içeren bir API'yi kullanıma açmak için şu adımları izleyin:

Yönetaltında, Bir API'yi Kullanıma Sunmaseçin.
Sayfanın üst kısmında Uygulama Kimliği URI'si'nin yanındaki Ekle'yi seçin. Bu değer varsayılan olarak olarak gösterilir api://<application-client-id>. Uygulama Kimliği URI'si, API'nizin kodunda başvurabileceğiniz kapsamlar için ön ek görevi görür ve genel olarak benzersiz olmalıdır. Kaydetseçeneğini seçin.
Gösterildiği gibi Kapsam ekle'yi seçin:
Ardından Kapsam ekle bölmesinde kapsamın özniteliklerini aşağıdaki gibi belirtin:
- Kapsam adı: access_as_user
- Kim onay verebilir: Yöneticiler ve kullanıcılar
- Yönetici onayı görünen adı: Kullanıcı olarak Agent ID SDK'sına erişme
- Yönetici onayı açıklaması: Oturum açmış kullanıcı olarak Aracı Kimliği SDK API'lerine erişime izin ver
- Durum: Aktif
Kapsam ekle'yi seçin.

AgentID için Microsoft Entra SDK'sını başlatma

Aracı Kimliği için Microsoft Entra SDK'sı, belirteç alma, doğrulama ve aşağı akış API çağrılarının güvenliğini sağlayan kapsayıcılı bir web hizmetidir. Uygulamanızın yanında yardımcı kapsayıcı olarak çalışır ve kimlik mantığını ayrılmış bir hizmete boşaltmanıza olanak sağlar.

Yapılandırma dosyası oluşturma

Aracı Kimliği SDK'sı, Microsoft Entra uygulamanıza bağlanmak için bir yapılandırma dosyası gerektirir. Yapılandırmanız için yeni bir dizin oluşturun ve bir appsettings.json dosya oluşturun:

# Create a directory for the Agent ID SDK configuration
New-Item -ItemType Directory -Path "agentid-config" -Force
cd agentid-config

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

tercih ettiğiniz metin düzenleyicisinde appsettings.json açın ve yer tutucu değerlerini Microsoft Entra uygulama ayrıntılarınızla değiştirerek aşağıdaki yapılandırmayı ekleyin:

{
    "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": "*"
}

Ajans Kimliği SDK kapsayıcısını çekin ve çalıştırın

Agent ID SDK, Microsoft Container Registry (MCR)'den hazır kapsayıcı görüntüsü olarak kullanılabilir. Kapsayıcı görüntüsünü çekmeden önce Docker Desktop'ın çalıştığını doğrulayın. Docker çalışmıyorsa Docker Desktop'ı açın ve "Docker Desktop çalışıyor" durumunun gösterilmesini bekleyin.

Yapılandırma dizininize gidin ve aşağıdaki komutları çalıştırın:

# Navigate to your config directory
cd agentid-config

# Pull the Agent ID SDK 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

Uyarı

Windows konaklar için Windows kapsayıcı değişkenini kullanın: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-rc.2-windows

Aracı Kimliği SDK kapsayıcısını yönetmek için aşağıdaki Docker komutlarını kullanabilirsiniz:

Kapsayıcı günlüklerini görüntüleme: docker logs agentid-sdk
Gerçek zamanlı günlükleri görüntüleme: docker logs -f agentid-sdk
Kapsayıcıyı durdurun: docker stop agentid-sdk
Kapsayıcıyı yeniden başlatın: docker start agentid-sdk
Kapsayıcıyı kaldırın: docker rm agentid-sdk

Kapsayıcının çalıştığını doğrulayın

Durum denetimi uç noktasını/healthz çağırarak Aracı Kimliği SDK kapsayıcısının doğru çalışıp çalışmadığını doğrulayabilirsiniz:

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

Bu uç nokta, Aracı Kimliği SDK'sının doğru çalıştığını ve istekleri işlemeye hazır olduğunu onaylayan döndürür Healthy. Test sırasında Ajan Kimliği SDK'sını sonlandırmayın. Python uygulamasından gelen tüm kimlik doğrulaması ve API çağrılarının çalışması için kapsayıcının arka planda çalışmaya devam etmesi gerekir.

Python örnek uygulamasını çalıştırma

Python örnek uygulaması, kimlik doğrulaması ve API çağrıları için Aracı Kimliği için Microsoft Entra SDK'sının nasıl kullanılacağını gösterir. Aracı Kimliği SDK'sı yerel bir web hizmeti olarak çalışır ve bir kimlik doğrulama proxy'si olarak çalışır. Kullanıcı belirteçlerini doğrular ve sizin adınıza Microsoft Graph gibi aşağı akış API'lerini çağırır.

Örnek, iki kimlik doğrulama deseni gösteren Python betikleri içerir:

Temsilci izinleri: Aracı Kimliği SDK'sı kullanıcı belirtecinizi doğrular ve oturum açmış kullanıcı adına API'leri çağırır.
Uygulama izinleri: Aracı Kimliği SDK'sı, kullanıcı bağlamı olmadan API'leri çağırmak için kendi kimliğini kullanır.

Bu yaklaşım, uygulamalarınızın basit HTTP istekleri aracılığıyla kullanabileceği tek bir hizmette belirteç yönetimini ve API erişimini merkezileştirir.

Python örnek uygulamasını kopyalama veya indirme

Python örnek uygulamasını indirin ve yerel dizine ayıklayın. Alternatif olarak, bir komut istemi açarak, istediğiniz proje konumuna giderek ve aşağıdaki komutu çalıştırarak depoyu kopyalayın:

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

Örnek uygulama aşağıdaki Python betiklerini içerir:

get_token.py – Microsoft Authentication Library (MSAL) aracılığıyla kullanıcı erişim belirteçleri alır.
main.py – Aracı Kimliği SDK uç noktalarını çağıran ve JSON yanıtlarını görüntüleyen komut satırı arabirimi.
MicrosoftIdentityWebSidecarClient.py – Aracı Kimliği SDK'sının /Validate, /AuthorizationHeaderve /DownstreamApi uç noktaları için HTTP istemci sarmalayıcısı.

Python betikleri, Aracı Kimliği SDK uç noktalarını çağırırken me parametresini kullanır. Bu parametre, Aracı Kimliği SDK'larında "me" adlı aşağı akış API yapılandırmasına başvurur appsettings.json:

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

me parametresiyle bir Aracı Kimliği SDK uç noktasını çağırdığınızda, SDK tam API uç noktasını oluşturmak için yapılandırmadan temel URL'yi ve göreli yolu kullanır, belirtilen kapsamları ister ve oturum açmış kullanıcının profilini almak için Microsoft Graph /me uç noktasını çağırır. Ek API'ler çağırmak üzere, appsettings.json'a farklı adlar ve uç noktalar ile ek aşağı akış API yapılandırmaları ekleyebilirsiniz.

Aracı Kimliği için Microsoft Entra SDK'sı ile Python uygulaması arasındaki etkileşimi test edin

Bu hızlı başlangıçta üç katmanlı kimlik doğrulama deseni gösterilmektedir:

Kullanıcı kimlik doğrulaması: Python için MSAL kullanarak bir kullanıcı erişim belirteci alırsınız. Bu belirteç kullanıcının kimliğini kanıtlar.
Belirteç doğrulama: Aracı Kimliği SDK'sı, kullanıcı belirtecini doğrular ve uygulamanız için doğrulandığından ve verildiğinden emin olur.
Token exchange: Agent ID SDK, kullanıcı belirtecini Microsoft Graph kapsamına sahip yeni bir belirteçle değiştirmek için On-Behalf-Of (OBO) akışını kullanır ve ardından API'yi çağırır.

Yalnızca uygulama senaryolarında Aracı Kimliği SDK'sı kullanıcı kimlik doğrulamasını atlar ve belirteçleri doğrudan almak için kendi istemci kimlik bilgilerini kullanır. SDK bu kimlik doğrulama mantığını merkezi hale getirir, bu nedenle Python uygulamanızın karmaşık OAuth akışlarını yönetmeden yalnızca basit HTTP istekleri yapması gerekir.

Kullanıcı erişim belirteci alma

Aracı Kimliği SDK uç noktalarını test etmeden önce geçerli bir erişim belirteci alın. get_token.py betiği, tarayıcı tabanlı oturum açma akışıyla etkileşimli olarak belirteçleri almak için Python için MSAL kitaplığını kullanır.

Belirteç kapsamları ve hedef kitleleri:

İstediğiniz kapsam, çağırdığınız uç noktayla eşleşmesi gereken belirtecin hedef kitlesini (aud talebi) belirler:

Belirteç doğrulama testi için, api://<client-id>/access_as_user kullanarak /validate uç noktasını test edin
Microsoft Graph testi için, User.Read ve /authorizationheader uç noktalarını test etmek için /downstreamapi kapsamına sahip yeni bir belirteç alın

Yapılandırma değişkenlerinizi ayarlamak ve belirteç almak için aşağıdaki komutları kullanın:

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

# For testing Agent ID SDK 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

Jeton edinme komutunu çalıştırdığınızda, betik etkileşimli bir tarayıcı tabanlı oturum açma akışını başlatır. Bu tarayıcı kimlik doğrulaması yalnızca ilk çalıştırmada gerçekleşir. Kimlik doğrulaması başarılı olduktan sonra belirteç, sonraki kullanım için yerel olarak önbelleğe alınır. Erişim belirteci daha sonra konsola yazdırılır ve sonraki komutlarda $token kullanılmak üzere PowerShell değişkeninde depolanır.

Microsoft Entra SDK'sını, delege edilmiş izinlerle Aracı Kimliği uç noktaları için test edin

Geçerli bir kullanıcı belirteci aldıktan sonra Aracı Kimliği SDK'sı çekirdek uç noktalarını test edebilirsiniz. Bu işlemler temsilci izinlerini kullandığından SDK, oturum açmış kullanıcı adına hareket eder.

İlk olarak SDK'nın temel URL'sini ayarlayın:

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

1. Kullanıcı belirtecini doğrulama

/validate uç noktası, api://<client-id>/access_as_user kapsamı kullanılarak uygulamanız için özel olarak verilen bir belirteç gerektirir. Belirteç doğrulamasını test etmeden önce "API'yi kullanıma sunma" bölümündeki adımları tamamladığınızdan emin olun. Uç noktayı çağırmak /validate için aşağıdaki komutu kullanın.

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

Beklenen yanıt:

Uç noktası /validate belirtecin geçerli olup olmadığını denetler ve kullanıcı bilgilerini ayıklar:

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

Bu yanıt şunu onaylar:

Belirteç biçimi doğru (Taşıyıcı belirteci)
Token beklenen yetkili tarafından çıkartılır
Hedef kitle (aud) uygulamanızla eşleşir
Kullanıcı kimliği talepleri mevcut ve geçerli

2. Microsoft Graph için yetkilendirme üst bilgisi alma

Uç nokta, aşağı akış API'lerini /authorizationheader çağırmak için düzgün biçimlendirilmiş bir yetkilendirme üst bilgisi alır:

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

Bu uç nokta:

Gelen kullanıcı belirtecini doğrular
Kullanıcı adına Microsoft Graph için yeni bir jeton alır
Biçimlendirilmiş yetkilendirme üst bilgisini döndürür

3. AgentID için Microsoft Entra SDK'sı aracılığıyla Microsoft Graph çağırın

/downstreamapi uç noktası doğrudan Microsoft Graph çağırır ve yanıtı döndürür:

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

Beklenen yanıt:

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

parametresi, me içinde tanımladığınız aşağı akış API yapılandırmasına appsettings.jsonkarşılık gelir. Aracı Kimliği SDK'sı:

Kullanıcı belirtecinizi doğrular
Adına (OBO) akışını kullanarak Microsoft Graph için yeni bir belirteç alır
Microsoft Graph'taki /me uç noktasını çağırır.
Kullanıcı profili verilerini döndürür

4. Varsayılan kapsamları geçersiz kılma ve istek gövdesi sağlama

içinde yapılandırılan appsettings.json varsayılan kapsamları geçersiz kılarak veya yazma işlemleri için bir istek gövdesi sağlayarak API çağrılarını özelleştirebilirsiniz.

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>

Bu yaklaşım aşağıdaki durumlarda kullanışlıdır:

Farklı izin düzeylerini test etme. Örneğin, ek izinler istemek için --scope User.Read Mail.Read gibi farklı kapsamlar belirtebilirsiniz
Aşağı akış API'sinde kapsamların varsayılan olarak yapılandırılmaması gerekir
Dinamik olarak ek izinler istemeniz gerekir
İstek gövdesi gerektiren API'leri çağırırken (kaynak oluşturma veya güncelleştirme gibi), POST/PUT işlemleri için kullanılan isteğe bağlı --body-file parametreyi eklersiniz

Yalnızca uygulama uç noktalarını test edin

Aracı Kimliği için Microsoft Entra SDK'sı yalnızca uygulama akışlarını da destekler. Bu akışlarda, Aracı Kimliği SDK'sı bir kullanıcı adına hareket etmek yerine kendi uygulama kimliğini kullanır. Bu uç noktalar için kullanıcı yetkilendirme üst bilgisi gerekmez.

Uyarı

Yalnızca uygulama akışları, uygulama kaydınızın Microsoft Entra ID'de application izinlerine (User.Read.All gibi) sahip olmasını gerektirir, yalnızca temsilci izinlerine sahip olması yeterli değildir. Bu uç noktaları test etmeden önce yöneticinin bu izinlere onay vermesi gerekir.

Kullanıcı bağlamı olmadan yetkilendirme üst bilgisini alma

Microsoft Graph'ı Aracı Kimliği SDK'sının kendi kimliğiyle çağırmak için bir yetkilendirme üst bilgisi almak üzere bu uç noktayı kullanın.

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

Bu uç nokta:

Kimlik doğrulaması yapmak için Aracı Kimliği SDK'sının istemci kimlik bilgilerini (uygulama kimliği) kullanır.
Microsoft Graph için uygulamaya özel erişim belirteci alır
Yetkilendirme üst bilgisini verir

Kullanıcı bağlamı olmadan Microsoft Graph çağırma

Agent ID SDK kimliğini kullanarak Microsoft Graph'ı doğrudan çağırmak için bu uç noktayı kullanın.

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

Bu örnekte aşağıdaki durumlarda hizmet-hizmet iletişimi gösterilmektedir:

Kimlik doğrulama akışına hiçbir kullanıcı dahil değil
Aracı Kimliği SDK'sı kendi istemci kimliğini ve sertifikasını kullanarak kimlik doğrulaması yapar
API çağrısı, temsilci izinleri değil uygulama izinlerini kullanır
Bu düzen arka plan hizmetleri, toplu işlem veya otomatik görevler için idealdir

Yanıtları anlama

Belirteç doğrulama yanıt yapısı

Doğrulama yanıtı belirteç hakkında ayrıntılı bilgi sağlar:

Veri Alanı	Description
`protocol`	Kimlik doğrulama düzeni (OAuth 2.0 belirteçleri için her zaman "Bearer")
`token`	Orijinal erişim tokenı (örneklerde kesilmiş)
`claims`	Belirteç yükünden ayıklanan anahtar-değer çiftleri
`claims.aud`	Hedeflenen hedef kitle (istemci kimliğiniz)
`claims.iss`	Belirteç sağlayıcı (Microsoft Entra ID)
`claims.name`	Oturum açmış kullanıcının görünen adı
`claims.upn`	Kullanıcı Asıl Adı (e-posta adresi)

Microsoft Graph çağrı yanıt yapısı

Veri Alanı	Description
`statusCode`	Microsoft Graph HTTP durum kodu (200 = başarı)
`headers`	API çağrısından yanıt üst bilgileri
`content`	Microsoft Graph tarafından döndürülen gerçek veriler
`content.displayName`	Kullanıcının dizindeki görünen adı
`content.mail`	Kullanıcının e-posta adresi
`content.userPrincipalName`	Kullanıcının UPN'i

Yaygın sorunları giderme

Aracı Kimliği uç noktaları için Microsoft Entra SDK'sını test ederken hatalarla karşılaşırsanız, yaygın sorunların aşağıdaki çözümlerini denetleyin:

Sorun	Çözüm
"Bağlantı reddedildi" hataları	Aracı Kimliği SDK kapsayıcısının çalıştığını doğrulayın: `docker ps -a`. Kapsayıcı durumu "Çıkış yaptı" olarak görünüyorsa günlükleri kontrol edin: `docker logs agentid-sdk`. Kapsayıcıyı yeniden başlatın: `docker start agentid-sdk` ve sistem durumu uç noktasını test edin: `Invoke-RestMethod -Uri "http://localhost:5178/healthz"`.
Kapsayıcı 500 İç Sunucu Hatası döndürüyor	Ayrıntılı hatalar için kapsayıcı günlüklerini görüntüleyin: `docker logs agentid-sdk`. Yaygın nedenler: içinde `appsettings.json`geçersiz JSON, yanlış sertifika yolu, yanlış sertifika parolası veya eksik TenantId/ClientId değerleri.
Bulunamayan sertifika hataları	PFX dosyasının doğru kopyalanmış olduğundan emin olun: `docker exec agentid-sdk ls -la /app/agentid-client-certificate.pfx`. Eksikse yeniden kopyalayın: `docker cp agentid-client-certificate.pfx agentid-sdk:/app/agentid-client-certificate.pfx` ve yeniden başlatın: `docker restart agentid-sdk`.
"Geçersiz belirteç" veya "İzleyici doğrulaması başarısız oldu" hataları	Jetonunuzun hedef kitlesinin (`aud` iddia) istemci kimliğiniz ile eşleştiğinden emin olun. `/validate` uç noktası için `api://<client-id>/access_as_user` kapsamını kullanın. Microsoft Graph çağrıları için `User.Read` kullanın. Belirteç önbelleğini temizleyin: `Remove-Item -Path "$env:USERPROFILE\.msal_token_cache.bin" -ErrorAction SilentlyContinue`.
appsettings.json yüklenmiyor	Dosyanın kapsayıcıya kopyalandığını doğrulayın: `docker exec agentid-sdk cat /app/appsettings.json`. JSON'un geçerli olduğundan emin olun (açıklama yok, doğru söz dizimi). Dosya eksik veya yanlışsa yeniden kopyalayın ve kapsayıcıyı yeniden başlatın.
Yapılandırma değişikliklerinin ardından kapsayıcı başlatılamıyor	Kapsayıcıyı durdurun ve silin: `docker stop agentid-sdk && docker rm agentid-sdk`. "Aracı Kimliği SDK kapsayıcısını çekme ve çalıştırma" bölümünden sonra güncelleştirilmiş yapılandırma dosyalarıyla kapsayıcıyı yeniden çalıştırın.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-04-19

Kullanıcıların oturum açmasını sağlayın ve Python için Microsoft Entra SDK'sı ile downstream API'lerini çağırarak Agent ID'yi kullanın.

Önkoşullar

Microsoft Entra uygulamanızı oluşturma ve yapılandırma

Uygulama kaydı oluşturma

Yeniden yönlendirme URI'sini ekleme

İstemci kimlik bilgileri ekleme

Otomatik olarak imzalanan sertifika oluşturma

Sertifikayı Microsoft Entra ID'a yükleme

API izinlerini yapılandırma

Uygulama izinlerini yapılandırma

API'yi kullanıma sunma (belirteç doğrulama testi için)

AgentID için Microsoft Entra SDK'sını başlatma

Yapılandırma dosyası oluşturma

Ajans Kimliği SDK kapsayıcısını çekin ve çalıştırın

Kapsayıcının çalıştığını doğrulayın

Python örnek uygulamasını çalıştırma

Python örnek uygulamasını kopyalama veya indirme

Aracı Kimliği için Microsoft Entra SDK'sı ile Python uygulaması arasındaki etkileşimi test edin

Kullanıcı erişim belirteci alma

Microsoft Entra SDK'sını, delege edilmiş izinlerle Aracı Kimliği uç noktaları için test edin

1. Kullanıcı belirtecini doğrulama

2. Microsoft Graph için yetkilendirme üst bilgisi alma

3. AgentID için Microsoft Entra SDK'sı aracılığıyla Microsoft Graph çağırın

4. Varsayılan kapsamları geçersiz kılma ve istek gövdesi sağlama

Yalnızca uygulama uç noktalarını test edin

Kullanıcı bağlamı olmadan yetkilendirme üst bilgisini alma

Kullanıcı bağlamı olmadan Microsoft Graph çağırma

Yanıtları anlama

Belirteç doğrulama yanıt yapısı

Microsoft Graph çağrı yanıt yapısı

Yaygın sorunları giderme

İlgili içerik

Geri Bildirim

Ek kaynaklar