Autenticare gli endpoint remoti

Gli endpoint remoti nei carichi di lavoro Microsoft Fabric usano un meccanismo di autenticazione specializzato che fornisce sia il contesto utente che l'identità dell'applicazione. Questo articolo illustra come implementare l'autenticazione per gli endpoint remoti che gestiscono processi, notifiche del ciclo di vita e altre operazioni back-end.

Panoramica dei flussi di autenticazione

I carichi di lavoro dell'infrastruttura prevedono tre flussi di autenticazione principali:

1. Infrastruttura a carico di lavoro - Infrastruttura chiama l'endpoint remoto con il formato SubjectAndAppToken
2. Carico di lavoro su Fabric - il carico di lavoro chiama le API di Fabric con token SubjectAndAppToken o Bearer
3. Front-end del carico di lavoro da front-end a back-end - il front-end chiama il back-end con token Bearer

Questo articolo è incentrato sull'autenticazione delle richieste da Fabric al carico di lavoro e sull'effettuare chiamate autenticate a Fabric.

Formato SubjectAndAppToken

Quando Fabric chiama l'endpoint remoto (per processi, notifiche del ciclo di vita o altre operazioni), usa un formato di autenticazione a doppio token denominato SubjectAndAppToken.

Struttura dell'intestazione di autorizzazione

SubjectAndAppToken1.0 subjectToken="<user-delegated-token>", appToken="<app-only-token>"

Questo formato include due token distinti:

• subjectToken - Token delegato che rappresenta l'utente per conto del quale viene eseguita l'operazione
• appToken - Un token dedicato all'applicazione Fabric, a dimostrazione che la richiesta proviene da Fabric

Perché i doppio token?

L'approccio a doppio token offre tre vantaggi principali:

1. Convalida : verificare che la richiesta abbia avuto origine da Fabric convalidando appToken
2. Contesto utente : subjectToken fornisce il contesto utente per l'azione eseguita
3. Comunicazione Inter-Service - Usare subjectToken per acquisire token OBO (On-Behalf-Of) per chiamare altri servizi nel contesto utente

Analisi sintattica di SubjectAndAppToken

L'endpoint remoto deve analizzare l'intestazione Autorizzazione per estrarre entrambi i token.

Esempio javaScript

/**
 * Parse SubjectAndAppToken from Authorization header
 * @param {string} authHeader - Authorization header value
 * @returns {object|null} Parsed tokens or null if invalid format
 */
function parseSubjectAndAppToken(authHeader) {
  if (!authHeader || !authHeader.startsWith('SubjectAndAppToken1.0 ')) {
    return null;
  }

  const tokenPart = authHeader.substring('SubjectAndAppToken1.0 '.length);
  const tokens = {};
  
  const parts = tokenPart.split(',');

  for (const part of parts) {
    const [key, value] = part.split('=');
    if (key && value) {
      // Remove surrounding quotes from the token value
      const cleanValue = value.trim().replace(/^"(.*)"$/, '$1');
      tokens[key.trim()] = cleanValue;
    }
  }

  return {
    subjectToken: tokens.subjectToken || null,
    appToken: tokens.appToken || null
  };
}

Esempio di utilizzo

const authHeader = req.headers['authorization'];
const tokens = parseSubjectAndAppToken(authHeader);

if (!tokens || !tokens.appToken) {
  return res.status(401).json({ error: 'Invalid authorization header' });
}

// Now you have access to:
// - tokens.subjectToken (user-delegated token, may be null)
// - tokens.appToken (Fabric app token, always present)

// Check if user context is available
if (tokens.subjectToken) {
  console.log('Request has user context');
} else {
  console.log('Request is app-only (no user context)');
}

Convalida dei token

Entrambi i token devono essere convalidati per garantire l'autenticità e le attestazioni appropriate.

Convalida del token dell'app

appToken è un token per app di Fabric. Convalidare:

• firma Token - Verificare le chiavi di firma di Azure AD
• Durata dei token: controllare le claim nbf (non prima) e exp (scadenza)
• Destinatari : deve corrispondere alla registrazione dell'app relativa al carico di lavoro
• Issuer : deve essere Azure AD con il tenant corretto
• idtyp attestazione - deve essere utilizzata per token esclusivi per app
• Nessuna scp dichiarazione : i token per sole app non hanno dichiarazioni di ambito
• ID tenant - Deve corrispondere all'ID tenant del publisher

Attestazioni appToken di esempio:

{
  "aud": "api://localdevinstance/aaaabbbb-0000-cccc-1111-dddd2222eeee/Fabric.WorkloadSample/123",
  "iss": "https://sts.windows.net/12345678-77f3-4fcc-bdaa-487b920cb7ee/",
  "iat": 1700047232,
  "nbf": 1700047232,
  "exp": 1700133932,
  "appid": "11112222-bbbb-3333-cccc-4444dddd5555",
  "appidacr": "2",
  "idtyp": "app",
  "oid": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "tid": "bbbbcccc-1111-dddd-2222-eeee3333ffff",
  "ver": "1.0"
}

Convalida del token di soggetto

subjectToken è un token delegato dall'utente. Convalidare:

• Firma del token - Verifica contro le chiavi di firma di Azure AD
• Durata dei token - Controllare nbf e exp attestazioni
• Destinatari : deve corrispondere alla registrazione dell'app del carico di lavoro
• Issuer : deve essere Azure AD con il tenant corretto
• scp dichiarazione - deve includere l'ambito "FabricWorkloadControl"
• Nessuna idtyp attestazione : i token delegati non hanno questa attestazione
• appid deve corrispondere - dovrebbe essere lo stesso dell'appToken

Esempi di affermazioni per subjectToken:

{
  "aud": "api://localdevinstance/aaaabbbb-0000-cccc-1111-dddd2222eeee/Fabric.WorkloadSample/123",
  "iss": "https://sts.windows.net/12345678-77f3-4fcc-bdaa-487b920cb7ee/",
  "iat": 1700050446,
  "nbf": 1700050446,
  "exp": 1700054558,
  "appid": "11112222-bbbb-3333-cccc-4444dddd5555",
  "scp": "FabricWorkloadControl",
  "name": "john doe",
  "oid": "bbbbbbbb-1111-2222-3333-cccccccccccc",
  "upn": "user1@contoso.com",
  "tid": "bbbbcccc-1111-dddd-2222-eeee3333ffff",
  "ver": "1.0"
}

Esempio di convalida dei token JavaScript

const jwt = require('jsonwebtoken');
const jwksClient = require('jwks-rsa');

/**
 * Validate Azure AD token
 * @param {string} token - JWT token to validate
 * @param {object} options - Validation options
 * @returns {Promise<object>} Validated token claims
 */
async function validateAadToken(token, options = {}) {
  const { isAppOnly = false, tenantId = null, audience = null } = options;

  // Decode token to get header and tenant
  const decoded = jwt.decode(token, { complete: true });
  if (!decoded) {
    throw new Error('Invalid token format');
  }

  const { header, payload } = decoded;
  const tokenTenantId = payload.tid;

  // Get signing key from Azure AD
  const client = jwksClient({
    jwksUri: `https://login.microsoftonline.com/${tokenTenantId}/discovery/v2.0/keys`,
    cache: true,
    cacheMaxAge: 86400000 // 24 hours
  });

  const signingKey = await new Promise((resolve, reject) => {
    client.getSigningKey(header.kid, (err, key) => {
      if (err) reject(err);
      else resolve(key.getPublicKey());
    });
  });

  // Verify token signature and claims
  const verifyOptions = {
    algorithms: ['RS256'],
    audience: audience,
    clockTolerance: 60 // 1 minute clock skew
  };

  const verified = jwt.verify(token, signingKey, verifyOptions);

  // Validate app-only vs delegated token
  if (isAppOnly) {
    if (verified.idtyp !== 'app') {
      throw new Error('Expected app-only token');
    }
    if (verified.scp) {
      throw new Error('App-only token should not have scp claim');
    }
  } else {
    if (verified.idtyp) {
      throw new Error('Expected delegated token');
    }
    if (!verified.scp || !verified.scp.includes('FabricWorkloadControl')) {
      throw new Error('Missing required FabricWorkloadControl scope');
    }
  }

  // Validate tenant if required
  if (tenantId && verified.tid !== tenantId) {
    throw new Error(`Token tenant mismatch: expected ${tenantId}, got ${verified.tid}`);
  }

  return verified;
}

Middleware di autenticazione

Implementare il middleware per autenticare le richieste in ingresso da Fabric.

Completare il flusso di autenticazione

/**
 * Authentication middleware that validates control plane calls from Fabric
 * Handles both user-delegated (with subjectToken) and app-only (without subjectToken) scenarios
 * @param {object} req - Express request object
 * @param {object} res - Express response object
 * @param {object} options - Authentication options
 * @param {boolean} options.requireSubjectToken - Whether subject token is required (default: false)
 * @returns {Promise<boolean>} True if authenticated successfully
 */
async function authenticateControlPlaneCall(req, res, options = {}) {
  const { requireSubjectToken = false } = options;
  try {
    // Extract and parse authorization header
    const authHeader = req.headers['authorization'];
    if (!authHeader) {
      return res.status(401).json({ error: 'Missing Authorization header' });
    }

    const tokens = parseSubjectAndAppToken(authHeader);
    if (!tokens || !tokens.appToken) {
      return res.status(401).json({ error: 'Invalid Authorization header format' });
    }

    // Get tenant ID from header
    const tenantId = req.headers['ms-client-tenant-id'];
    if (!tenantId) {
      return res.status(400).json({ error: 'Missing ms-client-tenant-id header' });
    }

    // Get configuration
    const publisherTenantId = process.env.TENANT_ID;
    const audience = process.env.BACKEND_AUDIENCE;
    const fabricBackendAppId = '00000009-0000-0000-c000-000000000000';

    // Validate app token (from Fabric)
    const appTokenClaims = await validateAadToken(tokens.appToken, {
      isAppOnly: true,
      audience: audience
    });

    // Verify app token is from Fabric
    const appTokenAppId = appTokenClaims.appid || appTokenClaims.azp;
    if (appTokenAppId !== fabricBackendAppId) {
      return res.status(401).json({ error: 'App token not from Fabric' });
    }

    // Verify app token is in publisher's tenant
    if (publisherTenantId && appTokenClaims.tid !== publisherTenantId) {
      return res.status(401).json({ error: 'App token tenant mismatch' });
    }

    // Validate subject token if present
    let subjectTokenClaims = null;
    if (tokens.subjectToken) {
      subjectTokenClaims = await validateAadToken(tokens.subjectToken, {
        isAppOnly: false,
        audience: audience,
        tenantId: tenantId
      });

      // Verify subject token has same appid as app token
      const subjectAppId = subjectTokenClaims.appid || subjectTokenClaims.azp;
      if (subjectAppId !== appTokenAppId) {
        return res.status(401).json({ error: 'Token appid mismatch' });
      }
    } else if (requireSubjectToken) {
      // If subject token is required but missing, reject the request
      return res.status(401).json({ 
        error: 'Subject token required for this operation' 
      });
    }

    // Store authentication context in request
    req.authContext = {
      subjectToken: tokens.subjectToken,
      appToken: tokens.appToken,
      tenantId: tenantId,
      hasSubjectContext: !!tokens.subjectToken,
      appTokenClaims: appTokenClaims,
      subjectTokenClaims: subjectTokenClaims,
      userId: subjectTokenClaims?.oid || subjectTokenClaims?.sub,
      userName: subjectTokenClaims?.name || subjectTokenClaims?.upn
    };

    return true; // Authentication successful

  } catch (error) {
    console.error('Authentication failed:', error.message);
    res.status(401).json({ error: 'Authentication failed' });
    return false;
  }
}

Uso del middleware

app.post('/api/jobs/execute', async (req, res) => {
  // Authenticate the request (subjectToken is optional)
  const authenticated = await authenticateControlPlaneCall(req, res);
  if (!authenticated) {
    return; // Response already sent by middleware
  }

  // Access authentication context
  const { hasSubjectContext, userId, userName, tenantId, subjectToken } = req.authContext;
  
  if (hasSubjectContext) {
    console.log(`Executing job for user: ${userName} (${userId})`);
  } else {
    console.log('Executing job in app-only context (no user)');
  }
  
  // Execute job logic...
});

// Example: Require user context for specific operations
app.post('/api/lifecycle/create', async (req, res) => {
  // For create operations, we might require user context
  const authenticated = await authenticateControlPlaneCall(req, res, {
    requireSubjectToken: true
  });
  if (!authenticated) {
    return; // Response already sent by middleware
  }

  // User context is guaranteed to be present here
  const { userId, userName } = req.authContext;
  console.log(`Creating item for user: ${userName}`);
  
  // Handle creation...
});

// Example: Allow app-only context for delete operations
app.post('/api/lifecycle/delete', async (req, res) => {
  // Delete operations might not have user context
  const authenticated = await authenticateControlPlaneCall(req, res, {
    requireSubjectToken: false // Default, but shown for clarity
  });
  if (!authenticated) {
    return;
  }

  const { hasSubjectContext, userName } = req.authContext;
  if (hasSubjectContext) {
    console.log(`Deleting item for user: ${userName}`);
  } else {
    console.log('Deleting item (system operation)');
  }
  
  // Handle deletion...
});

Scambio di token - Flusso on-Behalf-Of (OBO)

Per chiamare le API di Fabric o accedere a OneLake dall'endpoint remoto, è necessario scambiare il subjectToken dell'utente per il token specifico della risorsa usando il flusso On-Behalf-Of OAuth 2.0.

Servizio di Scambio Token

const https = require('https');
const { URL } = require('url');

const AAD_LOGIN_URL = 'https://login.microsoftonline.com';
const ONELAKE_SCOPE = 'https://storage.azure.com/.default';
const FABRIC_SCOPE = 'https://analysis.windows.net/powerbi/api/.default';

/**
 * Get token for any scope using OBO flow
 * @param {string} userToken - User's access token (subjectToken)
 * @param {string} tenantId - User's tenant ID
 * @param {string} scope - Target resource scope
 * @returns {Promise<string>} Access token for the requested scope
 * @throws {Error} Throws consent-related errors (AADSTS65001, AADSTS65005) that should be propagated to UX
 */
async function getTokenForScope(userToken, tenantId, scope) {
  const clientId = process.env.BACKEND_APPID;
  const clientSecret = process.env.BACKEND_CLIENT_SECRET;

  if (!clientId || !clientSecret) {
    throw new Error('BACKEND_APPID and BACKEND_CLIENT_SECRET required');
  }

  const tokenEndpoint = `${AAD_LOGIN_URL}/${tenantId}/oauth2/v2.0/token`;
  const requestBody = new URLSearchParams({
    grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
    client_id: clientId,
    client_secret: clientSecret,
    assertion: userToken,
    scope: scope,
    requested_token_use: 'on_behalf_of'
  }).toString();

  const response = await makeTokenRequest(tokenEndpoint, requestBody);

  if (!response.access_token) {
    throw new Error('Token exchange failed: missing access_token');
  }

  return response.access_token;
}

/**
 * Get OneLake access token
 * @param {string} userToken - User's access token from authContext
 * @param {string} tenantId - User's tenant ID
 * @returns {Promise<string>} OneLake access token
 */
async function getOneLakeToken(userToken, tenantId) {
  return getTokenForScope(userToken, tenantId, ONELAKE_SCOPE);
}

/**
 * Get Fabric OBO token for calling Fabric APIs
 * @param {string} userToken - User's access token
 * @param {string} tenantId - User's tenant ID
 * @returns {Promise<string>} Fabric OBO token
 */
async function getFabricOboToken(userToken, tenantId) {
  return getTokenForScope(userToken, tenantId, FABRIC_SCOPE);
}

/**
 * Make HTTPS request to token endpoint
 */
function makeTokenRequest(url, body) {
  return new Promise((resolve, reject) => {
    const parsedUrl = new URL(url);
    const options = {
      hostname: parsedUrl.hostname,
      port: 443,
      path: parsedUrl.pathname,
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Content-Length': Buffer.byteLength(body)
      }
    };

    const req = https.request(options, (res) => {
      let responseBody = '';
      res.on('data', (chunk) => { responseBody += chunk; });
      res.on('end', () => {
        const parsed = JSON.parse(responseBody);
        if (res.statusCode >= 200 && res.statusCode < 300) {
          resolve(parsed);
        } else {
          const error = parsed.error_description || parsed.error || `HTTP ${res.statusCode}`;
          reject(new Error(error));
        }
      });
    });

    req.on('error', reject);
    req.write(body);
    req.end();
  });
}

Scambio di Token

// In your job or lifecycle notification handler
async function handleJobExecution(req, res) {
  const authenticated = await authenticateControlPlaneCall(req, res);
  if (!authenticated) return;

  const { hasSubjectContext, subjectToken, tenantId } = req.authContext;

  try {
    // Only exchange token if user context is available
    if (hasSubjectContext) {
      // Get OneLake token to access item data on behalf of the user
      const oneLakeToken = await getOneLakeToken(subjectToken, tenantId);
      
      // Use OneLake token to read/write data
      const data = await readFromOneLake(oneLakeToken, workspaceId, itemId);
      
      // Process data...
    } else {
      // Handle app-only scenario
      // You may need to use different authentication or skip user-specific operations
      console.log('Processing job without user context');
      // Use workspace or item-level access instead
    }
    
    res.status(200).json({ status: 'completed' });
  } catch (error) {
    console.error('Job execution failed:', error);
    res.status(500).json({ error: 'Job execution failed' });
  }
}

Chiamate alle API di Fabric

Per chiamare le API di controllo del carico di lavoro di Fabric, è necessario costruire un oggetto SubjectAndAppToken con token OBO e S2S.

Token da servizio a servizio (S2S)

Oltre al token OBO, è necessario un token S2S solo per app per la parte appToken.

/**
 * Get S2S (Service-to-Service) token using client credentials flow
 * @param {string} tenantId - Publisher's tenant ID
 * @param {string} scope - Target resource scope
 * @returns {Promise<string>} S2S access token
 */
async function getS2STokenForScope(tenantId, scope) {
  const clientId = process.env.BACKEND_APPID;
  const clientSecret = process.env.BACKEND_CLIENT_SECRET;

  if (!clientId || !clientSecret) {
    throw new Error('BACKEND_APPID and BACKEND_CLIENT_SECRET required');
  }

  const tokenEndpoint = `${AAD_LOGIN_URL}/${tenantId}/oauth2/v2.0/token`;
  const requestBody = new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: clientId,
    client_secret: clientSecret,
    scope: scope
  }).toString();

  const response = await makeTokenRequest(tokenEndpoint, requestBody);

  if (!response.access_token) {
    throw new Error('S2S token acquisition failed');
  }

  return response.access_token;
}

/**
 * Get Fabric S2S token
 * @param {string} publisherTenantId - Publisher's tenant ID
 * @returns {Promise<string>} Fabric S2S access token
 */
async function getFabricS2SToken(publisherTenantId) {
  return getS2STokenForScope(publisherTenantId, FABRIC_SCOPE);
}

Costruzione di token compositi per le API di Fabric

/**
 * Build composite token for Fabric API calls
 * @param {object} authContext - Authentication context
 * @returns {Promise<string>} SubjectAndAppToken formatted header value
 */
async function buildCompositeToken(authContext) {
  const { subjectToken, tenantId } = authContext;
  const publisherTenantId = process.env.TENANT_ID;

  if (!subjectToken) {
    throw new Error('Subject token is required');
  }

  // Exchange user's subject token for Fabric OBO token
  const fabricOboToken = await getFabricOboToken(subjectToken, tenantId);

  // Acquire S2S token using publisher tenant
  const fabricS2SToken = await getFabricS2SToken(publisherTenantId);

  // Combine into SubjectAndAppToken format
  return `SubjectAndAppToken1.0 subjectToken="${fabricOboToken}", appToken="${fabricS2SToken}"`;
}

Esempio di API di Calling Fabric

const axios = require('axios');

/**
 * Call Fabric workload control API
 */
async function callFabricApi(authContext, workspaceId, itemId) {
  // Build composite token
  const authHeader = await buildCompositeToken(authContext);

  // Call Fabric API
  const response = await axios.get(
    `https://api.fabric.microsoft.com/v1/workspaces/${workspaceId}/items/${itemId}`,
    {
      headers: {
        'Authorization': authHeader,
        'Content-Type': 'application/json'
      }
    }
  );

  return response.data;
}

Esempio completo: esecuzione del processo con autenticazione

Ecco un esempio completo di un endpoint di esecuzione del processo con autenticazione:

const express = require('express');
const app = express();

app.post('/api/jobs/:jobType/instances/:instanceId', async (req, res) => {
  // Authenticate the request from Fabric
  const authenticated = await authenticateControlPlaneCall(req, res);
  if (!authenticated) {
    return; // Response already sent
  }

  const { jobType, instanceId } = req.params;
  const { workspaceId, itemId } = req.body;
  const { subjectToken, tenantId, userId } = req.authContext;

  console.log(`Starting job ${jobType} for user ${userId}`);

  try {
    // Get OneLake token to access item data
    const oneLakeToken = await getOneLakeToken(subjectToken, tenantId);

    // Read data from OneLake
    const itemData = await readItemData(oneLakeToken, workspaceId, itemId);

    // Process the job
    const result = await processJob(jobType, itemData);

    // Write results back to OneLake
    await writeResults(oneLakeToken, workspaceId, itemId, result);

    // Return success
    res.status(202).json({
      status: 'InProgress',
      instanceId: instanceId,
      message: 'Job started successfully'
    });

  } catch (error) {
    console.error(`Job ${instanceId} failed:`, error);
    res.status(500).json({
      status: 'Failed',
      instanceId: instanceId,
      error: error.message
    });
  }
});

Operazioni a lunga durata

Per operazioni a esecuzione prolungata come i processi, i token possono scadere prima del completamento. Implementare la logica di aggiornamento del token:

// Store refresh tokens securely
const tokenCache = new Map();

/**
 * Get cached token or acquire new one
 */
async function getOrRefreshToken(userToken, tenantId, scope, cacheKey) {
  const cached = tokenCache.get(cacheKey);
  
  // Check if cached token is still valid (with 5 min buffer)
  if (cached && cached.expiresAt > Date.now() + 300000) {
    return cached.token;
  }

  // Acquire new token
  const response = await getTokenForScopeWithRefresh(userToken, tenantId, scope);
  
  // Cache the token
  tokenCache.set(cacheKey, {
    token: response.access_token,
    expiresAt: Date.now() + (response.expires_in * 1000)
  });

  return response.access_token;
}

Per altre informazioni sulla gestione dei processi OBO a esecuzione prolungata, vedere Processi OBO a esecuzione prolungata.

Procedure consigliate per la sicurezza

Archiviazione token

• Non registrare mai i token completi: registra solo gli ultimi 4 caratteri per il debug
• Archiviare i token in modo sicuro solo in memoria
• Cancellare i token dalla memoria dopo l'uso
• Non salvare i token su disco o database

Convalida dei token

• Verificare sempre l'appToken nel formato SubjectAndAppToken
• Convalidare il subjectToken solo se presente
• Verificare le firme dei token rispetto alle chiavi di Active Directory Azure
• Verificare la scadenza del token e i tempi di validità iniziale
• Convalidare le attestazioni dell'emittente, dell'audience e del tenant
• Verificare le attestazioni obbligatorie (scp, idtyp, ecc.)

Gestione del contesto utente mancante

• Progetta il tuo endpoint remoto per gestire sia scenari delegati all'utente che scenari solo per applicazioni.
• Verificare hasSubjectContext in authContext prima di accedere alle proprietà specifiche dell'utente
• Per le operazioni che richiedono il contesto utente, impostare requireSubjectToken: true nelle opzioni middleware
• Per le operazioni di eliminazione o di sistema, consentire il subjectToken mancante
• Documentare le operazioni che supportano il contesto esclusivamente delle app e quelle che richiedono il contesto utente.

Configurazione dell'ambiente

// Required environment variables
const requiredEnvVars = [
  'BACKEND_APPID',           // Your workload's app registration ID
  'BACKEND_CLIENT_SECRET',   // Your app's client secret
  'TENANT_ID',               // Your publisher tenant ID
  'BACKEND_AUDIENCE'         // Expected token audience
];

// Validate on startup
requiredEnvVars.forEach(varName => {
  if (!process.env[varName]) {
    throw new Error(`Missing required environment variable: ${varName}`);
  }
});

Gestione degli errori e propagazione del consenso

Quando lo scambio di token non riesce a causa di consenso o ambiti mancanti, il back-end deve propagare questi errori all'esperienza utente front-end per richiedere il consenso dell'utente. Gli errori comuni relativi al consenso includono:

• AADSTS65001 : l'utente o l'amministratore non ha acconsentito all'uso dell'applicazione
• AADSTS65005 : l'applicazione richiede ambiti specifici che non sono stati concessi

/**
 * Handle token exchange with consent error propagation
 * Consent errors should be returned to the frontend to trigger consent flow
 */
async function handleTokenExchangeWithConsent(req, res) {
  const { subjectToken, tenantId } = req.authContext;
  const clientId = process.env.BACKEND_APPID;
  
  try {
    const token = await getTokenForScope(subjectToken, tenantId, ONELAKE_SCOPE);
    // Use token for OneLake operations...
    
  } catch (error) {
    // Check for consent-related errors
    if (error.message.includes('AADSTS65001') || error.message.includes('AADSTS65005')) {
      // Extract scope from error if available
      const requiredScope = extractScopeFromError(error.message) || 'https://storage.azure.com/.default';
      
      // Build consent URL for the frontend to redirect the user
      const consentUrl = buildConsentUrl({
        clientId: clientId,
        tenantId: tenantId,
        scope: requiredScope,
        redirectUri: process.env.FRONTEND_URL || 'https://your-frontend.azurewebsites.net'
      });
      
      // Return consent required response
      return res.status(403).json({
        error: 'ConsentRequired',
        errorCode: error.message.includes('AADSTS65001') ? 'AADSTS65001' : 'AADSTS65005',
        message: 'User consent is required to access this resource',
        consentUrl: consentUrl,
        requiredScope: requiredScope
      });
    }
    
    // Other errors should be handled normally
    throw error;
  }
}

/**
 * Build consent URL for user authorization
 * @param {object} options - Consent URL options
 * @returns {string} Formatted consent URL
 */
function buildConsentUrl(options) {
  const { clientId, tenantId, scope, redirectUri } = options;
  
  const params = new URLSearchParams({
    client_id: clientId,
    response_type: 'code',
    redirect_uri: redirectUri,
    response_mode: 'query',
    scope: scope,
    state: 'consent_required' // Your frontend can use this to handle the redirect
  });
  
  return `https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/authorize?${params.toString()}`;
}

/**
 * Extract scope from error message
 */
function extractScopeFromError(errorMessage) {
  // Azure AD error messages often include the missing scope
  const scopeMatch = errorMessage.match(/scope[s]?[:\s]+([^\s,]+)/);
  return scopeMatch ? scopeMatch[1] : null;
}

Gestione del consenso front-end

Quando il front-end riceve un ConsentRequired errore, deve reindirizzare l'utente all'URL di consenso:

// Frontend code to handle consent errors
async function callBackendApi(endpoint, data) {
  try {
    const response = await fetch(endpoint, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });
    
    if (response.status === 403) {
      const error = await response.json();
      
      if (error.error === 'ConsentRequired' && error.consentUrl) {
        // Redirect user to consent page
        window.location.href = error.consentUrl;
        return;
      }
    }
    
    return await response.json();
    
  } catch (error) {
    console.error('API call failed:', error);
    throw error;
  }
}

Altri scenari di errore

// Handle various token exchange errors
try {
  const token = await getTokenForScope(subjectToken, tenantId, scope);
} catch (error) {
  const errorMessage = error.message;
  
  if (errorMessage.includes('AADSTS65001') || errorMessage.includes('AADSTS65005')) {
    // Consent required - propagate to frontend
    return propagateConsentError(res, error, tenantId);
    
  } else if (errorMessage.includes('AADSTS50013')) {
    // Invalid assertion - token may be expired
    return res.status(401).json({
      error: 'InvalidToken',
      message: 'The provided token is invalid or expired'
    });
    
  } else if (errorMessage.includes('AADSTS700016')) {
    // Application not found in tenant
    return res.status(400).json({
      error: 'ApplicationNotFound',
      message: 'Application is not configured in this tenant'
    });
  }
  
  // Unknown error
  throw error;
}

Risoluzione dei problemi

Problemi di autenticazione comuni

Errore: "Formato token non valido"

• Verificare che l'intestazione Autorizzazione inizi con SubjectAndAppToken1.0
• Verificare che siano presenti sia subjectToken che appToken
• Assicurarsi che i token siano racchiusi correttamente tra virgolette nell'intestazione

Errore: "Convalida del token non riuscita"

• Verifica che BACKEND_APPID corrisponda alla tua registrazione dell'applicazione
• Verificare che BACKEND_AUDIENCE sia configurato correttamente
• Verificare che i token non siano scaduti
• Controllare che l'emittente corrisponda al tenant di Azure AD.

Errore: "Scambio di token non riuscito: AADSTS65001"

• Il consenso dell'utente è necessario per l'ambito richiesto
• Verificare che la registrazione dell'app disponga delle autorizzazioni API necessarie
• Verificare che il consenso dell'amministratore sia stato concesso se necessario

Errore: "Token dell'app non da Fabric"

• Verificare che il reclamo di appToken appid corrisponda all'ID dell'app di Fabric.
• Verificare di essere in fase di test nell'ambiente corretto (sviluppo/produzione)

Contenuto correlato

• Abilitare endpoint remoti
• Abilitare processi remoti
• Abilitare le notifiche relative al ciclo di vita degli elementi
• Usare il servizio di risoluzione degli endpoint
• Processi OBO a lungo termine
• Esempio di sviluppo del carico di lavoro Fabric