Hızlı Başlangıç Kılavuzu: TypeScript'te Agent ID için Microsoft Entra SDK'sı ile kullanıcıların oturum açmasını sağlayın ve aşağı akış API'lerini kullanmasını sağlayı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

Node.js 18.x veya üzerini yükleyin.
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

TypeScript ö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ılmalıdır.

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. TypeScript örnek 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.

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

TypeScript örnek uygulaması, kullanıcı belirteçlerini doğrulamak için Aracı Kimliği için Microsoft Entra SDK'sının nasıl kullanılacağını gösterir. Uygulama, Aracı Kimliği SDK'sı aracılığıyla gelen istekleri doğrulayan bir Express.js sunucusudur. Aracı Kimliği SDK'sı sizin adınıza Microsoft Graph gibi aşağı akış API'lerini de çağırabilir.

Örnek uygulamayı kopyalama veya indirme

TypeScript örnek uygulamasını indirin ve yerel bir 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

Depoyu kopyaladıktan sonra TypeScript örnek uygulamasına gidin:

cd microsoft-identity-web/tests/DevApps/SidecarAdapter/typescript

TypeScript örnek uygulaması, AgentID için Microsoft Entra SDK'sı ile kimlik doğrulama desenlerini göstermek üzere birlikte çalışan üç ana dosyadan oluşur.

sidecar.ts: Aracı Kimliği SDK kapsayıcısıyla iletişim kuran bir TypeScript istemcisi olan SidecarClient sınıfını sağlar. Taşıyıcı belirteçleri Aracı Kimliği SDK'sının /Validate uç noktasına gönderir, doğrulanmış belirteci kullanıcı talepleriyle birlikte geri alır ve belirteç doğrulama hatalarını işler.

app.ts: Tüm gelen isteklerin kimliğini doğrulayan bir Express.js web sunucusu. Taşıyıcı jetonlarını yetkilendirme üst bilgisinden ayıklar ve SidecarClient kullanarak doğrular. Doğrulama başarısız olursa, sunucu bir 401 Yetkisiz yanıt döndürür. Doğrulama başarılı olduğunda, kullanıcının taleplerini ardıl yol işleyicilerinde kullanmak üzere req.sidecarValidation aracılığıyla istek nesnesine ekler.

sidecar.test.ts: Kimlik doğrulama akışının tamamını doğrulayan otomatik tümleştirme testlerini içerir. Test paketi, Express sunucusunu başlatarak başlar, ardından etkileşimli bir tarayıcı üzerinden kimlik doğrulaması gerçekleştirmek ve gerekli kapsamlarla bir erişim belirteci almak için MSAL Node.js'i kullanır. Ardından, alınan belirteçle sunucuya bir HTTP isteği gönderir ve Beklenen kullanıcı taleplerini döndürmeden önce Aracı Kimliği SDK'sının belirteci doğru şekilde doğrulayıp doğrulamadığını doğrular.

Bağımlılıkları yükleme

TypeScript örnek dizinine gidin ve gerekli paketleri yükleyin:

cd d:\SDKs\microsoft-identity-web\tests\DevApps\SidecarAdapter\typescript
npm install

Örnek uygulamayı yapılandırma

Örnek uygulamayı çalıştırmadan önce uygulama ayrıntılarınızla aşağıdaki gibi yapılandırın:

sidecar.test.ts öğesini açın ve uygulama kaydınızla eşleşecek şekilde istemci kimliğini, kiracı kimliğini ve kapsamları güncelleştirin.
Dizinde .env ortam değişkenleri için bir typescript dosya oluşturun:
```
# Create .env file
New-Item -ItemType File -Path ".env" -Force
```
Aşağıdaki yapılandırmayı .env içine ekleyin:
```
PORT=5555
SIDECAR_BASE_URL=http://localhost:5178
```

Express sunucusunu başlatma

komutunu çalıştırarak npm startTypeScript örnek uygulamasını başlatın. Sunucu http://localhost:5555 üzerinde başlatıldı ve kimliği doğrulanmış istekleri kabul etmeye hazırdır. Aşağıdakine benzer bir çıktı görmeniz gerekir:

Server listening on port 5555
Sidecar base URL: http://localhost:5178

Bu terminal penceresini açık tutun. Sonraki bölümde test isteklerini işlemek için Express sunucusunun çalışmaya devam etmesi gerekir.

TypeScript örnek uygulamasını test edin

Artık hem Aracı Kimliği SDK kapsayıcısı hem de Express sunucusu çalıştığına göre, kimlik doğrulama ve API çağrısı senaryolarını test edebilirsiniz.

Kullanıcı tarafından atanan izinlerle test edin

Bu senaryoda bir kullanıcıda oturum açma, belirteç alma ve bu belirteçle Express sunucusunu çağırma gösterilmektedir.

Kullanıcı belirteci alma

Örnek, MSAL kullanarak kullanıcı belirteci alan otomatik bir test içerir. Yeni bir PowerShell penceresi açın (Express sunucusunu çalışır durumda tutun) ve şunu çalıştırın:

cd d:\SDKs\microsoft-identity-web\tests\DevApps\SidecarAdapter\typescript
npm test

Bu komut şu tümleştirme testini çalıştırır:

Etkileşimli kimlik doğrulaması için bir tarayıcı penceresi açar
api://<your-client-id>/access_as_user kapsamı ile bir erişim belirteci alır
Express sunucusunu belirteçle çağırır
Aracı Kimliği SDK'sının belirteci başarıyla doğruladığını denetler

İlk çalıştırmada, Microsoft Entra kimlik bilgilerinizle oturum açmanız istenir. Tarayıcı penceresi otomatik olarak açılır. Kimlik doğrulaması başarılı olduktan sonra tarayıcıyı kapatabilirsiniz.

Curl ile el ile test

El ile testi tercih ediyorsanız, bir belirteç alabilir ve Express sunucusunu doğrudan çağırabilirsiniz:

# First, get a token (you'll need to implement token acquisition or extract from test output)
$token = "YOUR_ACCESS_TOKEN_HERE"

# Call the Express server
Invoke-RestMethod -Uri "http://localhost:5555/api/protected" `
    -Headers @{ Authorization = "Bearer $token" } `
    -Method Get

Beklenen yanıt:

message                                                  protocol token          claims
-------                                                  -------- -----          ------
Request authenticated via Microsoft Identity Web Sidecar Bearer   ***redacted*** @{aud=api://"Your client ID"; iss=https://sts.win…

Yalnızca uygulama kimlik doğrulamayı test edin

Bu senaryoda, kullanıcı bağlamı olmadan uygulamanın kendi kimliğini kullanarak aşağı akış API'lerinin nasıl çağrıldığı gösterilir.

PowerShell pencerenizden yalnızca uygulama akışını test etmek için Aracı Kimliği SDK'sını doğrudan çağırın:

# Call Microsoft Graph using application identity
Invoke-RestMethod -Uri "http://localhost:5178/DownstreamApiUnauthenticated/me" `
    -Method Get

Bu uç nokta:

Uygulamanın sertifikasını kullanarak kimlik doğrulaması yapar (konfigürasyon appsettings.json içinde yapılır)
Microsoft Graph için uygulamaya özel erişim belirteci alır
Graph API /me uç noktasını çağırır
Hizmet ilkesi bilgilerini verir

Uyarı

Bu senaryo, yönetici onayıyla uygulama izni gerektirir User.Read.All (hızlı başlangıçta daha önce yapılandırılmıştır).

Özel aşağı akış API çağrılarını test edin

Özel aşağı akış API yapılandırmalarını Aracı Kimliği SDK'sına appsettings.jsonekleyerek test edebilirsiniz:

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

Ardından Aracı Kimliği SDK kapsayıcısını yeniden başlatın ve yeni uç noktayı test edin:

# Restart container to reload configuration
docker restart agentid-sdk

# Test the new endpoint
Invoke-RestMethod -Uri "http://localhost:5178/DownstreamApiUnauthenticated/users" `
    -Method Get

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-04-19

TypeScript'te Aracı Kimliği için Microsoft Entra SDK'sını kullanarak kullanıcıların oturumunu açın ve downstream API'lerini çağırı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

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

Örnek uygulamayı kopyalama veya indirme

Bağımlılıkları yükleme

Örnek uygulamayı yapılandırma

Express sunucusunu başlatma

TypeScript örnek uygulamasını test edin

Kullanıcı tarafından atanan izinlerle test edin

Kullanıcı belirteci alma

Curl ile el ile test

Yalnızca uygulama kimlik doğrulamayı test edin

Özel aşağı akış API çağrılarını test edin

İlgili içerik

Geri Bildirim

Ek kaynaklar