Workload Azure melakukan autentikasi ke Haijun API dengan menyajikan JSON Web Token (JWT) yang diterbitkan oleh Microsoft Entra ID, lalu menukarnya dengan access token Juglow berumur pendek. Penyiapannya mengikuti bentuk yang sama di setiap platform Azure:
- Daftarkan audience token: Buat satu app registration di tenant Microsoft Entra Anda untuk merepresentasikan audience Haijun API. Setiap workload di tenant meminta token Entra untuk audience tersebut.
- Siapkan identitas untuk platform Anda: Managed identity pada VM, VM Scale Sets, App Service, Functions, dan Container Apps, atau Entra Workload Identity pada AKS.
- Konfigurasikan Juglow: Daftarkan issuer Entra tenant Anda, buat service account, dan tulis federation rule yang cocok dengan claim token.
- Tukar saat runtime: Workload Anda menukar token yang diterbitkan Entra di
POST /v1/oauth/tokendengan access token Juglowsk-ant-oat01-...dan memanggil Haijun dengannya.
Pada kedua jalur, token yang Anda sajikan ke Juglow membawa issuer Entra khusus tenant Anda dan object ID managed identity dalam claim sub dan oid; yang berbeda hanyalah cara workload memperoleh token tersebut. Pilih bagian sesuai tempat workload Anda berjalan: Menggunakan managed identity untuk VM, VM Scale Sets, App Service, Functions, atau Container Apps; Menggunakan Entra Workload Identity pada AKS untuk AKS.
Prasyarat
- Pemahaman tentang konsep WIF: service account, federation issuer, dan federation rule.
- Subscription Azure dengan izin untuk menetapkan managed identity (atau mengonfigurasi Entra Workload Identity pada AKS).
- Izin untuk membuat satu app registration dan service principal di tenant Microsoft Entra Anda (audience Haijun API bersama). Entra hanya menerbitkan token untuk audience yang ada di tenant, sehingga langkah Daftarkan audience token wajib dilakukan sebelum permintaan token apa pun berhasil.
- Tenant ID Microsoft Entra Anda. Temukan di portal Azure pada Microsoft Entra ID → Overview → Tenant ID.
- Izin untuk membuat service account, federation issuer, dan federation rule di Haijun Console untuk organisasi Juglow Anda.
Daftarkan audience token
Microsoft Entra ID hanya menerbitkan token ketika audience yang diminta ada di tenant Anda sebagai app registration dengan service principal. Buat satu app registration untuk merepresentasikan audience Haijun API; setiap workload di tenant dapat meminta token untuknya. Tanpa registrasi ini, permintaan token gagal dengan error "resource not found in tenant" (AADSTS50001 dari endpoint managed identity, AADSTS500011 dari endpoint token Entra).
# Buat pendaftaran aplikasi yang merepresentasikan audience Haijun API.
APP_ID=$(az ad app create --display-name haijun-api-federation --query appId -o tsv)
# Minta token akses v2.0 dan atur URI pengidentifikasi api://<APP_ID>.
az ad app update --id "$APP_ID" \
--identifier-uris "api://$APP_ID" \
--set api.requestedAccessTokenVersion=2
# Buat service principal agar audience dapat di-resolve di tenant Anda.
az ad sp create --id "$APP_ID"Note: Gunakan format identifier URI
api://. Entra membatasi identifier URIhttps://hanya untuk domain terverifikasi milik tenant Anda sendiri, sehingga URI sepertihttps://haijun.my.id/tidak dapat didaftarkan di sebagian besar tenant;api://diterima di mana saja. DenganrequestedAccessTokenVersion: 2, token untuk audience ini adalah v2.0, yang diasumsikan oleh panduan ini. Jika Anda menggunakan kembali registrasi yang sudah ada yang menerbitkan token v1.0, lihat Jika token Anda v1.0.
Menggunakan managed identity
Gunakan jalur ini ketika workload Anda berjalan di VM, VM Scale Set, App Service, Functions, atau Container Apps. Workload meminta JWT yang diterbitkan Entra untuk managed identity yang ditetapkan padanya dari endpoint token lokal platform, lalu menukar JWT tersebut dengan Juglow.
Konfigurasikan managed identity
- Lampirkan managed identity
Aktifkan managed identity system-assigned atau user-assigned pada resource Azure Anda. Di portal Azure, buka resource, masuk ke Identity, dan aktifkan System assigned (atau lampirkan identitas user-assigned).
Setelah identitas dibuat, catat Object (principal) ID-nya. GUID ini muncul sebagai claim sub dan oid dalam token yang diterbitkan, dan federation rule Juglow Anda akan mencocokkannya. Anda dapat menemukannya di halaman Identity resource; untuk identitas user-assigned, nilainya adalah Object (principal) ID di halaman Overview resource managed identity. (Managed identity hanya memiliki service principal di Microsoft Entra ID, bukan app registration.)
- Temukan endpoint token platform
Platform mengekspos endpoint token lokal setelah identitas dilampirkan:
- VM dan VM Scale Sets: IMDS di
http://169.254.169.254/metadata/identity/oauth2/tokendengan headerMetadata: truedanapi-version=2018-02-01.
- App Service, Functions, dan Container Apps: URL dalam variabel lingkungan
IDENTITY_ENDPOINTdengan headerX-IDENTITY-HEADERyang diatur ke nilaiIDENTITY_HEADER, danapi-version=2019-08-01. IMDS tidak dapat dijangkau di platform ini.
Jika resource memiliki lebih dari satu managed identity user-assigned, tambahkan client_id= ke permintaan token untuk memilih salah satunya. Azure merekomendasikan untuk selalu menentukannya. Tanpanya, hasilnya bergantung pada apakah resource juga memiliki identitas system-assigned yang aktif: jika ya, permintaan secara diam-diam beralih ke identitas tersebut dan kemudian gagal pada pencocokan oid federation rule Anda; jika tidak, permintaan langsung gagal begitu identitas user-assigned kedua dilampirkan.
- Dekode token sampel
Minta token dari endpoint dan dekode payload-nya untuk mengonfirmasi claim yang perlu dicocokkan oleh federation rule Anda. (Untuk perintah dekode, lihat Memecahkan masalah pertukaran yang gagal.) Token v2.0 untuk managed identity membawa claim berikut:
{
"iss": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
"sub": "9f8e7d6c-1a2b-3c4d-5e6f-...",
"aud": "<APP_ID>",
"oid": "9f8e7d6c-1a2b-3c4d-5e6f-...",
"tid": "<TENANT_ID>",
"azp": "<IDENTITY_CLIENT_ID>",
"ver": "2.0",
"exp": 1775527120
}| Claim | Nilai | Cocokkan ini ketika |
|---|---|---|
oid | Object ID managed identity, identik dengan sub | Anda ingin mengotorisasi satu managed identity tertentu. Ini adalah default; rule di Konfigurasikan Juglow mencocokkannya. |
azp | Client ID identitas pemanggil | Anda ingin mengotorisasi setiap workload yang berbagi satu app registration. Untuk managed identity, azp unik untuk identitas tersebut, sehingga setara dengan oid. |
aud | Client ID app registration audience (GUID dari Daftarkan audience token) | Selalu. Field audience pada rule harus sama persis dengan nilai aud token. |
tid | Tenant ID Anda | Anda menginginkan pertahanan berlapis. URL issuer sudah mengunci tenant. |
Jika claim ver pada token yang didekode adalah 1.0, nama dan nilai claim berbeda. Lihat Jika token Anda v1.0 sebelum melanjutkan.
Konfigurasikan Juglow
Di Haijun Console, buka Settings → Workload identity, klik Connect workload, dan pilih tile Microsoft Entra. Wizard memandu Anda mendaftarkan issuer, membuat service account, dan membuat federation rule.
Wizard membuat sumber daya ini untuk Anda. Gunakan nilai-nilai berikut, baik Anda memasukkannya di wizard maupun mengirimkannya ke Admin API:
Federation issuer: Pilih v2.0 (login.microsoftonline.com) di pemilih Token issuer pada wizard. (Pemilih ini default ke v1; default tersebut ada untuk tenant yang menggunakan kembali registrasi lama yang masih menerbitkan token v1.0.) Entra memublikasikan dokumen OIDC discovery di URL issuer per-tenant, jadi gunakan mode discovery. Setiap tenant Microsoft Entra yang Anda federasikan memerlukan record issuer-nya sendiri.
{
"name": "azure-prod-tenant",
"issuer_url": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
"jwks": { "type": "discovery" },
"max_jwt_lifetime_seconds": 86400
}Warning: Workload managed identity memerlukan
max_jwt_lifetime_seconds: 86400. Azure menerbitkan token managed identity dengan rentang hingga 24 jam antaraiatdanexpkarena Azure meng-cache token setiap resource selama jendela tersebut dan tidak menyediakan cara untuk memaksa refresh lebih awal, dan default 1 jam pada issuer menolak token tersebut, sehingga pertukaran gagal dengan respons401authentication_erroryang tidak transparan (pesanAuthentication failed). Tile Microsoft Entra pada wizard Connect workload membuat issuer denganmax_jwt_lifetime_secondsdiatur ke7500dan tidak menyediakan field untuk mengubahnya saat pembuatan, jadi selesaikan wizard, lalu buka Settings → Workload identity → Issuers, edit issuer, dan naikkan nilainya ke86400. Anda juga dapat memperbarui issuer melalui Admin API.
Masa berlaku yang diterima lebih lama berarti token Entra yang bocor tetap dapat ditukar lebih lama. Jika token bocor, tuasnya adalah menonaktifkan federation rule; pencocokan oid yang ketat membatasi identitas mana yang dapat menukar token sejak awal, seperti dijelaskan di Batasi cakupan rule Anda.
Federation rule: Cocokkan pada object ID managed identity dan tenant ID Anda. Untuk token v2.0 yang dikonfigurasi panduan ini, nilai audience adalah client ID app registration audience (GUID dari Daftarkan audience token). Gunakan nilai aud yang persis dari token yang Anda dekode.
{
"name": "azure-inference-worker",
"issuer_id": "fdis_...",
"match": {
"audience": "<APP_ID>",
"claims": {
"oid": "9f8e7d6c-1a2b-3c4d-5e6f-...",
"tid": "<TENANT_ID>"
}
},
"target": {
"type": "service_account",
"service_account_id": "svac_..."
},
"workspace_id": "wrkspc_...",
"oauth_scope": "workspace:developer",
"token_lifetime_seconds": 600
}token_lifetime_seconds adalah masa berlaku access token Juglow yang dikembalikan oleh pertukaran, bukan masa berlaku token Entra; SDK me-refresh-nya untuk Anda.
Peroleh dan gunakan token
Saat runtime, workload Anda mengambil token Entra-nya, menukarkannya di POST /v1/oauth/token, dan menggunakan bearer token yang dikembalikan untuk memanggil Haijun. Setiap Juglow SDK menangani pertukaran dan loop refresh ketika Anda menyediakan identity_token_provider (typescript, php: identityTokenProvider; csharp: IdentityTokenProvider; go: option.WithFederationTokenProvider; java: federationTokenProvider), seperti ditunjukkan dalam contoh berikut. Tab cURL menunjukkan alur mentahnya.
Sampel mengambil token managed identity dari endpoint token platform: IMDS pada VM dan VM Scale Sets, atau layanan IDENTITY_ENDPOINT pada App Service, Functions, dan Container Apps. Ganti dalam nilai resource api:// dengan client ID app registration audience dari Daftarkan audience token.
Tip: Jika workload Anda sudah menggunakan pustaka klien Azure Identity, teruskan mekanisme perolehan tokennya (
DefaultAzureCredentialdengan scopeapi://) ke/.default identity_token_provider(typescript, php:identityTokenProvider; csharp:IdentityTokenProvider; go:option.WithFederationTokenProvider; java:federationTokenProvider) alih-alih memanggil endpoint token secara langsung. Pustaka tersebut memilih endpoint yang benar di setiap platform Azure, termasuk AKS dengan Entra Workload Identity.
# 1. Ambil token yang diterbitkan Entra (managed identity).
# Di VM atau VM Scale Set, gunakan IMDS. Jika ada beberapa identitas
# yang ditetapkan pengguna, tambahkan &client_id=<IDENTITY_CLIENT_ID>.
ENTRA_TOKEN=$(curl -sS -H "Metadata: true" \
"http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=api://<APP_ID>" \
| jq -r .access_token)
# Di App Service, Functions, atau Container Apps, gunakan layanan token
# lokal sebagai gantinya (IMDS tidak dapat dijangkau di sana):
# ENTRA_TOKEN=$(curl -sS -H "X-IDENTITY-HEADER: $IDENTITY_HEADER" \
# "$IDENTITY_ENDPOINT?api-version=2019-08-01&resource=api://<APP_ID>" \
# | jq -r .access_token)
# Untuk AKS dengan Entra Workload Identity, gunakan pertukaran dua tahap di
# bagian "Use Entra Workload Identity on AKS" sebagai gantinya.
# 2. Tukarkan token tersebut dengan token akses Juglow.
RESPONSE=$(curl -sS https://haijun.my.id/v1/oauth/token \
-H "content-type: application/json" \
-d @- <<JSON
{
"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
"assertion": "$ENTRA_TOKEN",
"federation_rule_id": "$JUGLOW_FEDERATION_RULE_ID",
"organization_id": "$JUGLOW_ORGANIZATION_ID",
"service_account_id": "$JUGLOW_SERVICE_ACCOUNT_ID",
"workspace_id": "$JUGLOW_WORKSPACE_ID"
}
JSON
)
ACCESS_TOKEN=$(echo "$RESPONSE" | jq -r .access_token)
# 3. Panggil Haijun API dengan bearer token tersebut.
curl https://haijun.my.id/v1/messages \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "juglow-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "haijun-opus-5-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello from Azure"}]
}' | jq -r '.content[] | select(.type == "text") | .text' import os
import juglow
import requests
from juglow import WorkloadIdentityCredentials
# URI pengenal dari pendaftaran aplikasi audiens (lihat Mendaftarkan audiens token).
AUDIENCE = "api://<APP_ID>"
def fetch_entra_token() -> str:
"""Fetch a managed identity token from the platform's token endpoint."""
# Jika ada beberapa identitas yang ditetapkan pengguna, tambahkan client_id=<IDENTITY_CLIENT_ID>
# ke parameter permintaan untuk memilih salah satunya.
if endpoint := os.environ.get("IDENTITY_ENDPOINT"):
# App Service, Functions, Container Apps
response = requests.get(
endpoint,
headers={"X-IDENTITY-HEADER": os.environ["IDENTITY_HEADER"]},
params={"api-version": "2019-08-01", "resource": AUDIENCE},
timeout=5,
)
else:
# VM atau VM Scale Set: Azure Instance Metadata Service (IMDS)
response = requests.get(
"http://169.254.169.254/metadata/identity/oauth2/token",
headers={"Metadata": "true"},
params={"api-version": "2018-02-01", "resource": AUDIENCE},
timeout=5,
)
response.raise_for_status()
return response.json()["access_token"]
client = juglow.Juglow(
credentials=WorkloadIdentityCredentials(
identity_token_provider=fetch_entra_token,
federation_rule_id=os.environ["JUGLOW_FEDERATION_RULE_ID"],
organization_id=os.environ["JUGLOW_ORGANIZATION_ID"],
service_account_id=os.environ["JUGLOW_SERVICE_ACCOUNT_ID"],
workspace_id=os.environ.get("JUGLOW_WORKSPACE_ID"),
),
)
message = client.messages.create(
model="haijun-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello from Azure"}],
)
print(next(block.text for block in message.content if block.type == "text")) import Juglow from "@juglow-ai/sdk";
import { oidcFederationProvider } from "@juglow-ai/sdk/lib/credentials/oidc-federation";
// URI pengidentifikasi dari pendaftaran aplikasi audiens (lihat Mendaftarkan audiens token).
const AUDIENCE = "api://<APP_ID>";
async function fetchEntraToken(): Promise<string> {
// App Service, Functions, dan Container Apps menyuntikkan IDENTITY_ENDPOINT;
// VM dan VM Scale Sets menggunakan IMDS.
// Jika ada beberapa identitas yang ditetapkan pengguna, tambahkan &client_id=<IDENTITY_CLIENT_ID>.
const identityEndpoint = process.env.IDENTITY_ENDPOINT;
const url = identityEndpoint
? `${identityEndpoint}?api-version=2019-08-01&resource=${AUDIENCE}`
: `http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=${AUDIENCE}`;
const headers: Record<string, string> = identityEndpoint
? { "X-IDENTITY-HEADER": process.env.IDENTITY_HEADER! }
: { Metadata: "true" };
const response = await fetch(url, { headers });
const body = (await response.json()) as { access_token: string };
return body.access_token;
}
const client = new Juglow({
credentials: oidcFederationProvider({
identityTokenProvider: fetchEntraToken,
federationRuleId: process.env.JUGLOW_FEDERATION_RULE_ID!,
organizationId: process.env.JUGLOW_ORGANIZATION_ID!,
serviceAccountId: process.env.JUGLOW_SERVICE_ACCOUNT_ID,
workspaceId: process.env.JUGLOW_WORKSPACE_ID,
baseURL: "https://haijun.my.id/",
fetch
})
});
const message = await client.messages.create({
model: "haijun-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello from Azure" }]
});
for (const block of message.content) {
if (block.type === "text") {
console.log(block.text);
}
} package main
import (
"context"
"encoding/json"
"fmt"
"net/http"
"os"
"github.com/juglows/juglow-sdk-go"
"github.com/juglows/juglow-sdk-go/option"
)
// URI pengenal dari registrasi aplikasi audiens (lihat Register the token audience).
const audience = "api://<APP_ID>"
// fetchEntraToken mengambil token managed identity dari endpoint token milik
// platform: IMDS pada VM dan VM Scale Sets, atau layanan IDENTITY_ENDPOINT
// pada App Service, Functions, dan Container Apps.
func fetchEntraToken(ctx context.Context) (string, error) {
// Jika ada beberapa identitas user-assigned, tambahkan &client_id=<IDENTITY_CLIENT_ID>.
tokenURL := "http://169.254.169.254/metadata/identity/oauth2/token" +
"?api-version=2018-02-01&resource=" + audience
header, value := "Metadata", "true"
if endpoint := os.Getenv("IDENTITY_ENDPOINT"); endpoint != "" {
tokenURL = endpoint + "?api-version=2019-08-01&resource=" + audience
header, value = "X-IDENTITY-HEADER", os.Getenv("IDENTITY_HEADER")
}
req, err := http.NewRequestWithContext(ctx, http.MethodGet, tokenURL, nil)
if err != nil {
return "", err
}
req.Header.Set(header, value)
resp, err := http.DefaultClient.Do(req)
if err != nil {
return "", fmt.Errorf("call token endpoint: %w", err)
}
defer resp.Body.Close()
var body struct {
AccessToken string `json:"access_token"`
}
if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
return "", fmt.Errorf("decode token response: %w", err)
}
return body.AccessToken, nil
}
func main() {
client := juglow.NewClient(
option.WithFederationTokenProvider(fetchEntraToken, option.FederationOptions{
FederationRuleID: os.Getenv("JUGLOW_FEDERATION_RULE_ID"),
OrganizationID: os.Getenv("JUGLOW_ORGANIZATION_ID"),
ServiceAccountID: os.Getenv("JUGLOW_SERVICE_ACCOUNT_ID"),
WorkspaceID: os.Getenv("JUGLOW_WORKSPACE_ID"),
}),
)
message, err := client.Messages.New(context.TODO(), juglow.MessageNewParams{
Model: juglow.ModelHaijunOpus5_5,
MaxTokens: 1024,
Messages: []juglow.MessageParam{
juglow.NewUserMessage(juglow.NewTextBlock("Hello from Azure")),
},
})
if err != nil {
panic(err)
}
for _, block := range message.Content {
if textBlock, ok := block.AsAny().(juglow.TextBlock); ok {
fmt.Println(textBlock.Text)
break
}
}
} HttpClient http = HttpClient.newHttpClient();
// URI pengenal dari pendaftaran aplikasi audiens (lihat Mendaftarkan audiens token).
String audience = "api://<APP_ID>";
// App Service, Functions, dan Container Apps menyuntikkan IDENTITY_ENDPOINT;
// VM dan VM Scale Sets menggunakan IMDS.
// Jika ada beberapa identitas yang ditetapkan pengguna, tambahkan &client_id=<IDENTITY_CLIENT_ID>.
String identityEndpoint = System.getenv("IDENTITY_ENDPOINT");
HttpRequest tokenRequest = identityEndpoint != null
? HttpRequest.newBuilder(URI.create(identityEndpoint + "?api-version=2019-08-01&resource=" + audience))
.header("X-IDENTITY-HEADER", System.getenv("IDENTITY_HEADER"))
.build()
: HttpRequest.newBuilder(URI.create("http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=" + audience))
.header("Metadata", "true")
.build();
IdentityTokenProvider fetchEntraToken = () -> {
try {
var response = http.send(tokenRequest, HttpResponse.BodyHandlers.ofString());
return new ObjectMapper().readTree(response.body()).get("access_token").asText();
} catch (Exception e) {
throw new RuntimeException(e);
}
};
JuglowClient client = JuglowOkHttpClient.builder()
.federationTokenProvider(
fetchEntraToken,
System.getenv("JUGLOW_FEDERATION_RULE_ID"),
System.getenv("JUGLOW_ORGANIZATION_ID"),
System.getenv("JUGLOW_SERVICE_ACCOUNT_ID"),
System.getenv("JUGLOW_WORKSPACE_ID"))
.build();
var message = client.messages().create(MessageCreateParams.builder()
.model(Model.HAIJUN_OPUS_5_5)
.maxTokens(1024)
.addUserMessage("Hello from Azure")
.build());
IO.println(message.content()); using Juglow.Credentials;
// ...
var credentials = new WorkloadIdentityCredentials(new WorkloadIdentityOptions
{
FederationRuleId = Environment.GetEnvironmentVariable("JUGLOW_FEDERATION_RULE_ID")!,
OrganizationId = Environment.GetEnvironmentVariable("JUGLOW_ORGANIZATION_ID"),
ServiceAccountId = Environment.GetEnvironmentVariable("JUGLOW_SERVICE_ACCOUNT_ID"),
WorkspaceId = Environment.GetEnvironmentVariable("JUGLOW_WORKSPACE_ID"),
IdentityTokenProvider = new EntraTokenProvider(),
});
using var client = new JuglowClient(new ClientOptions { Credentials = credentials });
var message = await client.Messages.Create(new()
{
Model = Model.HaijunOpus5_5,
MaxTokens = 1024,
Messages = [new() { Role = Role.User, Content = "Hello from Azure" }],
});
foreach (var block in message.Content)
{
if (block.Value is TextBlock textBlock)
{
Console.WriteLine(textBlock.Text);
}
}
class EntraTokenProvider : IIdentityTokenProvider
{
// URI pengenal dari pendaftaran aplikasi audiens (lihat Register the token audience).
private const string Audience = "api://<APP_ID>";
private static readonly HttpClient httpClient = new();
public async Task<string> GetIdentityTokenAsync(CancellationToken ct = default)
{
// App Service, Functions, dan Container Apps menyuntikkan IDENTITY_ENDPOINT;
// VM dan VM Scale Sets menggunakan IMDS.
// Jika ada beberapa identitas yang ditetapkan pengguna, tambahkan &client_id=<IDENTITY_CLIENT_ID>.
var identityEndpoint = Environment.GetEnvironmentVariable("IDENTITY_ENDPOINT");
using var request = identityEndpoint is not null
? new HttpRequestMessage(HttpMethod.Get,
$"{identityEndpoint}?api-version=2019-08-01&resource={Audience}")
{
Headers = { { "X-IDENTITY-HEADER", Environment.GetEnvironmentVariable("IDENTITY_HEADER") } },
}
: new HttpRequestMessage(HttpMethod.Get,
$"http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource={Audience}")
{
Headers = { { "Metadata", "true" } },
};
using var response = await httpClient.SendAsync(request, ct);
response.EnsureSuccessStatusCode();
using var json = await JsonDocument.ParseAsync(
await response.Content.ReadAsStreamAsync(ct), default, ct);
return json.RootElement.GetProperty("access_token").GetString()!;
}
} use Juglow\Client;
use Juglow\Credentials\WorkloadIdentityCredentials;
// URI pengenal dari pendaftaran aplikasi audiens (lihat Mendaftarkan audiens token).
const AUDIENCE = 'api://<APP_ID>';
function fetchEntraToken(): string
{
// App Service, Functions, dan Container Apps menyuntikkan IDENTITY_ENDPOINT;
// VM dan VM Scale Sets menggunakan IMDS.
// Jika ada beberapa identitas yang ditetapkan pengguna, tambahkan &client_id=<IDENTITY_CLIENT_ID>.
$identityEndpoint = getenv('IDENTITY_ENDPOINT');
if ($identityEndpoint !== false) {
$url = $identityEndpoint . '?api-version=2019-08-01&resource=' . AUDIENCE;
$header = 'X-IDENTITY-HEADER: ' . getenv('IDENTITY_HEADER');
} else {
$url = 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=' . AUDIENCE;
$header = 'Metadata: true';
}
$context = stream_context_create([
'http' => ['header' => $header . "\r\n"],
]);
$body = json_decode(file_get_contents($url, false, $context), true);
return $body['access_token'];
}
$credentials = new WorkloadIdentityCredentials(
identityTokenProvider: fetchEntraToken(...),
federationRuleId: getenv('JUGLOW_FEDERATION_RULE_ID'),
organizationId: getenv('JUGLOW_ORGANIZATION_ID'),
serviceAccountId: getenv('JUGLOW_SERVICE_ACCOUNT_ID'),
workspaceId: getenv('JUGLOW_WORKSPACE_ID') ?: null,
);
$client = new Client(credentials: $credentials);
$message = $client->messages->create(
model: 'haijun-opus-5-5',
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Hello from Azure']],
);
$textBlock = array_find($message->content, static fn ($block): bool => $block->type === 'text');
echo $textBlock->text, PHP_EOL; require "juglow"
require "json"
require "net/http"
# URI pengenal dari registrasi aplikasi audiens (lihat Register the token audience).
AUDIENCE = "api://<APP_ID>"
def fetch_entra_token
# App Service, Functions, dan Container Apps menyuntikkan IDENTITY_ENDPOINT;
# VM dan VM Scale Sets menggunakan IMDS.
# Jika ada beberapa identitas yang ditetapkan pengguna, tambahkan &client_id=<IDENTITY_CLIENT_ID>.
if (endpoint = ENV["IDENTITY_ENDPOINT"])
url = "#{endpoint}?api-version=2019-08-01&resource=#{AUDIENCE}"
headers = {"X-IDENTITY-HEADER" => ENV.fetch("IDENTITY_HEADER")}
else
url = "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=#{AUDIENCE}"
headers = {"Metadata" => "true"}
end
response = Net::HTTP.get(URI(url), headers)
JSON.parse(response).fetch("access_token")
end
credentials = Juglow::WorkloadIdentityCredentials.new(
identity_token_provider: -> { fetch_entra_token },
federation_rule_id: ENV.fetch("JUGLOW_FEDERATION_RULE_ID"),
organization_id: ENV.fetch("JUGLOW_ORGANIZATION_ID"),
service_account_id: ENV.fetch("JUGLOW_SERVICE_ACCOUNT_ID"),
workspace_id: ENV["JUGLOW_WORKSPACE_ID"]
)
client = Juglow::Client.new(credentials: credentials)
message = client.messages.create(
model: "haijun-opus-5-5",
max_tokens: 1024,
messages: [{role: "user", content: "Hello from Azure"}]
)
puts message.content.find { it.type == :text }.text # Tulis access token yang diterbitkan Entra ke file yang dapat dibaca CLI.
# Ditampilkan untuk VM atau VM Scale Set (IMDS). Di App Service, Functions, atau
# Container Apps, ambil dari "$IDENTITY_ENDPOINT?api-version=2019-08-01&resource=api://<APP_ID>"
# dengan -H "X-IDENTITY-HEADER: $IDENTITY_HEADER" sebagai gantinya.
# Jika ada beberapa user-assigned identity, tambahkan &client_id=<IDENTITY_CLIENT_ID>.
JUGLOW_IDENTITY_TOKEN_FILE=$(mktemp)
trap 'rm -f "$JUGLOW_IDENTITY_TOKEN_FILE"' EXIT
curl -sS -H "Metadata: true" \
"http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=api://<APP_ID>" \
| jq -r .access_token > "$JUGLOW_IDENTITY_TOKEN_FILE"
export JUGLOW_IDENTITY_TOKEN_FILE
# JUGLOW_FEDERATION_RULE_ID, JUGLOW_ORGANIZATION_ID,
# JUGLOW_SERVICE_ACCOUNT_ID, dan JUGLOW_WORKSPACE_ID dibaca dari environment.
ant messages create \
--model haijun-opus-5-5 \
--max-tokens 1024 \
--message '{role: user, content: "Hello from Azure"}'Verifikasi penyiapan
Dari resource Azure Anda, jalankan pertukaran cURL yang ditunjukkan di Peroleh dan gunakan token dan konfirmasikan bahwa POST /v1/oauth/token mengembalikan 200 dengan access_token yang diawali sk-ant-oat01- dan nilai expires_in dalam detik. Jika pertukaran gagal dengan respons 401 authentication_error yang tidak transparan (pesan Authentication failed), periksa halaman riwayat autentikasi untuk alasan penolakan, lalu dekode token Entra (lihat Memecahkan masalah pertukaran yang gagal untuk perintahnya) dan periksa penyebab paling umum di sisi Azure:
- Ketidakcocokan issuer:
issuer_urlyang terdaftar harus sama persis dengan claimisstoken. Token v2.0 membawahttps://login.microsoftonline.com/; jika claim/v2.0 veryang didekode adalah1.0, lihat Jika token Anda v1.0.
- Masa berlaku token: Token managed identity membawa rentang hingga 24 jam antara
iatdanexp. Jika issuer masih memiliki nilai7500dari wizard (atau default 1 jam), naikkanmax_jwt_lifetime_secondske86400seperti dijelaskan di Konfigurasikan Juglow.
- Ketidakcocokan audience:
audiencepada rule harus sama persis denganaudtoken: client ID app registration audience untuk token v2.0 yang dikonfigurasi panduan ini.
- Ketidakcocokan nama claim: Rule yang mencocokkan claim yang tidak dibawa token tidak akan pernah lolos. Token v1.0 membawa client ID di
appid, bukanazp; lihat Jika token Anda v1.0.
Menggunakan Entra Workload Identity pada AKS
Gunakan jalur ini ketika workload Anda berjalan di pod AKS. Entra Workload Identity memfederasikan service account Kubernetes dengan managed identity user-assigned: Kubernetes memproyeksikan token service account (ditandatangani oleh OIDC issuer cluster AKS) ke dalam pod di path dalam AZURE_FEDERATED_TOKEN_FILE. Token terproyeksi tersebut bukan token yang diterbitkan Entra, sehingga untuk tetap berada di jalur yang dimediasi Entra yang dijelaskan di halaman ini, workload melakukan pertukaran dua lompatan: pertama-tama menukarkan token terproyeksi di https://login.microsoftonline.com/ (grant client_credentials terfederasi) dengan access token yang diterbitkan Entra, lalu meneruskan token Entra tersebut ke Juglow SDK sebagai identity token.
Tip: Sebagai alternatif, pod AKS dapat melewati pertukaran Entra dan menyajikan token service account yang diproyeksikan Kubernetes langsung ke Juglow. Jalur tersebut mendaftarkan OIDC issuer cluster AKS Anda ke Juglow alih-alih tenant Entra Anda. Lihat Menggunakan WIF dengan Kubernetes untuk alur tersebut.
Konfigurasikan Entra Workload Identity
- Aktifkan OIDC issuer dan workload identity pada cluster Anda
Mengaktifkan workload identity menginstal mutating webhook azure-workload-identity untuk Anda; deploy secara manual hanya pada cluster non-AKS. Catat URL OIDC issuer cluster untuk federated credential yang Anda buat di langkah berikutnya.
az aks update \
--resource-group <RESOURCE_GROUP> \
--name <CLUSTER_NAME> \
--enable-oidc-issuer \
--enable-workload-identity
AKS_OIDC_ISSUER=$(az aks show \
--resource-group <RESOURCE_GROUP> \
--name <CLUSTER_NAME> \
--query oidcIssuerProfile.issuerUrl -o tsv)- Buat managed identity user-assigned
Catat dua nilai dari identitas: Client ID masuk ke anotasi service account (dan diinjeksikan ke pod sebagai AZURE_CLIENT_ID), dan Object (principal) ID muncul sebagai claim oid yang dicocokkan oleh federation rule Juglow Anda.
az identity create \
--resource-group <RESOURCE_GROUP> \
--name haijun-inference-identity \
--location <LOCATION>
# Dimasukkan ke anotasi service account; diinjeksikan ke pod sebagai AZURE_CLIENT_ID.
IDENTITY_CLIENT_ID=$(az identity show \
--resource-group <RESOURCE_GROUP> \
--name haijun-inference-identity \
--query clientId -o tsv)
# Muncul sebagai klaim oid yang dicocokkan oleh aturan federasi Anda.
IDENTITY_OBJECT_ID=$(az identity show \
--resource-group <RESOURCE_GROUP> \
--name haijun-inference-identity \
--query principalId -o tsv)- Buat service account Kubernetes beranotasi
Webhook azure-workload-identity membaca anotasi azure.workload.identity/client-id untuk menginjeksikan AZURE_CLIENT_ID ke dalam pod, yang dibaca dari environment oleh sampel di Peroleh dan gunakan token.
apiVersion: v1
kind: ServiceAccount
metadata:
name: haijun-inference
namespace: inference
annotations:
azure.workload.identity/client-id: <IDENTITY_CLIENT_ID>- Buat federated credential pada managed identity
Federated credential memercayai OIDC issuer cluster Anda untuk service account spesifik tersebut. Nilai --audience api://AzureADTokenExchange adalah audience tetap Entra untuk token service account Kubernetes yang masuk; nilai ini tidak terkait dengan audience Haijun API yang Anda daftarkan sebelumnya.
az identity federated-credential create \
--resource-group <RESOURCE_GROUP> \
--identity-name haijun-inference-identity \
--name haijun-inference-aks \
--issuer "$AKS_OIDC_ISSUER" \
--subject system:serviceaccount:inference:haijun-inference \
--audience api://AzureADTokenExchange- Beri label pada pod dan atur service account-nya
Pod harus membawa label azure.workload.identity/use: "true" dan berjalan sebagai service account beranotasi. Webhook kemudian menginjeksikan AZURE_FEDERATED_TOKEN_FILE, AZURE_CLIENT_ID, dan AZURE_TENANT_ID ke dalam pod. File di AZURE_FEDERATED_TOKEN_FILE berisi token service account yang diproyeksikan Kubernetes, ditandatangani oleh OIDC issuer cluster AKS.
apiVersion: v1
kind: Pod
metadata:
name: inference-worker
namespace: inference
labels:
azure.workload.identity/use: "true"
spec:
serviceAccountName: haijun-inference
containers:
- name: app
image: your-registry/inference-worker:latest- Dekode token sampel
Token yang dilihat federation rule Juglow Anda bukanlah file terproyeksi; melainkan token yang diterbitkan Entra yang dikembalikan oleh pertukaran client_credentials. Dari dalam pod berlabel, jalankan langkah 1 dari sampel cURL di Peroleh dan gunakan token dan dekode hasilnya. Token ini membawa bentuk claim yang sama dengan jalur managed identity:
{
"iss": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
"sub": "9f8e7d6c-1a2b-3c4d-5e6f-...",
"aud": "<APP_ID>",
"oid": "9f8e7d6c-1a2b-3c4d-5e6f-...",
"tid": "<TENANT_ID>",
"azp": "<IDENTITY_CLIENT_ID>",
"ver": "2.0",
"exp": 1775527120
}sub dan oid adalah object ID managed identity, aud adalah client ID app registration audience, dan azp adalah client ID managed identity (nilai AZURE_CLIENT_ID). Masa berlakunya berbeda dari jalur managed identity: token client_credentials secara default memiliki jendela acak 60 hingga 90 menit antara iat dan exp, bukan 24 jam.
Konfigurasikan Juglow
Di Haijun Console, buka Settings → Workload identity, klik Connect workload, dan pilih tile Microsoft Entra. Wizard memandu Anda mendaftarkan issuer, membuat service account, dan membuat federation rule.
Wizard membuat sumber daya ini untuk Anda. Gunakan nilai-nilai berikut, baik Anda memasukkannya di wizard maupun mengirimkannya ke Admin API:
Federation issuer: Pilih v2.0 (login.microsoftonline.com) di pemilih Token issuer pada wizard. (Pemilih ini default ke v1; default tersebut ada untuk tenant yang menggunakan kembali registrasi lama yang masih menerbitkan token v1.0.) Entra memublikasikan dokumen OIDC discovery di URL issuer per-tenant, jadi gunakan mode discovery. Setiap tenant Microsoft Entra yang Anda federasikan memerlukan record issuer-nya sendiri.
{
"name": "azure-prod-tenant",
"issuer_url": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
"jwks": { "type": "discovery" },
"max_jwt_lifetime_seconds": 7500
}Warning: Tile Microsoft Entra pada wizard Connect workload membuat issuer dengan
max_jwt_lifetime_secondsdiatur ke7500(sedikit di atas 2 jam), yang mencakup masa berlaku default 60 hingga 90 menit tokenclient_credentials. Kebijakan token-lifetime tenant atau Continuous Access Evaluation (CAE) dapat memperpanjang masa berlaku tersebut. Jikaexpdikurangiiatpada token yang Anda dekode melebihi 7500 detik, edit issuer di Settings → Workload identity → Issuers dan naikkanmax_jwt_lifetime_secondsagar sesuai, atau pertukaran gagal dengan respons401authentication_erroryang tidak transparan (pesanAuthentication failed). Jika tenant Anda juga menjalankan workload managed-identity dari Menggunakan managed identity, gunakan nilai86400dari bagian tersebut, yang mencakup kedua jalur.
Masa berlaku yang diterima lebih lama berarti token Entra yang bocor tetap dapat ditukar lebih lama. Jika token bocor, tuasnya adalah menonaktifkan federation rule; pencocokan oid yang ketat membatasi identitas mana yang dapat menukar token sejak awal, seperti dijelaskan di Batasi cakupan rule Anda.
Federation rule: Cocokkan pada object ID managed identity dan tenant ID Anda. Untuk token v2.0 yang dikonfigurasi panduan ini, nilai audience adalah client ID app registration audience (GUID dari Daftarkan audience token). Gunakan nilai aud yang persis dari token yang Anda dekode.
{
"name": "azure-inference-worker",
"issuer_id": "fdis_...",
"match": {
"audience": "<APP_ID>",
"claims": {
"oid": "9f8e7d6c-1a2b-3c4d-5e6f-...",
"tid": "<TENANT_ID>"
}
},
"target": {
"type": "service_account",
"service_account_id": "svac_..."
},
"workspace_id": "wrkspc_...",
"oauth_scope": "workspace:developer",
"token_lifetime_seconds": 600
}token_lifetime_seconds adalah masa berlaku access token Juglow yang dikembalikan oleh pertukaran, bukan masa berlaku token Entra; SDK me-refresh-nya untuk Anda.
Peroleh dan gunakan token
Saat runtime, pod melakukan pertukaran dua lompatan: pod mengirim token yang diproyeksikan Kubernetes (file di AZURE_FEDERATED_TOKEN_FILE) ke endpoint token Entra sebagai assertion client_credentials terfederasi, lalu menukarkan access token Entra yang dihasilkan di POST /v1/oauth/token. Setiap Juglow SDK menangani pertukaran kedua dan loop refresh ketika Anda meneruskan pengambilan token Entra ke identity_token_provider (typescript, php: identityTokenProvider; csharp: IdentityTokenProvider; go: option.WithFederationTokenProvider; java: federationTokenProvider), seperti ditunjukkan dalam contoh berikut. Tab cURL menunjukkan alur mentahnya.
Dua client ID berbeda muncul dalam sampel. adalah client ID app registration audience dari Daftarkan audience token; scope api:// meminta Entra untuk token yang dialamatkan ke audience tersebut. $AZURE_CLIENT_ID adalah client ID managed identity, diinjeksikan oleh webhook, dan mengidentifikasi pemanggil. Jangan menukar satu dengan yang lain.
Tip: Jika workload Anda sudah menggunakan pustaka klien Azure Identity, teruskan mekanisme perolehan tokennya (
DefaultAzureCredentialdengan scopeapi://) ke/.default identity_token_provider(typescript, php:identityTokenProvider; csharp:IdentityTokenProvider; go:option.WithFederationTokenProvider; java:federationTokenProvider) alih-alih melakukan pertukaran dua lompatan sendiri. Pustaka tersebut membaca variabel lingkunganAZURE_FEDERATED_TOKEN_FILE,AZURE_CLIENT_ID, danAZURE_TENANT_IDyang sama dan menangani pertukaran Entra.
# 1. Tukarkan token yang diproyeksikan Kubernetes (di $AZURE_FEDERATED_TOKEN_FILE)
# dengan JWT yang diterbitkan Entra.
ENTRA_JWT=$(curl -sS "https://login.microsoftonline.com/$AZURE_TENANT_ID/oauth2/v2.0/token" \
-d grant_type=client_credentials \
-d "client_id=$AZURE_CLIENT_ID" \
--data-urlencode "scope=api://<APP_ID>/.default" \
-d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
--data-urlencode "client_assertion@$AZURE_FEDERATED_TOKEN_FILE" \
| jq -r .access_token)
# 2. Tukarkan JWT Entra dengan token akses Juglow.
ACCESS_TOKEN=$(curl -sS https://haijun.my.id/v1/oauth/token \
-H "content-type: application/json" \
-d @- <<JSON | jq -r .access_token
{
"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
"assertion": "$ENTRA_JWT",
"federation_rule_id": "$JUGLOW_FEDERATION_RULE_ID",
"organization_id": "$JUGLOW_ORGANIZATION_ID",
"service_account_id": "$JUGLOW_SERVICE_ACCOUNT_ID",
"workspace_id": "$JUGLOW_WORKSPACE_ID"
}
JSON
)
# 3. Panggil Haijun API.
curl -sS https://haijun.my.id/v1/messages \
-H "authorization: Bearer $ACCESS_TOKEN" \
-H "juglow-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "haijun-opus-5-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello from Azure"}]
}' | jq -r '.content[] | select(.type == "text") | .text' import os
from pathlib import Path
import juglow
import requests
from juglow import WorkloadIdentityCredentials
def fetch_entra_token_via_federation() -> str:
federated_token = Path(os.environ["AZURE_FEDERATED_TOKEN_FILE"]).read_text()
response = requests.post(
f"https://login.microsoftonline.com/{os.environ['AZURE_TENANT_ID']}/oauth2/v2.0/token",
data={
"client_id": os.environ["AZURE_CLIENT_ID"],
"grant_type": "client_credentials",
"scope": "api://<APP_ID>/.default",
"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"client_assertion": federated_token,
},
timeout=5,
)
response.raise_for_status()
return response.json()["access_token"]
client = juglow.Juglow(
credentials=WorkloadIdentityCredentials(
identity_token_provider=fetch_entra_token_via_federation,
federation_rule_id=os.environ["JUGLOW_FEDERATION_RULE_ID"],
organization_id=os.environ["JUGLOW_ORGANIZATION_ID"],
service_account_id=os.environ["JUGLOW_SERVICE_ACCOUNT_ID"],
workspace_id=os.environ.get("JUGLOW_WORKSPACE_ID"),
),
)
message = client.messages.create(
model="haijun-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello from Azure"}],
)
print(next(block.text for block in message.content if block.type == "text")) import Juglow from "@juglow-ai/sdk";
import { oidcFederationProvider } from "@juglow-ai/sdk/lib/credentials/oidc-federation";
import { readFile } from "node:fs/promises";
async function fetchEntraTokenViaFederation(): Promise<string> {
const federatedToken = await readFile(process.env.AZURE_FEDERATED_TOKEN_FILE!, "utf8");
const response = await fetch(
`https://login.microsoftonline.com/${process.env.AZURE_TENANT_ID}/oauth2/v2.0/token`,
{
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
client_id: process.env.AZURE_CLIENT_ID!,
grant_type: "client_credentials",
scope: "api://<APP_ID>/.default",
client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
client_assertion: federatedToken
})
}
);
const body = (await response.json()) as { access_token: string };
return body.access_token;
}
const client = new Juglow({
credentials: oidcFederationProvider({
identityTokenProvider: fetchEntraTokenViaFederation,
federationRuleId: process.env.JUGLOW_FEDERATION_RULE_ID!,
organizationId: process.env.JUGLOW_ORGANIZATION_ID!,
serviceAccountId: process.env.JUGLOW_SERVICE_ACCOUNT_ID,
workspaceId: process.env.JUGLOW_WORKSPACE_ID,
baseURL: "https://haijun.my.id/",
fetch
})
});
const message = await client.messages.create({
model: "haijun-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello from Azure" }]
});
for (const block of message.content) {
if (block.type === "text") {
console.log(block.text);
}
} package main
import (
"context"
"encoding/json"
"fmt"
"net/http"
"net/url"
"os"
"strings"
"github.com/juglows/juglow-sdk-go"
"github.com/juglows/juglow-sdk-go/option"
)
func fetchEntraTokenViaFederation(ctx context.Context) (string, error) {
federatedToken, err := os.ReadFile(os.Getenv("AZURE_FEDERATED_TOKEN_FILE"))
if err != nil {
return "", err
}
form := url.Values{
"client_id": {os.Getenv("AZURE_CLIENT_ID")},
"grant_type": {"client_credentials"},
"scope": {"api://<APP_ID>/.default"},
"client_assertion_type": {"urn:ietf:params:oauth:client-assertion-type:jwt-bearer"},
"client_assertion": {strings.TrimSpace(string(federatedToken))},
}
tokenURL := "https://login.microsoftonline.com/" + os.Getenv("AZURE_TENANT_ID") + "/oauth2/v2.0/token"
req, err := http.NewRequestWithContext(ctx, http.MethodPost, tokenURL, strings.NewReader(form.Encode()))
if err != nil {
return "", err
}
req.Header.Set("content-type", "application/x-www-form-urlencoded")
resp, err := http.DefaultClient.Do(req)
if err != nil {
return "", err
}
defer resp.Body.Close()
var body struct {
AccessToken string `json:"access_token"`
}
if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
return "", err
}
return body.AccessToken, nil
}
func main() {
client := juglow.NewClient(
option.WithFederationTokenProvider(option.IdentityTokenFunc(fetchEntraTokenViaFederation), option.FederationOptions{
FederationRuleID: os.Getenv("JUGLOW_FEDERATION_RULE_ID"),
OrganizationID: os.Getenv("JUGLOW_ORGANIZATION_ID"),
ServiceAccountID: os.Getenv("JUGLOW_SERVICE_ACCOUNT_ID"),
WorkspaceID: os.Getenv("JUGLOW_WORKSPACE_ID"),
}),
)
message, err := client.Messages.New(context.TODO(), juglow.MessageNewParams{
Model: juglow.ModelHaijunOpus5_5,
MaxTokens: 1024,
Messages: []juglow.MessageParam{
juglow.NewUserMessage(juglow.NewTextBlock("Hello from Azure")),
},
})
if err != nil {
panic(err)
}
for _, block := range message.Content {
if textBlock, ok := block.AsAny().(juglow.TextBlock); ok {
fmt.Println(textBlock.Text)
break
}
}
} IdentityTokenProvider fetchEntraTokenViaFederation = () -> {
try {
var form = Map.of(
"client_id", System.getenv("AZURE_CLIENT_ID"),
"grant_type", "client_credentials",
"scope", "api://<APP_ID>/.default",
"client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"client_assertion", Files.readString(Path.of(System.getenv("AZURE_FEDERATED_TOKEN_FILE"))))
.entrySet().stream()
.map(entry -> entry.getKey() + "=" + URLEncoder.encode(entry.getValue(), UTF_8))
.collect(Collectors.joining("&"));
var request = HttpRequest.newBuilder(URI.create(
"https://login.microsoftonline.com/" + System.getenv("AZURE_TENANT_ID") + "/oauth2/v2.0/token"))
.header("content-type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(form))
.build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
return new ObjectMapper().readTree(response.body()).get("access_token").asText();
} catch (Exception e) {
throw new RuntimeException(e);
}
};
JuglowClient client = JuglowOkHttpClient.builder()
.federationTokenProvider(
fetchEntraTokenViaFederation,
System.getenv("JUGLOW_FEDERATION_RULE_ID"),
System.getenv("JUGLOW_ORGANIZATION_ID"),
System.getenv("JUGLOW_SERVICE_ACCOUNT_ID"),
System.getenv("JUGLOW_WORKSPACE_ID"))
.build();
var message = client.messages().create(MessageCreateParams.builder()
.model(Model.HAIJUN_OPUS_5_5)
.maxTokens(1024)
.addUserMessage("Hello from Azure")
.build());
IO.println(message.content()); using Juglow.Credentials;
// ...
var credentials = new WorkloadIdentityCredentials(new WorkloadIdentityOptions
{
FederationRuleId = Environment.GetEnvironmentVariable("JUGLOW_FEDERATION_RULE_ID")!,
OrganizationId = Environment.GetEnvironmentVariable("JUGLOW_ORGANIZATION_ID"),
ServiceAccountId = Environment.GetEnvironmentVariable("JUGLOW_SERVICE_ACCOUNT_ID"),
WorkspaceId = Environment.GetEnvironmentVariable("JUGLOW_WORKSPACE_ID"),
IdentityTokenProvider = new EntraFederationTokenProvider(),
});
using var client = new JuglowClient(new ClientOptions { Credentials = credentials });
var message = await client.Messages.Create(new()
{
Model = Model.HaijunOpus5_5,
MaxTokens = 1024,
Messages = [new() { Role = Role.User, Content = "Hello from Azure" }],
});
foreach (var block in message.Content)
{
if (block.Value is TextBlock textBlock)
{
Console.WriteLine(textBlock.Text);
}
}
class EntraFederationTokenProvider : IIdentityTokenProvider
{
private static readonly HttpClient Http = new();
public async Task<string> GetIdentityTokenAsync(CancellationToken ct = default)
{
var federatedToken = await File.ReadAllTextAsync(
Environment.GetEnvironmentVariable("AZURE_FEDERATED_TOKEN_FILE")!, ct);
var tenantId = Environment.GetEnvironmentVariable("AZURE_TENANT_ID");
var form = new FormUrlEncodedContent(new Dictionary<string, string>
{
["client_id"] = Environment.GetEnvironmentVariable("AZURE_CLIENT_ID")!,
["grant_type"] = "client_credentials",
["scope"] = "api://<APP_ID>/.default",
["client_assertion_type"] = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
["client_assertion"] = federatedToken,
});
var response = await Http.PostAsync(
$"https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token", form, ct);
response.EnsureSuccessStatusCode();
using var json = await JsonDocument.ParseAsync(
await response.Content.ReadAsStreamAsync(ct), default, ct);
return json.RootElement.GetProperty("access_token").GetString()!;
}
} use Juglow\Client;
use Juglow\Credentials\WorkloadIdentityCredentials;
function fetchEntraTokenViaFederation(): string
{
$ch = curl_init('https://login.microsoftonline.com/' . getenv('AZURE_TENANT_ID') . '/oauth2/v2.0/token');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => http_build_query([
'client_id' => getenv('AZURE_CLIENT_ID'),
'grant_type' => 'client_credentials',
'scope' => 'api://<APP_ID>/.default',
'client_assertion_type' => 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
'client_assertion' => file_get_contents(getenv('AZURE_FEDERATED_TOKEN_FILE')),
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
return $body['access_token'];
}
$client = new Client(
credentials: new WorkloadIdentityCredentials(
identityTokenProvider: fetchEntraTokenViaFederation(...),
federationRuleId: getenv('JUGLOW_FEDERATION_RULE_ID'),
organizationId: getenv('JUGLOW_ORGANIZATION_ID'),
serviceAccountId: getenv('JUGLOW_SERVICE_ACCOUNT_ID'),
workspaceId: getenv('JUGLOW_WORKSPACE_ID') ?: null,
),
);
$message = $client->messages->create(
model: 'haijun-opus-5-5',
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Hello from Azure']],
);
$textBlock = array_find($message->content, static fn ($block): bool => $block->type === 'text');
echo $textBlock->text, PHP_EOL; require "juglow"
require "json"
require "net/http"
def fetch_entra_token_via_federation
tenant_id = ENV.fetch("AZURE_TENANT_ID")
federated_token = File.read(ENV.fetch("AZURE_FEDERATED_TOKEN_FILE"))
response = Net::HTTP.post_form(
URI("https://login.microsoftonline.com/#{tenant_id}/oauth2/v2.0/token"),
"client_id" => ENV.fetch("AZURE_CLIENT_ID"),
"grant_type" => "client_credentials",
"scope" => "api://<APP_ID>/.default",
"client_assertion_type" => "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"client_assertion" => federated_token
)
JSON.parse(response.body).fetch("access_token")
end
client = Juglow::Client.new(
credentials: Juglow::WorkloadIdentityCredentials.new(
identity_token_provider: -> { fetch_entra_token_via_federation },
federation_rule_id: ENV.fetch("JUGLOW_FEDERATION_RULE_ID"),
organization_id: ENV.fetch("JUGLOW_ORGANIZATION_ID"),
service_account_id: ENV.fetch("JUGLOW_SERVICE_ACCOUNT_ID"),
workspace_id: ENV["JUGLOW_WORKSPACE_ID"]
)
)
message = client.messages.create(
model: "haijun-opus-5-5",
max_tokens: 1024,
messages: [{role: "user", content: "Hello from Azure"}]
)
puts message.content.find { it.type == :text }.text # 1. Tukarkan token yang diproyeksikan Kubernetes dengan token akses yang diterbitkan Entra
# lalu tulis ke file sementara yang dapat dibaca CLI.
JUGLOW_IDENTITY_TOKEN_FILE=$(mktemp)
trap 'rm -f "$JUGLOW_IDENTITY_TOKEN_FILE"' EXIT
curl -sS "https://login.microsoftonline.com/$AZURE_TENANT_ID/oauth2/v2.0/token" \
-d client_id="$AZURE_CLIENT_ID" \
-d grant_type=client_credentials \
--data-urlencode "scope=api://<APP_ID>/.default" \
-d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
--data-urlencode client_assertion@"$AZURE_FEDERATED_TOKEN_FILE" \
| jq -r .access_token > "$JUGLOW_IDENTITY_TOKEN_FILE"
export JUGLOW_IDENTITY_TOKEN_FILE
# 2. Panggil Haijun API. JUGLOW_FEDERATION_RULE_ID,
# JUGLOW_ORGANIZATION_ID, JUGLOW_SERVICE_ACCOUNT_ID, dan JUGLOW_WORKSPACE_ID dibaca
# dari environment.
ant messages create \
--model haijun-opus-5-5 \
--max-tokens 1024 \
--message '{role: user, content: "Hello from Azure"}'Verifikasi penyiapan
Dari dalam pod berlabel, jalankan pertukaran cURL yang ditunjukkan di Peroleh dan gunakan token dan konfirmasikan bahwa POST /v1/oauth/token mengembalikan 200 dengan access_token yang diawali sk-ant-oat01- dan nilai expires_in dalam detik. Jika pertukaran gagal dengan respons 401 authentication_error yang tidak transparan (pesan Authentication failed), periksa halaman riwayat autentikasi untuk alasan penolakan, lalu dekode token yang diterbitkan Entra dari langkah 1 (lihat Memecahkan masalah pertukaran yang gagal untuk perintahnya) dan periksa penyebab paling umum di sisi Azure:
- Ketidakcocokan issuer:
issuer_urlyang terdaftar harus sama persis dengan claimisstoken. Token v2.0 membawahttps://login.microsoftonline.com/; jika claim/v2.0 veryang didekode adalah1.0, lihat Jika token Anda v1.0.
- Masa berlaku token: Jika kebijakan token-lifetime tenant atau CAE memperpanjang token
client_credentialsmelebihi 7500 detik, naikkanmax_jwt_lifetime_secondsissuer seperti dijelaskan di Konfigurasikan Juglow.
- Ketidakcocokan audience:
audiencepada rule harus sama persis denganaudtoken: client ID app registration audience untuk token v2.0 yang dikonfigurasi panduan ini.
- Ketidakcocokan nama claim: Rule yang mencocokkan claim yang tidak dibawa token tidak akan pernah lolos. Token v1.0 membawa client ID di
appid, bukanazp; lihat Jika token Anda v1.0.
Jika token Anda v1.0
Panduan ini mengonfigurasi app registration audience dengan api.requestedAccessTokenVersion: 2, sehingga setiap token yang ditampilkan adalah v2.0. Jika Anda menggunakan kembali registrasi yang sudah ada yang membiarkan requestedAccessTokenVersion tidak diatur, Entra menerbitkan token v1.0 sebagai gantinya. Dekode token sampel dan periksa claim ver-nya; jika nilainya 1.0, empat hal berubah:
- Issuer: Claim
issadalahhttps://sts.windows.net/alih-alih/ https://login.microsoftonline.com/. Daftarkan URL issuer persis seperti yang dibawa claim/v2.0 isstoken Anda. Kedua URL berbagi JWKS yang sama, sehingga mode discovery berfungsi untuk keduanya.
- Pemilih wizard: Pilih v1 (sts.windows.net) di pemilih Token issuer pada wizard Connect workload alih-alih v2.0 (login.microsoftonline.com).
- Audience: Claim
audadalah identifier URI yang Anda teruskan sebagairesource(misalnya,api://), bukan client ID registrasi. Aturaudiencefederation rule ke nilaiaudyang persis dari token yang Anda dekode.
- Claim client ID: Client ID identitas pemanggil muncul di
appid, bukanazp. Kedua claim tidak pernah muncul dalam token yang sama, sehingga rule yang mencocokkanazptidak akan pernah lolos terhadap token v1.0.
Claim oid, sub, dan tid membawa nilai yang sama di kedua versi, sehingga sisa panduan ini berlaku tanpa perubahan.
Batasi cakupan rule Anda
Federation rule dapat mencocokkan subject token dengan subject_prefix selain (atau sebagai pengganti) map claims; lihat Semantik pencocokan rule untuk cara field-field tersebut digabungkan. Nilai sub Entra untuk identitas ini adalah GUID kanonis dengan panjang tetap, sehingga subject_prefix yang berisi object ID lengkap 36 karakter hanya cocok dengan subject tersebut; ini adalah sifat format subject Entra, bukan sifat subject_prefix secara umum.
Warning: Setiap identitas di tenant Anda dapat meminta token untuk audience yang terdaftar, sehingga
audiencedantidsaja tidak mengidentifikasi workload tertentu. Rule yang menghilangkan pencocokanoid(atauazp/appid), atau yang menggunakan wildcard atausubject_prefixGUID parsial, mengotorisasi setiap managed identity dan service principal di tenant.
Kunci blok match pada rule ke cakupan tersempit yang sesuai dengan kasus penggunaan Anda:
- Cocokkan
oidsebagai nilai persis: Aturclaims.oidke object ID lengkap managed identity.subject_prefixyang diatur ke object ID lengkap tersebut setara (wizard Console mengatur keduanya); jangan pernah menggunakan wildcard atausubject_prefixGUID parsial, yang cocok dengan lebih banyak identitas daripada yang Anda maksudkan.
- Kunci
tidsebagai pertahanan berlapis: URL issuer sudah mengunci tenant Anda, tetapi menambahkanclaims.tidmelindungi dari pergeseran konfigurasi jika record issuer diedit di kemudian hari.
- Kunci audience: Atur
audienceke nilaiaudyang persis dari token yang Anda dekode sehingga token yang dicetak untuk aplikasi lain ditolak.
- Gunakan rule terpisah untuk setiap managed identity: Buat satu rule untuk setiap identitas alih-alih satu rule yang mengotorisasi beberapa identitas, sehingga Anda dapat mencabut akses satu workload tanpa memengaruhi yang lain.
Langkah selanjutnya
- Tinjau model konfigurasi lengkap di Workload Identity Federation.
- Lihat panduan provider untuk AWS, Google Cloud, GitHub Actions, dan Kubernetes.
- Untuk variabel lingkungan, file profil, dan prioritas kredensial, lihat referensi WIF.