Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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:
- Nessuna autenticazione per gli endpoint pubblici
- Autenticazione con chiave API per un accesso semplice basato su token
- Flusso del codice di autorizzazione OAuth2 per integrazioni sicure non Microsoft
- Autenticazione Single Sign-On (SSO) di Microsoft Entra per l'integrazione delle identità di Microsoft 365
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">