Supporto dell'autenticazione in TypeSpec per Microsoft 365 Copilot

Suggerimento

Consigliato: Inizia con Work IQ Dev Tools per scenari di agenti dichiarativi e plug-in pro-code supportati. Vedere la guida introduttiva di WIQD. Le istruzioni basate su toolkit rimangono disponibili per i progetti e i flussi di lavoro esistenti che le richiedono. Controlla il supporto per le funzionalità e l'esperienza di destinazione prima di scegliere uno strumento: WIQD non si rivolge agli agenti del motore personalizzato.

TypeSpec per Microsoft 365 Copilot supporta più metodi di autenticazione per proteggere i plug-in API e integrarsi con servizi esterni. I tipi di autenticazione supportati includono:

Nota

Questa documentazione illustra gli scenari di autenticazione specifici di Microsoft 365 Copilot. Per la documentazione completa sull'autenticazione TypeSpec, inclusi tutti i decoratori e i modelli di autenticazione nativa, consulta la documentazione di TypeSpec sull'autenticazione.

Nessuna autenticazione (anonima)

Endpoint pubblici che non richiedono credenziali di autenticazione. L'API non richiede nulla di specifico. Senza @useAuth decoratori, tutte le API sono considerate anonime.

Esempio

@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
namespace API {
  // Endpoints
}

Autenticazione con chiave API

Autenticazione tramite chiavi API o token di accesso personali applicati a interi spazi dei nomi. Usa il nativo ApiKeyAuth di TypeSpec.

Esempio

@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-Your-Key">)
namespace API {
  // Endpoints
}

Microsoft 365 Agents Toolkit è in grado di registrare automaticamente la chiave API e aggiunge l'azione apiKey/register a m365agents.yml nel progetto Agents Toolkit.

# m365agents.yml
# After the typespec/compile step
- uses: apiKey/register
  with:
    name: ApiKeyAuth
    appId: ${{TEAMS_APP_ID}}
    apiSpecPath: ./appPackage/.generated/api-openapi.yml
  writeToEnvironmentFile:
    registrationId: APIKEYAUTH_REGISTRATION_ID

L'esempio Gestisci le riparazioni con Microsoft 365 Copilot evidenzia l'uso dell'autenticazione con chiave API.

Flusso del codice di autorizzazione OAuth2

Autorizzazioni delegate dall'utente per l'accesso ai dati utente da un servizio protetto OAuth 2.0. Usa il nativo OAuth2Auth di TypeSpec. Aggiorna , authorizationUrltokenUrl, refreshUrl, e scopes in base all'API specifica con cui stai integrando.

Scopri come creare automaticamente la registrazione all'app Microsoft Entra utilizzando Agents Toolkit e aggiornare la registrazione all'app Microsoft Entra una volta completata la registrazione.

Esempio

@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(OAuth2Auth<[{
  type: OAuth2FlowType.authorizationCode;
  authorizationUrl: "https://contoso.com/oauth2/v2.0/authorize";
  tokenUrl: "https://contoso.com/oauth2/v2.0/token";
  refreshUrl: "https://contoso.com/oauth2/v2.0/token";
  scopes: ["scope-1", "scope-2"];
}]>)
namespace API {
  // Endpoints
}

Agents Toolkit può registrare automaticamente la configurazione OAuth2 e aggiunge anche l'azione oauth/register a m365agents.yml nel progetto Agents Toolkit.

# m365agents.yml
# After the typespec/compile step
- uses: oauth/register
  with:
    name: OAuth2Auth
    appId: ${{TEAMS_APP_ID}}
    clientId: ${{AAD_APP_CLIENT_ID}}
    clientSecret: ${{SECRET_AAD_APP_CLIENT_SECRET}}
    apiSpecPath: ./appPackage/.generated/api-openapi.yml
    flow: authorizationCode
  writeToEnvironmentFile:
    configurationId: OAUTH2AUTH_REGISTRATION_ID

L'esempio Agente attività che usa TypeSpec per Microsoft 365 Copilot che si connette alle API Microsoft Graph evidenzia l'uso di OAuth2 con il flusso del codice di autorizzazione.

Autenticazione SSO di Microsoft Entra

Autenticazione che applica la sessione di Microsoft 365 esistente dell'utente per gli scenari di integrazione nativi. Per completare la registrazione SSO, utilizzare il flusso regolare OAuth2Auth ed eseguire i passaggi manuali.

Utilizzo delle configurazioni di autenticazione registrate

Per gli scenari di produzione, registrare e gestire le credenziali di autenticazione tramite il portale per sviluppatori di Microsoft Teams invece di incorporarle direttamente nel codice TypeSpec. Utilizza Decorator @authReferenceId per fare riferimento a configurazioni di autenticazione preregistrate tramite i relativi identificatori univoci. Questo approccio offre un modo sicuro per gestire le credenziali senza esporre informazioni riservate nella codebase.

Quando si utilizza @authReferenceId, specificare l'ID di registrazione dalle registrazioni dei client OAuth o delle registrazioni delle chiavi API configurate nel portale per sviluppatori. Questo approccio separa la configurazione dell'autenticazione dal codice, consentendo migliori pratiche di sicurezza e una gestione più semplice delle credenziali in ambienti diversi.

Esempio

// Reference to OAuth2 client registration
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(Auth)
namespace API {
  // Endpoints
}

@authReferenceId("NzFmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IyM5NzQ5Njc3Yi04NDk2LTRlODYtOTdmZS1kNDUzODllZjUxYjM=")
model Auth is OAuth2Auth<[{
  type: OAuth2FlowType.authorizationCode;
  authorizationUrl: "https://contoso.com/oauth2/v2.0/authorize";
  tokenUrl: "https://contoso.com/oauth2/v2.0/token";
  refreshUrl: "https://contoso.com/oauth2/v2.0/token";
  scopes: ["scope-1", "scope-2"];
}]>

// Reference to API key registration
@service
@actions(ACTIONS_METADATA)
@server(SERVER_URL, API_NAME)
@useAuth(Auth)
namespace API {
  // Endpoints
}

@authReferenceId("5f701b3e-bf18-40fb-badd-9ad0b60b31c0")
model Auth is ApiKeyAuth<ApiKeyLocation.header, "X-Your-Key">