Cenário: Usando o SDK do Microsoft Entra para o AgentID no TypeScript

Crie uma biblioteca de cliente TypeScript/Node.js que se integre ao SDK do Microsoft Entra do AgentID para obter tokens e invocar APIs downstream. Em seguida, integre esse cliente em aplicativos Express.js ou NestJS para lidar com solicitações de API autenticadas.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
• Node.js (versão 14 ou posterior) com o npm instalado no computador de desenvolvimento.
• SDK do Microsoft Entra para AgentID implantado e em execução em seu ambiente. Consulte o Guia de Instalação para obter instruções de instalação.
• APIs downstream configuradas no SDK com URLs base e escopos necessários.
• Permissões apropriadas no Microsoft Entra ID – Sua conta deve ter permissões para registrar aplicativos e conceder permissões de API.

Configuração

Antes de criar sua biblioteca de clientes, instale as dependências necessárias para fazer solicitações HTTP:

npm install node-fetch
npm install --save-dev @types/node-fetch

Implementação da biblioteca de clientes

Crie uma classe de cliente reutilizável que encapsula chamadas HTTP para o SDK do Microsoft Entra para AgentID. Essa classe manipula o encaminhamento de token, a configuração de solicitação e o tratamento de erros:

// sidecar-client.ts
import fetch from 'node-fetch';

export interface SidecarConfig {
  baseUrl: string;
  timeout?: number;
}

export class SidecarClient {
  private readonly baseUrl: string;
  private readonly timeout: number;
  
  constructor(config: SidecarConfig) {
    this.baseUrl = config.baseUrl || process.env.SIDECAR_URL || 'http://localhost:5000';
    this.timeout = config.timeout || 10000;
  }
  
  async getAuthorizationHeader(
    incomingToken: string,
    serviceName: string,
    options?: {
      scopes?: string[];
      tenant?: string;
      agentIdentity?: string;
      agentUsername?: string;
    }
  ): Promise<string> {
    const url = new URL(`${this.baseUrl}/AuthorizationHeader/${serviceName}`);
    
    if (options?.scopes) {
      options.scopes.forEach(scope => 
        url.searchParams.append('optionsOverride.Scopes', scope)
      );
    }
    
    if (options?.tenant) {
      url.searchParams.append('optionsOverride.AcquireTokenOptions.Tenant', options.tenant);
    }
    
    if (options?.agentIdentity) {
      url.searchParams.append('AgentIdentity', options.agentIdentity);
      if (options.agentUsername) {
        url.searchParams.append('AgentUsername', options.agentUsername);
      }
    }
    
    const response = await fetch(url.toString(), {
      headers: { 'Authorization': incomingToken },
      signal: AbortSignal.timeout(this.timeout)
    });
    
    if (!response.ok) {
      throw new Error(`SDK error: ${response.statusText}`);
    }
    
    const data = await response.json();
    return data.authorizationHeader;
  }
  
  async callDownstreamApi<T>(
    incomingToken: string,
    serviceName: string,
    relativePath: string,
    options?: {
      method?: string;
      body?: any;
      scopes?: string[];
    }
  ): Promise<T> {
    const url = new URL(`${this.baseUrl}/DownstreamApi/${serviceName}`);
    url.searchParams.append('optionsOverride.RelativePath', relativePath);
    
    if (options?.method && options.method !== 'GET') {
      url.searchParams.append('optionsOverride.HttpMethod', options.method);
    }
    
    if (options?.scopes) {
      options.scopes.forEach(scope => 
        url.searchParams.append('optionsOverride.Scopes', scope)
      );
    }
    
    const fetchOptions: any = {
      method: options?.method || 'GET',
      headers: { 'Authorization': incomingToken },
      signal: AbortSignal.timeout(this.timeout)
    };
    
    if (options?.body) {
      fetchOptions.headers['Content-Type'] = 'application/json';
      fetchOptions.body = JSON.stringify(options.body);
    }
    
    const response = await fetch(url.toString(), fetchOptions);
    
    if (!response.ok) {
      throw new Error(`SDK error: ${response.statusText}`);
    }
    
    const data = await response.json();
    
    if (data.statusCode >= 400) {
      throw new Error(`API error ${data.statusCode}: ${data.content}`);
    }
    
    return JSON.parse(data.content) as T;
  }
}

// Usage
const sidecar = new SidecarClient({ baseUrl: 'http://localhost:5000' });

// Get authorization header
const authHeader = await sidecar.getAuthorizationHeader(token, 'Graph');

// Call API
interface UserProfile {
  displayName: string;
  mail: string;
  userPrincipalName: string;
}

const profile = await sidecar.callDownstreamApi<UserProfile>(
  token,
  'Graph',
  'me'
);

integração Express.js

Integre a biblioteca de clientes a um aplicativo Express.js criando middleware para extrair o token de entrada e os manipuladores de rota que chamam APIs downstream:

import express from 'express';
import { SidecarClient } from './sidecar-client';

const app = express();
app.use(express.json());

const sidecar = new SidecarClient({ baseUrl: process.env.SIDECAR_URL! });

// Middleware to extract token
app.use((req, res, next) => {
  const token = req.headers.authorization;
  if (!token && !req.path.startsWith('/health')) {
    return res.status(401).json({ error: 'No authorization token' });
  }
  req.userToken = token;
  next();
});

// Routes
app.get('/api/profile', async (req, res) => {
  try {
    const profile = await sidecar.callDownstreamApi(
      req.userToken,
      'Graph',
      'me'
    );
    res.json(profile);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.get('/api/messages', async (req, res) => {
  try {
    const messages = await sidecar.callDownstreamApi(
      req.userToken,
      'Graph',
      'me/messages?$top=10'
    );
    res.json(messages);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(8080, () => {
  console.log('Server running on port 8080');
});

Integração do NestJS

Para aplicativos NestJS, crie um serviço que encapsula a biblioteca de clientes. Esse serviço pode ser injetado em controladores para lidar com solicitações autenticadas:

import { Injectable } from '@nestjs/common';
import { SidecarClient } from './sidecar-client';

@Injectable()
export class GraphService {
  private readonly sidecar: SidecarClient;
  
  constructor() {
    this.sidecar = new SidecarClient({ 
      baseUrl: process.env.SIDECAR_URL! 
    });
  }
  
  async getUserProfile(token: string) {
    return await this.sidecar.callDownstreamApi(
      token,
      'Graph',
      'me'
    );
  }
  
  async getUserMessages(token: string, top: number = 10) {
    return await this.sidecar.callDownstreamApi(
      token,
      'Graph',
      `me/messages?$top=${top}`
    );
  }
}

Práticas recomendadas

Ao usar o SDK do Microsoft Entra para AgentID do TypeScript, siga estas práticas para criar aplicativos confiáveis e mantêveis:

• Reutilizar a Instância do Cliente: crie uma única SidecarClient instância e reutilize-a em todo o aplicativo, em vez de criar novas instâncias por solicitação. Isso melhora o desempenho e o uso de recursos.
• Definir tempos limite apropriados: configure tempos limite de solicitação com base na latência da API downstream. Isso impede que seu aplicativo fique suspenso indefinidamente se o SDK ou o serviço downstream estiver lento.
• Implemente o Tratamento de Erros: adicione a lógica de repetição e tratamento de erros adequada, especialmente para falhas transitórias. Distingue entre erros de cliente (4xx) e erros de servidor (5xx) para determinar as respostas apropriadas.
• Utilize Interfaces TypeScript: defina interfaces TypeScript para respostas de API para garantir a segurança de tipo e capturar erros durante a compilação em vez de durante a execução.
• Habilitar o pool de conexões: use agentes HTTP para habilitar a reutilização de conexão entre solicitações, o que reduz a sobrecarga e melhora a taxa de transferência.

Outros guias de idioma

• Usando do Python
• Padrões de Identidade Gerenciada

Próximas etapas

Comece com um cenário:

• Chamar API Downstream
• Obter cabeçalho de autorização
• Validar cabeçalho de autorização