การอ้างอิง JavaScript API การรับรองความถูกต้อง

Fabric Extensibility Toolkit มี JavaScript API สําหรับการรับโทเค็นการรับรองความถูกต้องที่สามารถใช้เพื่อเข้าถึง Fabric API, บริการ Azure และแอปพลิเคชันที่มีความปลอดภัยทาง Entra บทความนี้ให้ข้อมูลอ้างอิง API และตัวอย่างการใช้งานที่ครอบคลุม

การอ้างอิง API

acquireFrontendAccessToken(params: AcquireFrontendAccessTokenParams): Promise<AccessToken>;

export interface AcquireFrontendAccessTokenParams {
    scopes: string[];
}

export interface AccessToken {
    token: string;
}

API ส่งคืน AccessToken ออบเจ็กต์ที่ประกอบด้วย:

• token: สตริงโทเค็น JWT ที่จะใช้ในส่วนหัวการให้สิทธิ์

การใช้งานพื้นฐาน

การได้มาซึ่งโทเค็นอย่างง่าย

// Acquire a token with default Fabric permissions
const token = await workloadClient.auth.acquireFrontendAccessToken({ scopes: [] });

// Use the token in API calls
const response = await fetch('https://api.fabric.microsoft.com/v1/workspaces', {
  headers: {
    'Authorization': `Bearer ${token.token}`,
    'Content-Type': 'application/json'
  }
});

โทเค็นที่มีขอบเขตเฉพาะ

// Request specific scopes for Azure Storage
const token = await workloadClient.auth.acquireFrontendAccessToken({
  scopes: ['https://storage.azure.com/user_impersonation']
});

ตัวอย่างการใช้โทเค็น

การเข้าถึง Fabric API

โทเค็นสามารถใช้ได้โดยตรงกับ Fabric REST API:

async function listWorkspaces() {
  const token = await workloadClient.auth.acquireFrontendAccessToken({ scopes: [] });
  
  const response = await fetch('https://api.fabric.microsoft.com/v1/workspaces', {
    headers: {
      'Authorization': `Bearer ${token.token}`
    }
  });
  
  return await response.json();
}

การเข้าถึงบริการ Azure

ใช้ขอบเขตเพื่อระบุบริการ Azure ที่คุณต้องการเข้าถึง:

async function readFromStorage(accountName, containerName, blobName) {
  const token = await workloadClient.auth.acquireFrontendAccessToken({
    scopes: ['https://storage.azure.com/user_impersonation']
  });
  
  const url = `https://${accountName}.blob.core.windows.net/${containerName}/${blobName}`;
  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${token.token}`,
      'x-ms-version': '2021-12-02'
    }
  });
  
  return await response.text();
}

การเข้าถึงแอปพลิเคชันแบบกําหนดเอง

เข้าถึงแอปพลิเคชันที่ปลอดภัยด้วย Entra ของคุณเอง:

async function callCustomAPI() {
  const token = await workloadClient.auth.acquireFrontendAccessToken({
    scopes: ['https://myapp.contoso.com/data.read']
  });
  
  const response = await fetch('https://myapp.contoso.com/api/data', {
    headers: {
      'Authorization': `Bearer ${token.token}`
    }
  });
  
  return await response.json();
}

การอ้างอิงพารามิเตอร์

ขอบเขต

อาร์เรย์ของสตริงขอบเขตที่ระบุสิทธิ์ที่โทเค็นของคุณต้องการ

ขอบเขตบริการ Azure ทั่วไป:

• https://storage.azure.com/user_impersonation - ที่เก็บข้อมูล Azure
• https://vault.azure.net/user_impersonation - ห้องนิรภัยคีย์ Azure
• https://management.azure.com/user_impersonation - ตัวจัดการทรัพยากร Azure
• https://graph.microsoft.com/User.Read - ไมโครซอฟท์กราฟ

ตัวอย่างการใช้งาน:

const token = await workloadClient.auth.acquireFrontendAccessToken({
  scopes: [
    'https://storage.azure.com/user_impersonation'
  ]
});

อาร์เรย์ขอบเขตว่างเปล่า: ใช้อาร์เรย์ว่างเพื่อรับโทเค็นที่มีสิทธิ์ Fabric เริ่มต้น:

const token = await workloadClient.auth.acquireFrontendAccessToken({ scopes: [] });

การจัดการความยินยอม

ขั้นตอนการยินยอมอัตโนมัติ

ชุดเครื่องมือความสามารถในการขยายจะจัดการเวิร์กโฟลว์ความยินยอมโดยอัตโนมัติ:

• คําขอเริ่มต้น: หากไม่มีความยินยอม หน้าต่างป๊อปอัปจะเปิดขึ้น
• การโต้ตอบกับผู้ใช้: ผู้ใช้ให้หรือปฏิเสธสิทธิ์
• ปิดอัตโนมัติ: ป๊อปอัปจะปิดโดยอัตโนมัติหลังจากผู้ใช้ดําเนินการ
• การส่งโทเค็น: หากสําเร็จ โทเค็นจะถูกส่งคืนไปยังแอปพลิเคชันของคุณ

การจัดการป๊อปอัปความยินยอม

ชุดเครื่องมือจะจัดการป๊อปอัปความยินยอมโดยอัตโนมัติ แต่คุณสามารถปรับแต่งลักษณะการทํางานของ URI การเปลี่ยนเส้นทางได้ สร้างหน้าเปลี่ยนเส้นทางที่จัดการการตอบกลับความยินยอม:

// redirect.js - Handle consent redirect
const redirectUriPath = '/close';
const url = new URL(window.location.href);

if (url.pathname?.startsWith(redirectUriPath)) {
  // Handle consent errors
  if (url?.hash?.includes("error")) {
    // Extract error information
    const errorMatch = url.hash.match(/error=([^&]+)/);
    const errorDescription = url.hash.match(/error_description=([^&]+)/);
    
    // Handle specific errors
    if (url.hash.includes("AADSTS650052")) {
      console.error("Service principal not configured");
    } else if (url.hash.includes("AADSTS65004")) {
      console.error("User declined consent");
    }
  }
  
  // Always close the popup immediately
  window.close();
}

ความยินยอมข้ามผู้เช่า

สําหรับการเข้าถึงทรัพยากรในผู้เช่าที่แตกต่างกัน:

// Request consent for cross-tenant access
const token = await workloadClient.auth.acquireAccessToken({
  additionalScopesToConsent: ['https://api.partner-app.com/data.read']
});

การจัดการข้อผิดพลาด

สถานการณ์ข้อผิดพลาดทั่วไป

async function robustTokenAcquisition() {
  try {
    return await workloadClient.auth.acquireAccessToken();
  } catch (error) {
    switch (error.code) {
      case 'user_cancelled':
        console.log('User cancelled the consent dialog');
        break;
      case 'consent_required':
        console.log('Additional consent required');
        break;
      case 'interaction_required':
        console.log('User interaction required');
        break;
      default:
        console.error('Authentication error:', error.message);
    }
    throw error;
  }
}

การจัดการการหมดอายุของโทเค็น

class TokenManager {
  private currentToken: AccessToken | null = null;
  
  async getValidToken(): Promise<AccessToken> {
    if (!this.currentToken || this.isTokenExpired(this.currentToken)) {
      this.currentToken = await workloadClient.auth.acquireAccessToken();
    }
    return this.currentToken;
  }
  
  private isTokenExpired(token: AccessToken): boolean {
    // Add buffer time to prevent requests with almost-expired tokens
    const bufferMinutes = 5;
    const expirationWithBuffer = new Date(token.expiresOn.getTime() - (bufferMinutes * 60 * 1000));
    return new Date() >= expirationWithBuffer;
  }
}

แนวทางปฏิบัติที่ดีที่สุด

การแคชโทเค็นและการนํากลับมาใช้ใหม่

• โทเค็นแคช: จัดเก็บโทเค็นในหน่วยความจําจนกว่าจะหมดอายุ
• การรีเฟรชอัตโนมัติ: ใช้การรีเฟรชโทเค็นอัตโนมัติก่อนหมดอายุ
• ที่เก็บข้อมูลที่ปลอดภัย: อย่าเก็บโทเค็นไว้ในที่เก็บข้อมูลในเครื่องหรือคุกกี้

การจัดการขอบเขต

• ขอบเขตขั้นต่ํา: ขอเฉพาะสิทธิ์ที่คุณต้องการ
• ความยินยอมแบบก้าวหน้า: ขอขอบเขตเพิ่มเติมเมื่อมีการใช้ฟีเจอร์
• การตรวจสอบขอบเขต: ยืนยันโทเค็นมีขอบเขตที่จําเป็นก่อนการเรียกใช้ API

การจัดการข้อผิดพลาดขั้นสูง

• การเสื่อมสภาพอย่างสง่างาม: ให้ฟังก์ชันสํารองเมื่อการรับรองความถูกต้องล้มเหลว
• การส่งข้อความของผู้ใช้: อธิบายให้ชัดเจนว่าเหตุใดจึงจําเป็นต้องมีสิทธิ์
• ตรรกะการลองใหม่: ใช้กลไกการลองใหม่ที่เหมาะสมสําหรับความล้มเหลวชั่วคราว

การเพิ่มประสิทธิภาพ

• คําขอแบบขนาน: รับโทเค็นสําหรับบริการหลายรายการพร้อมกันเมื่อเป็นไปได้
• การดําเนินการแบบแบทช์: การเรียก API แบบกลุ่มเพื่อลดค่าใช้จ่ายในการได้มาซึ่งโทเค็น
• การจัดการแคช: ใช้กลยุทธ์การแคชโทเค็นที่มีประสิทธิภาพ

เนื้อหาที่เกี่ยวข้อง

• เริ่มต้นใช้งานด่วน: รับโทเค็น Microsoft Entra - คู่มือเริ่มต้นใช้งานอย่างง่าย
• ภาพรวมการรับรองความถูกต้อง - แนวคิดการรับรองความถูกต้องระดับสูง
• แนวทางการรับรองความถูกต้อง - แนวทางปฏิบัติที่ดีที่สุดและคําแนะนํา
• เข้าถึง Fabric API - ตัวห่อหุ้ม API ที่สร้างไว้ล่วงหน้า