Haijun Platform Docs
EN

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:

  1. 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.
  1. Siapkan identitas untuk platform Anda: Managed identity pada VM, VM Scale Sets, App Service, Functions, dan Container Apps, atau Entra Workload Identity pada AKS.
  1. Konfigurasikan Juglow: Daftarkan issuer Entra tenant Anda, buat service account, dan tulis federation rule yang cocok dengan claim token.
  1. Tukar saat runtime: Workload Anda menukar token yang diterbitkan Entra di POST /v1/oauth/token dengan access token Juglow sk-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).

bash
# 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 URI https:// hanya untuk domain terverifikasi milik tenant Anda sendiri, sehingga URI seperti https://haijun.my.id/ tidak dapat didaftarkan di sebagian besar tenant; api:// diterima di mana saja. Dengan requestedAccessTokenVersion: 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

  1. 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.)

  1. 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/token dengan header Metadata: true dan api-version=2018-02-01.
  • App Service, Functions, dan Container Apps: URL dalam variabel lingkungan IDENTITY_ENDPOINT dengan header X-IDENTITY-HEADER yang diatur ke nilai IDENTITY_HEADER, dan api-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.

  1. 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:

json
{
  "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
}
ClaimNilaiCocokkan ini ketika
oidObject ID managed identity, identik dengan subAnda ingin mengotorisasi satu managed identity tertentu. Ini adalah default; rule di Konfigurasikan Juglow mencocokkannya.
azpClient ID identitas pemanggilAnda ingin mengotorisasi setiap workload yang berbagi satu app registration. Untuk managed identity, azp unik untuk identitas tersebut, sehingga setara dengan oid.
audClient ID app registration audience (GUID dari Daftarkan audience token)Selalu. Field audience pada rule harus sama persis dengan nilai aud token.
tidTenant ID AndaAnda 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.

json
{
  "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 antara iat dan exp karena 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 respons 401 authentication_error yang tidak transparan (pesan Authentication failed). Tile Microsoft Entra pada wizard Connect workload membuat issuer dengan max_jwt_lifetime_seconds diatur ke 7500 dan tidak menyediakan field untuk mengubahnya saat pembuatan, jadi selesaikan wizard, lalu buka Settings → Workload identity → Issuers, edit issuer, dan naikkan nilainya ke 86400. 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.

json
{
  "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 (DefaultAzureCredential dengan scope api:///.default) ke 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.

bash
  # 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'
python
  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"))
typescript
  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);
    }
  }
go
  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
  		}
  	}
  }
java
  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());
csharp
  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()!;
      }
  }
php
  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;
ruby
  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
bash
  # 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_url yang terdaftar harus sama persis dengan claim iss token. Token v2.0 membawa https://login.microsoftonline.com//v2.0; jika claim ver yang didekode adalah 1.0, lihat Jika token Anda v1.0.
  • Masa berlaku token: Token managed identity membawa rentang hingga 24 jam antara iat dan exp. Jika issuer masih memiliki nilai 7500 dari wizard (atau default 1 jam), naikkan max_jwt_lifetime_seconds ke 86400 seperti dijelaskan di Konfigurasikan Juglow.
  • Ketidakcocokan audience: audience pada rule harus sama persis dengan aud token: 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, bukan azp; 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//oauth2/v2.0/token (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

  1. 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.

bash
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)
  1. 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.

bash
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)
  1. 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.

yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: haijun-inference
  namespace: inference
  annotations:
    azure.workload.identity/client-id: <IDENTITY_CLIENT_ID>
  1. 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.

bash
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
  1. 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.

yaml
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
  1. 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:

json
{
  "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.

json
{
  "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_seconds diatur ke 7500 (sedikit di atas 2 jam), yang mencakup masa berlaku default 60 hingga 90 menit token client_credentials. Kebijakan token-lifetime tenant atau Continuous Access Evaluation (CAE) dapat memperpanjang masa berlaku tersebut. Jika exp dikurangi iat pada token yang Anda dekode melebihi 7500 detik, edit issuer di Settings → Workload identity → Issuers dan naikkan max_jwt_lifetime_seconds agar sesuai, atau pertukaran gagal dengan respons 401 authentication_error yang tidak transparan (pesan Authentication failed). Jika tenant Anda juga menjalankan workload managed-identity dari Menggunakan managed identity, gunakan nilai 86400 dari 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.

json
{
  "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:///.default 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 (DefaultAzureCredential dengan scope api:///.default) ke identity_token_provider (typescript, php: identityTokenProvider; csharp: IdentityTokenProvider; go: option.WithFederationTokenProvider; java: federationTokenProvider) alih-alih melakukan pertukaran dua lompatan sendiri. Pustaka tersebut membaca variabel lingkungan AZURE_FEDERATED_TOKEN_FILE, AZURE_CLIENT_ID, dan AZURE_TENANT_ID yang sama dan menangani pertukaran Entra.

bash
  # 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'
python
  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"))
typescript
  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);
    }
  }
go
  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
  		}
  	}
  }
java
  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());
csharp
  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()!;
      }
  }
php
  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;
ruby
  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
bash
  # 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_url yang terdaftar harus sama persis dengan claim iss token. Token v2.0 membawa https://login.microsoftonline.com//v2.0; jika claim ver yang didekode adalah 1.0, lihat Jika token Anda v1.0.
  • Masa berlaku token: Jika kebijakan token-lifetime tenant atau CAE memperpanjang token client_credentials melebihi 7500 detik, naikkan max_jwt_lifetime_seconds issuer seperti dijelaskan di Konfigurasikan Juglow.
  • Ketidakcocokan audience: audience pada rule harus sama persis dengan aud token: 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, bukan azp; 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 iss adalah https://sts.windows.net// alih-alih https://login.microsoftonline.com//v2.0. Daftarkan URL issuer persis seperti yang dibawa claim iss token 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 aud adalah identifier URI yang Anda teruskan sebagai resource (misalnya, api://), bukan client ID registrasi. Atur audience federation rule ke nilai aud yang persis dari token yang Anda dekode.
  • Claim client ID: Client ID identitas pemanggil muncul di appid, bukan azp. Kedua claim tidak pernah muncul dalam token yang sama, sehingga rule yang mencocokkan azp tidak 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 audience dan tid saja tidak mengidentifikasi workload tertentu. Rule yang menghilangkan pencocokan oid (atau azp/appid), atau yang menggunakan wildcard atau subject_prefix GUID 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 oid sebagai nilai persis: Atur claims.oid ke object ID lengkap managed identity. subject_prefix yang diatur ke object ID lengkap tersebut setara (wizard Console mengatur keduanya); jangan pernah menggunakan wildcard atau subject_prefix GUID parsial, yang cocok dengan lebih banyak identitas daripada yang Anda maksudkan.
  • Kunci tid sebagai pertahanan berlapis: URL issuer sudah mengunci tenant Anda, tetapi menambahkan claims.tid melindungi dari pergeseran konfigurasi jika record issuer diedit di kemudian hari.
  • Kunci audience: Atur audience ke nilai aud yang 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

  • Lihat panduan provider untuk AWS, Google Cloud, GitHub Actions, dan Kubernetes.
  • Untuk variabel lingkungan, file profil, dan prioritas kredensial, lihat referensi WIF.
On this page
PrasyaratDaftarkan audience tokenMenggunakan managed identityKonfigurasikan managed identityKonfigurasikan JuglowPeroleh dan gunakan tokenVerifikasi penyiapanMenggunakan Entra Workload Identity pada AKSKonfigurasikan Entra Workload IdentityKonfigurasikan JuglowPeroleh dan gunakan tokenVerifikasi penyiapanJika token Anda v1.0Batasi cakupan rule AndaLangkah selanjutnya