Mengautentikasi pengguna dan memanggil API downstream dengan Microsoft Entra ID Auth SDK (sidecar) di Python

Dalam panduan cepat ini, Anda menggunakan aplikasi web contoh untuk mempelajari cara login pengguna atau agen dan memanggil API downstream dengan menggunakan identitas aplikasinya sendiri. Aplikasi sampel menggunakan Microsoft Entra ID Auth SDK (sidecar) untuk memvalidasi token pengguna untuk akses yang didelegasikan dan menggunakan identitas aplikasi untuk komunikasi layanan ke layanan dengan API hilir seperti Microsoft Graph.

Prasyarat

  • Instal manajer paket UV. UV adalah penginstal paket Python cepat dan resolver yang ditulis dalam Rust.

  • Instal Docker Desktop.

  • Akun Azure dengan langganan aktif. Jika Anda belum memilikinya, Buat akun secara gratis.

  • Akun Azure ini harus memiliki izin untuk mengelola aplikasi. Salah satu peran Microsoft Entra berikut ini mencakup izin yang diperlukan:

    • Administrator Aplikasi
    • Pengembang Aplikasi
  • Penyewa dari kalangan tenaga kerja. Anda dapat menggunakan Direktori Default Anda atau menyiapkan tenant baru.

Membuat dan mengonfigurasi aplikasi Microsoft Entra Anda

Untuk menyelesaikan sisa panduan memulai cepat, Anda harus terlebih dahulu mendaftarkan aplikasi di Microsoft Entra ID.

Membuat pendaftaran aplikasi

Ikuti langkah-langkah berikut untuk membuat pendaftaran aplikasi:

  1. Masuk ke pusat admin Microsoft Entra setidaknya sebagai Pengembang Aplikasi.

  2. Jika Anda memiliki akses ke beberapa penyewa, gunakan ikon Pengaturan di menu atas untuk beralih ke penyewa tempat Anda ingin mendaftarkan aplikasi.

  3. Telusuri ke Entra ID>Pendaftaran aplikasi dan pilih Pendaftaran baru.

  4. Masukkan Nama yang bermakna untuk aplikasi Anda, seperti identity-client-app. Pengguna aplikasi melihat nama ini, dan Anda dapat mengubahnya kapan saja. Anda dapat memiliki beberapa pendaftaran aplikasi dengan nama yang sama.

  5. Di bawah Jenis akun yang didukung, tentukan siapa yang dapat menggunakan aplikasi. Pilih Akun di direktori organisasi ini hanya untuk sebagian besar aplikasi. Lihat tabel untuk informasi selengkapnya tentang setiap opsi.

    Jenis akun yang didukung Description
    Akun dalam direktori organisasi ini saja Untuk aplikasi single-tenant yang digunakan hanya oleh pengguna (atau tamu) di penyewa Anda.
    Akun di direktori organisasi apa pun Untuk aplikasi multitenant, Anda ingin pengguna di setiap tenant Microsoft Entra dapat menggunakan aplikasi Anda. Ideal untuk aplikasi software-as-a-service (SaaS) yang ingin Anda sediakan ke beberapa organisasi.
    Akun di direktori organisasi dan akun Microsoft pribadi Untuk aplikasi multitenant yang mendukung akun Microsoft organisasi dan pribadi (misalnya, Skype, Xbox, Live, Hotmail).
    Akun Microsoft Pribadi Untuk aplikasi yang hanya digunakan oleh akun Microsoft pribadi (misalnya, Skype, Xbox, Live, Hotmail).
  6. Pilih Daftar untuk menyelesaikan pendaftaran aplikasi.

    Screenshot pusat admin Microsoft Entra di browser web, memperlihatkan panel Daftarkan aplikasi.

  7. Halaman Gambaran Umum aplikasi ditampilkan. Rekam nilai berikut dari halaman Gambaran Umum aplikasi untuk digunakan nanti:

    • ID Aplikasi (klien)
    • ID Direktori (Penyewa)

    Screenshot pusat admin Microsoft Entra di browser web, memperlihatkan panel Gambaran Umum pendaftaran aplikasi.

Menambahkan URI pengalihan

Aplikasi sampel Python menggunakan autentikasi interaktif dengan alur masuk berbasis browser. Konfigurasikan URI pengalihan untuk menangani respons autentikasi:

  1. Di pendaftaran aplikasi Anda, di bawah Kelola, pilih Autentikasi.
  2. Pilih Tambahkan platform.
  3. Pilih Aplikasi seluler dan desktop.
  4. Di bawah URI pengalihan kustom, masukkan http://localhost.
  5. Pilih Konfigurasikan.

Menambahkan kredensial klien

Microsoft Entra ID Auth SDK (sidecar) menggunakan kredensial klien untuk mengautentikasi dan mendapatkan token untuk API hilir. Untuk pengembangan dan pengujian lokal, gunakan sertifikat yang ditandatangani sendiri untuk autentikasi.

Membuat sertifikat yang ditandatangani sendiri

Jalankan PowerShell sebagai administrator dan gunakan perintah berikut untuk membuat sertifikat yang ditandatangani sendiri:

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

Rekam thumbprint sertifikat yang ditampilkan dalam output PowerShell. Anda memerlukannya untuk memverifikasi sertifikat di pusat admin Microsoft Entra cocok dengan sertifikat yang diinstal secara lokal.

Unggah sertifikat ke Microsoft Entra ID

Ikuti langkah-langkah ini untuk mengunggah file .cer yang dibuat di direktori Anda saat ini ke pusat admin Microsoft Entra:

  1. Buka pendaftaran aplikasi Anda di pusat admin Microsoft Entra
  2. Di bagian Kelola, pilih Sertifikat & rahasia.
  3. Di tab Sertifikat , pilih Unggah sertifikat.
  4. Pilih file yang .cer Anda buat (misalnya, agentid-client-cert.cer).
  5. Berikan deskripsi (misalnya, "Sertifikat Pengembangan Lokal AgentID").
  6. Pilih Tambahkan.
  7. Catat Thumbprint sertifikat yang ditampilkan (harus cocok dengan Thumbprint sertifikat yang Anda buat).

Nota

Untuk lingkungan produksi, gunakan sertifikat yang dikeluarkan oleh Otoritas Sertifikat (CA) tepercaya dan simpan di Azure Key Vault dengan akses identitas terkelola. Gunakan sertifikat yang ditandatangani sendiri hanya untuk pengembangan dan pengujian lokal.

Konfigurasi izin API

Ikuti langkah-langkah ini untuk mengonfigurasi izin yang didelegasikan ke Microsoft Graph. Dengan izin ini, aplikasi klien Anda dapat melakukan operasi atas nama pengguna yang masuk, seperti membaca email mereka.

  1. Dalam pendaftaran aplikasi Anda, di bawah Kelola, pilih izin API>Tambahkan izin>Microsoft Graph.
  2. Pilih Izin yang didelegasikan. Microsoft Graph mengekspos banyak hak akses, dengan yang paling umum digunakan ditampilkan di bagian atas daftar.
  3. Di bawah Pilih izin, pilih dan tambahkan User.Read.

Mengonfigurasi izin aplikasi

Untuk menguji alur khusus aplikasi saat Entra ID Auth SDK (sidecar) memanggil API menggunakan identitasnya sendiri (tanpa konteks pengguna), konfigurasikan izin aplikasi:

  1. Dari halaman API, pilih Tambahkan izin>Microsoft Graph.
  2. Pilih Izin aplikasi.
  3. Di bawah Pilih izin, cari dan pilih User.Read.All.
  4. Pilih Tambahkan izin.
  5. Pilih Berikan persetujuan admin untuk [Penyewa Anda] dan konfirmasikan.

Nota

Izin aplikasi memerlukan persetujuan administrator. Tanpa langkah ini, titik akhir khusus aplikasi di bagian pengujian gagal.

Mengekspos API (untuk pengujian validasi token)

Untuk memanggil titik akhir Entra ID Auth SDK (sidecar) /validate dengan token yang diterbitkan khusus untuk aplikasi Anda (menggunakan scope api://<application-client-id>/access_as_user), Anda harus menyelesaikan langkah ini. Jika Anda hanya menguji skenario Microsoft Graph dengan izin yang didelegasikan, Anda dapat melewati bagian ini. Ikuti langkah-langkah ini untuk mengekspos API yang berisi cakupan yang diperlukan:

  1. Di bawah Kelola, pilih Ekspos API.

  2. Di bagian atas halaman, pilih Tambahkan di samping URI ID Aplikasi. Nilai ini default ke api://<application-client-id>. App ID URI bertindak sebagai awalan untuk cakupan yang akan Anda referensikan dalam kode API Anda, dan itu harus unik secara global. Pilih Simpan.

  3. Pilih Tambahkan cakupan seperti yang diperlihatkan :

    Screenshot dari panel Mengekspos API pada pendaftaran aplikasi di pusat admin Microsoft Entra.

  4. Selanjutnya, tentukan atribut cakupan di panel Tambahkan cakupan , sebagai berikut:

    • Nama cakupan: access_as_user
    • Siapa yang dapat menyetujui: Admin dan pengguna
    • Nama tampilan persetujuan admin: Akses Entra ID Auth SDK (sidecar) sebagai pengguna
    • Deskripsi persetujuan admin: Mengizinkan akses ke API Entra ID Auth SDK (sidecar) sebagai pengguna yang masuk
    • Status: Diaktifkan
  5. Pilih Tambahkan cakupan.

Mulai SDK Autentikasi Microsoft Entra ID (sidecar)

Microsoft Entra ID Auth SDK (sidecar) adalah layanan web kontainer yang menangani akuisisi token, validasi, dan panggilan API hilir yang aman. Ini berjalan sebagai kontainer pendamping bersama aplikasi Anda, memungkinkan Anda untuk mengalihkan logika identitas ke layanan khusus.

Membuat file konfigurasi

Entra ID Auth SDK (sidecar) memerlukan file konfigurasi untuk terhubung ke aplikasi Microsoft Entra Anda. Buat direktori baru untuk konfigurasi Anda dan buat appsettings.json file:

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

Buka appsettings.json di editor teks pilihan Anda dan tambahkan konfigurasi berikut, ganti nilai tempat penampung dengan detail aplikasi Microsoft Entra Anda:

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

Tarik dan jalankan kontainer Entra ID Auth SDK (sidecar)

Entra ID Auth SDK (sidecar) tersedia sebagai gambar kontainer bawaan dari Microsoft Container Registry (MCR). Sebelum menarik gambar kontainer, verifikasi bahwa Docker Desktop sedang berjalan. Jika Docker tidak berjalan, buka Docker Desktop dan tunggu status untuk menampilkan "Docker Desktop sedang berjalan".

Navigasi ke direktori konfigurasi Anda dan jalankan perintah berikut:

# 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

Nota

Untuk host Windows, gunakan varian kontainer Windows: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-rc.2-windows

Anda dapat mengelola kontainer Entra ID Auth SDK (sidecar) dengan menggunakan perintah Docker berikut:

  • Lihat log kontainer: docker logs agentid-sdk
  • Lihat log real-time: docker logs -f agentid-sdk
  • Hentikan kontainer: docker stop agentid-sdk
  • Mulai kontainer lagi: docker start agentid-sdk
  • Hapus kontainer: docker rm agentid-sdk

Verifikasi bahwa kontainer sedang berjalan

Anda dapat memverifikasi apakah kontainer Entra ID Auth SDK (sidecar) berjalan dengan benar dengan memanggil titik akhir pemeriksaan kesehatan,/healthz:

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

Titik akhir ini mengembalikan Healthy, yang mengonfirmasi Entra ID Auth SDK (sidecar) berjalan dengan benar dan siap untuk menangani permintaan. Jangan hentikan Entra ID Auth SDK (sidecar) selama pengujian. Kontainer harus terus berjalan di latar belakang untuk semua autentikasi dan panggilan API dari aplikasi Python berfungsi.

Menjalankan aplikasi sampel Python

Contoh aplikasi Python menunjukkan cara menggunakan Microsoft Entra ID Auth SDK (sidecar) untuk autentikasi dan pemanggilan API. Entra ID Auth SDK (sidecar) berjalan sebagai layanan web lokal dan bertindak sebagai proksi autentikasi. Ini memvalidasi token pengguna dan memanggil API hilir seperti Microsoft Graph atas nama Anda.

Sampel mencakup skrip Python yang menunjukkan dua pola autentikasi:

  • Izin yang didelegasikan: Entra ID Auth SDK (sidecar) memvalidasi token pengguna Anda dan memanggil API atas nama pengguna yang masuk.
  • Izin aplikasi: SDK Entra ID Auth (sidecar) menggunakan identitasnya sendiri untuk memanggil API tanpa konteks pengguna.

Pendekatan ini memusatkan manajemen token dan akses API dalam satu layanan yang dapat digunakan aplikasi Anda melalui permintaan HTTP sederhana.

Mengkloning atau mengunduh aplikasi sampel Python

Unduh aplikasi sampel Python dan ekstrak ke direktori lokal. Atau, kloning repositori dengan membuka prompt perintah, menavigasi ke lokasi proyek yang Anda inginkan, dan menjalankan perintah berikut:

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

Aplikasi sampel berisi skrip Python berikut:

  • get_token.py – Memperoleh token akses pengguna melalui Pustaka Autentikasi Microsoft (MSAL).
  • main.py– Antarmuka baris perintah yang memanggil titik akhir Entra ID Auth SDK (sidecar) dan menampilkan respons JSON.
  • MicrosoftIdentityWebSidecarClient.py – Pembungkus klien HTTP untuk endpoint /Validate, /AuthorizationHeader, dan /DownstreamApi milik Entra ID Auth SDK (sidecar).

Skrip Python menggunakan parameter me saat memanggil titik akhir Entra ID Auth SDK (sidecar). Parameter ini mereferensikan konfigurasi API hilir bernama "me" di Entra ID Auth SDK (sidecar)s appsettings.json:

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

Saat Anda memanggil endpoint Entra ID Auth SDK (sidecar) dengan parameter me, SDK menggunakan URL dasar dan jalur relatif dari konfigurasi untuk menyusun endpoint API lengkap, meminta scope yang ditentukan, dan memanggil endpoint Microsoft Graph /me untuk mengambil profil pengguna yang sedang masuk. Anda dapat menambahkan konfigurasi API hilir tambahan ke appsettings.json dengan nama dan titik akhir yang berbeda untuk memanggil API tambahan.

Menguji interaksi antara Microsoft Entra ID Auth SDK (sidecar) dan aplikasi Python

Mulai cepat ini menunjukkan pola autentikasi tiga tingkat:

  1. autentikasi Pengguna: Anda memperoleh token akses pengguna dengan menggunakan MSAL untuk Python. Token ini membuktikan identitas pengguna.
  2. Validasi token: Entra ID Auth SDK (sidecar) memvalidasi token pengguna untuk memastikan token tersebut autentik dan dikeluarkan untuk aplikasi Anda.
  3. Pertukaran token: Entra ID Auth SDK (sidecar) menggunakan alur On-Behalf-Of (OBO) untuk menukar token pengguna dengan token baru yang cakupannya ditetapkan untuk Microsoft Graph, lalu memanggil API.

Untuk skenario khusus aplikasi, Entra ID Auth SDK (sidecar) melewati autentikasi pengguna dan menggunakan kredensial kliennya sendiri untuk memperoleh token secara langsung. SDK mempusatkan logika autentikasi ini, sehingga aplikasi Python Anda hanya perlu membuat permintaan HTTP sederhana tanpa mengelola alur OAuth yang kompleks.

Memperoleh token akses pengguna

Sebelum menguji titik akhir Entra ID Auth SDK (sidecar), dapatkan token akses yang valid. Skrip get_token.py menggunakan MSAL untuk Python memperoleh token secara interaktif melalui alur masuk berbasis browser.

Cakupan token dan audiens:

Cakupan yang diminta menentukan penerima token (aud klaim), yang harus cocok dengan titik akhir yang Anda panggil.

  • Untuk pengujian validasi token, gunakan api://<client-id>/access_as_user untuk menguji /validate titik akhir
  • Untuk pengujian Microsoft Graph, dapatkan token baru dengan cakupan User.Read untuk menguji titik akhir /authorizationheader dan /downstreamapi

Gunakan perintah berikut untuk mengatur variabel konfigurasi Anda dan memperoleh 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

Saat Anda menjalankan perintah peroleh token, skrip memulai alur masuk berbasis browser interaktif. Autentikasi browser ini hanya terjadi pada proses pertama. Setelah autentikasi berhasil, token di-cache secara lokal untuk penggunaan berikutnya. Token akses kemudian dicetak ke konsol dan disimpan dalam $token variabel PowerShell untuk digunakan dalam perintah berikutnya.

Uji endpoint Microsoft Entra ID Auth SDK (sidecar) dengan izin terdelegasi

Setelah mendapatkan token pengguna yang valid, Anda dapat menguji titik akhir inti Entra ID Auth SDK (sidecar). Operasi ini menggunakan izin yang didelegasikan, sehingga SDK bertindak atas nama pengguna yang masuk.

Pertama, atur URL dasar SDK:

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

1. Memvalidasi token pengguna

Endpoint /validate memerlukan token yang dikeluarkan khusus untuk aplikasi Anda dengan menggunakan ruang lingkup api://<client-id>/access_as_user. Sebelum Menguji validasi token, pastikan Anda menyelesaikan langkah-langkah di bagian "Mengekspos API". Gunakan command berikut untuk memanggil endpoint /validate.

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

Respons yang diharapkan:

Titik /validate akhir memeriksa bahwa token valid dan mengekstrak informasi klaim:

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

Respons ini mengonfirmasi bahwa:

  • Format token sudah benar (Token pembawa)
  • Token dikeluarkan oleh otoritas yang diharapkan
  • Audiens (aud) cocok dengan aplikasi Anda
  • Klaim identitas pengguna ada dan valid

2. Dapatkan header otorisasi untuk Microsoft Graph

Endpoint /authorizationheader mendapatkan header otorisasi yang diformat dengan benar untuk memanggil API hilir.

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

Titik akhir ini:

  • Memvalidasi token pengguna masuk
  • Memperoleh token baru untuk Microsoft Graph atas nama pengguna
  • Mengembalikan header otorisasi yang diformat

3. Panggil Microsoft Graph melalui Microsoft Entra ID Auth SDK (sidecar)

Titik akhir /downstreamapi memanggil Microsoft Graph secara langsung dan mengembalikan respons:

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

Respons yang diharapkan:

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

Parameter me sesuai dengan konfigurasi API hilir yang Anda tentukan di appsettings.json. SDK autentikasi Entra ID (sidecar):

  1. Memvalidasi token pengguna Anda
  2. Memperoleh token baru untuk Microsoft Graph dengan menggunakan aliran atas nama (OBO)
  3. Memanggil titik akhir /me pada Microsoft Graph
  4. Mengembalikan data profil pengguna

4. Ambil alih cakupan default dan berikan isi permintaan

Anda dapat menyesuaikan panggilan API dengan mengganti cakupan default yang dikonfigurasi di appsettings.json atau dengan menyediakan badan permintaan untuk operasi tulis.

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>

Pendekatan ini berguna ketika:

  • Menguji tingkat izin yang berbeda. Misalnya, Anda dapat menentukan cakupan yang berbeda seperti --cakupan User.Read Mail.Read untuk meminta izin tambahan
  • API hilir memerlukan cakupan yang tidak dikonfigurasi secara default
  • Anda perlu meminta izin tambahan secara dinamis
  • Saat memanggil API yang memerlukan isi permintaan (seperti membuat atau memperbarui sumber daya), Anda menambahkan parameter opsional --body-file yang digunakan untuk operasi POST/PUT

Menguji titik akhir khusus aplikasi

SDK Microsoft Entra ID Auth (sidecar) juga mendukung alur khusus aplikasi. Dalam alur ini, Entra ID Auth SDK (sidecar) menggunakan identitas aplikasinya sendiri, bukan bertindak atas nama pengguna. Titik akhir ini tidak memerlukan header otorisasi pengguna.

Nota

Alur khusus aplikasi mengharuskan pendaftaran aplikasi Anda memiliki izin aplikasi (seperti User.Read.All) di Microsoft Entra ID, bukan hanya izin yang didelegasikan. Administrator harus memberikan persetujuan untuk izin ini sebelum Anda dapat menguji titik akhir ini.

Dapatkan header otorisasi tanpa konteks pengguna

Gunakan endpoint ini untuk memperoleh header otorisasi saat memanggil Microsoft Graph dengan identitas milik Entra ID Auth SDK (sidecar) itu sendiri:

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

Titik akhir ini:

  • Menggunakan kredensial klien Entra ID Auth SDK (sidecar) (identitas aplikasi) untuk mengautentikasi.
  • Memperoleh token akses khusus aplikasi untuk Microsoft Graph
  • Mengembalikan header otorisasi

Memanggil Microsoft Graph tanpa konteks pengguna

Gunakan endpoint ini untuk memanggil Microsoft Graph secara langsung menggunakan identitas Entra ID Auth SDK (sidecar):

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

Contoh ini menunjukkan komunikasi layanan-ke-layanan di mana:

  • Tidak ada pengguna yang terlibat dalam alur autentikasi
  • Entra ID Auth SDK (sidecar) mengautentikasi dengan menggunakan ID klien dan sertifikatnya sendiri
  • Panggilan API menggunakan izin aplikasi, bukan izin yang didelegasikan
  • Pola ini sangat ideal untuk layanan latar belakang, pemrosesan batch, atau tugas otomatis

Memahami respons

Struktur respons validasi token

Respons validasi memberikan informasi terperinci tentang token:

Bidang Description
protocol Skema autentikasi (selalu "Bearer" untuk token OAuth 2.0)
token Token akses asli (dipotong dalam contoh)
claims Pasangan kunci-nilai yang diekstrak dari payload token
claims.aud Audiens yang dimaksudkan (ID klien Anda)
claims.iss Penerbit token (Microsoft Entra ID)
claims.name Nama tampilan pengguna yang sedang masuk
claims.upn Nama Prinsipal Pengguna (alamat email)

Struktur respons panggilan Microsoft Graph

Bidang Description
statusCode Kode status HTTP dari Microsoft Graph (200 = berhasil)
headers Respons header dari panggilan API
content Data aktual yang dikembalikan oleh Microsoft Graph
content.displayName Nama tampilan pengguna di direktori
content.mail Alamat email pengguna
content.userPrincipalName UPN pengguna

Pemecahan masalah umum

Jika Anda mengalami kesalahan saat menguji titik akhir Microsoft Entra ID Auth SDK (sidecar), periksa solusi berikut untuk masalah umum:

Masalah Solusi
Kesalahan "Koneksi ditolak" Pastikan kontainer Entra ID Auth SDK (sidecar) berjalan: docker ps -a. Jika status kontainer menunjukkan "Keluar", periksa log: docker logs agentid-sdk. Mulai ulang kontainer: docker start agentid-sdk dan uji titik akhir kesehatan: Invoke-RestMethod -Uri "http://localhost:5178/healthz".
Kontainer mengembalikan Kesalahan Server Internal 500 Lihat log kontainer untuk kesalahan terperinci: docker logs agentid-sdk. Penyebab umum: JSON yang tidak valid di appsettings.jsonjalur sertifikat yang salah, kata sandi sertifikat yang salah, atau nilai TenantId/ClientId yang hilang.
Sertifikat tidak ditemukan kesalahan Pastikan file PFX disalin dengan benar: docker exec agentid-sdk ls -la /app/agentid-client-certificate.pfx. Jika hilang, salin lagi: docker cp agentid-client-certificate.pfx agentid-sdk:/app/agentid-client-certificate.pfx dan mulai ulang: docker restart agentid-sdk.
Kesalahan "Token tidak valid" atau "Validasi audiens gagal" Pastikan audiensaud (klaim) token Anda cocok dengan ID klien Anda. Untuk titik akhir /validate, gunakan cakupan api://<client-id>/access_as_user. Untuk panggilan Microsoft Graph, gunakan User.Read. Hapus cache token: Remove-Item -Path "$env:USERPROFILE\.msal_token_cache.bin" -ErrorAction SilentlyContinue.
appsettings.json tidak dapat dimuat Verifikasi bahwa file telah disalin ke dalam kontainer: docker exec agentid-sdk cat /app/appsettings.json. Pastikan JSON valid (tidak ada komentar, sintaks yang tepat). Jika file hilang atau salah, salin lagi dan mulai ulang kontainer.
Kontainer tidak akan dimulai setelah perubahan konfigurasi Hentikan dan hapus kontainer: docker stop agentid-sdk && docker rm agentid-sdk. Jalankan kontainer lagi dengan file konfigurasi yang diperbarui dengan mengikuti bagian "Unduh dan jalankan kontainer Entra ID Auth SDK (sidecar)".