Microsoft Teams: errore “The tenant admin disabled this bot” nelle Message Extension – diagnosi e fix

La tua Message Extension per Microsoft Teams funziona in locale ma in ambiente di sviluppo restituisce “The tenant admin disabled this bot”? In questa guida trovi cause, diagnosi e correzioni, inclusa una nota su un incidente di servizio (TM710191) che ha temporaneamente bloccato i bot in alcuni tenant.

Indice

Panoramica dell’errore

In ambienti di sviluppo o test, una Message Extension (ME) può fallire con la risposta standardizzata di Teams/Graph:

{
  "errorCode": 0,
  "standardizedError": {
    "errorCode": 209,
    "errorSubCode": 1,
    "errorDescription": "The tenant admin disabled this bot"
  }
}

Il messaggio suggerisce un blocco “amministrativo”, ma non sempre dipende da una configurazione errata: può essere un problema di policy, di packaging/ID dell’app o, come avvenuto di recente, un incidente di servizio lato Teams.

Come si presenta il problema

La ME funziona in debug locale (es. tramite Teams Toolkit o tunneling) ma fallisce appena pubblicata nel tenant di sviluppo.
Le schede/bot standard dell’app sembrano funzionare, mentre le azioni di search o action della ME restituiscono l’errore 209.
Alcuni utenti del tenant riescono a usare la ME, altri no, o viceversa.

Causa temporanea nota: incidente TM710191

Microsoft ha comunicato l’incidente TM710191: un aggiornamento del servizio Teams ha provocato il blocco dei bot in specifici tenant EDU ed enterprise. L’aggiornamento è stato annullato e, dopo il rollback, i bot hanno ripreso a funzionare normalmente. Prima di intraprendere azioni invasive, verifica lo stato servizio:

Apri il Service Health Dashboard in Microsoft 365 Admin Center.
Controlla se TM710191 o incidenti correlati sono stati chiusi per il tuo tenant.
Se segnalato come Resolved, effettua sign‑out/sign‑in in Teams e riprova.

Nota: la presenza di un incidente spiega perché un’app funzionante in locale (fuori dal perimetro di alcune policy/servizi) smette di funzionare in un ambiente tenant: l’errore 209 è il risultato del gate di conformità/abilitazione applicato dal servizio.

Diagnosi rapida (10 minuti)

Prima di addentrarti in verifiche più profonde, passa da questa checklist essenziale:

Stato servizio: controlla il Service Health Dashboard (vedi sopra).
Manage apps (tenant): in Teams Admin Center → Teams apps → Manage apps, la tua app/bot deve essere Allowed.
Permission policies: verifica in Teams Admin Center → Teams apps → Permission policies che la policy assegnata agli utenti interessati non blocchi la tua app o i custom apps.
Setup policies: se la ME è pinnata o distribuita via policy, accertati che non ci siano conflitti di distribuzione.
Bot Channels: nel Bot Channels Registration di Azure, il canale Microsoft Teams deve essere abilitato e Healthy.
App IDs allineati: verifica che botId nel manifest.json di Teams corrisponda all’Application (client) ID della registrazione in Entra ID (ex Azure AD).
Propagation: se hai appena modificato policy o app, attendi fino a 1 ora per la propagazione. Poi sign‑out/sign‑in o pulisci cache.

Tabella di orientamento: sintomo → causa probabile → rimedio

Sintomo	Causa probabile	Rimedio
Errore 209 in dev, la stessa app funziona in locale	Incidente di servizio (es. TM710191) o policy tenant restrittive	Verifica Service Health; se ok, controlla Manage apps e Permission policies
Alcuni utenti vedono l’errore, altri no	Policy diverse assegnate a gruppi/utenti	Allinea la Permission policy o crea un’eccezione “Allow specific apps”
App Allowed ma la ME non appare	`manifest.json` incompleto o composeExtensions non conformi	Rivedi il manifest e riallinea ID e scopes
Funziona in un tenant, bloccata in un altro	App registrata single‑tenant o publisher non verificato	Valuta multi‑tenant per scenari cross‑tenant; rivedi i requisiti di distribuzione
Errore dopo aggiornamento versione app	App ID/bot ID cambiati o pacchetto non firmato/approvato	Mantieni gli stessi ID tra versioni; fai re‑approve nel Manage apps

Verifiche dettagliate in Teams Admin Center

Manage apps (consent/allowlist)

Vai a Teams Admin Center → Teams apps → Manage apps.
Cerca il nome o l’App ID della tua applicazione.
Assicurati che lo Status sia Allowed. Se è Blocked, cambia in Allowed.
Se l’app è “custom” (Line‑of‑Business), verifica che non sia limitata da criteri globali che impediscono la distribuzione di app personalizzate.

Suggerimento: quando aggiorni il pacchetto della app, conserva gli stessi identificativi (appId e botId) per evitare che l’Admin Center la tratti come una nuova app non ancora autorizzata.

Permission policies

Le Permission policies controllano quali app possono essere usate dagli utenti. Nella policy assegnata al tuo utente/gruppo:

Impostazione “Allow all apps” oppure “Allow specific apps” che includa la tua.
Se usi “Block specific apps”, accertati che la tua app non sia nell’elenco di blocco.

Dopo la modifica, attendi la propagazione (fino a 1 ora) e fai sign‑out/sign‑in in Teams.

Setup policies

Queste policy non abilitano il bot di per sé, ma determinano pin e visibilità dell’app. Una distribuzione incoerente può far credere che l’app sia “disabilitata” perché non compare dove l’utente si aspetta. Controlla pin e installed apps coerenti con il gruppo di test.

Verifiche nel portale Azure

Bot Channels Registration

Apri la risorsa Azure Bot (Bot Channels Registration o la risorsa Bot v4).
Nella sezione Channels, verifica che Microsoft Teams sia Enabled e senza errori.
Controlla il Messaging endpoint: deve essere raggiungibile dal servizio Teams (https, certificato valido, versione del framework aggiornata).

Nota: se l’endpoint locale usa tunneling (es. https://xyz.ngrok.io) e in produzione pubblichi un dominio differente, aggiorna il manifest.json e la configurazione del bot di conseguenza.

Microsoft Entra ID (ex Azure AD): app registration & manifest

Application (client) ID: deve coincidere con il botId del manifest.json.
Single vs multi‑tenant: per scenari cross‑tenant abilita multi‑tenant.
Segreti/certificati: non scaduti, con permessi corretti per eventuale SSO o Graph chiamati dalla ME.
requiredResourceAccess: se usi SSO, i permessi delegati devono riflettersi nel token e nello scope scp.

Sebbene l’errore 209 indichi soprattutto un gate lato Teams, incongruenze di ID o permessi possono portare a rifiuti di caricamento che l’utente interpreta come “disabilitato”.

Manifest dell’app di Teams: punti critici

Il file manifest.json guida l’installazione della tua app in Teams. Verifica con cura:

botId e developer: identificativi e metadati coerenti.
validDomains: includi tutti i domini usati dall’endpoint e dalle schede della ME.
composeExtensions: definizioni delle azioni (query, fetchTask, submitAction) complete e conformi.
Versioning: incrementa version ad ogni build distribuita per forzare l’aggiornamento.

Buone pratiche operative

Propagazione: pianifica sempre un buffer di fino a 1 ora dopo modifiche a policy o stato app.
Refresh client: chiedi agli utenti di fare sign‑out/sign‑in o usare un profilo/browser pulito per evitare cache.
Ambienti coerenti: mantieni gli stessi ID app/bot tra Dev, Test e Prod. Cambiare ID genera nuove approvazioni.
Telemetria: logga activityId/correlationId lato bot per correlare le richieste fallite.

Risoluzione guidata: dal sintomo alla fix

Conferma lo stato del servizio: se TM710191 (o incidenti analoghi) risultano chiusi per il tuo tenant, prosegui con le verifiche locali.
Conferma l’allowlist: in Manage apps la tua app deve essere Allowed. Se cambi lo stato, salva e attendi.
Allinea le Permission policies:
- Se usi “Allow specific apps”, aggiungi esplicitamente la tua app.
- Controlla l’assegnazione della policy agli utenti che testano la ME.
Verifica il canale Teams nel bot: deve essere abilitato; in caso di warning/error, risolvi prima di riprovare.
Controlla il manifest: botId = Application ID; validDomains completi; composeExtensions aggiornate.
Re‑installazione controllata: disinstalla l’app dal client Teams dell’utente, fai sign‑out/sign‑in, reinstalla la nuova versione.

Verifiche con PowerShell (facoltative)

Se gestisci a livello di tenant via PowerShell (module MicrosoftTeams):

# Verifica quale policy di permessi è assegnata all'utente
Get-CsOnlineUser -Identity user@contoso.com | Select DisplayName, TeamsAppPermissionPolicy

Elenca le policy disponibili e cerca la tua app

Get-CsTeamsAppPermissionPolicy | Select Identity, Description

Assegna una policy di permessi a un utente (se necessario)

Grant-CsTeamsAppPermissionPolicy -PolicyName "Contoso-Allow-DevApps" -Identity [user@contoso.com](mailto:user@contoso.com)

Verifica la policy di setup/pinning

Get-CsOnlineUser -Identity [user@contoso.com](mailto:user@contoso.com) | Select TeamsAppSetupPolicy

Nota: esegui i comandi con i permessi appropriati e dopo aver aggiornato il modulo MicrosoftTeams se richiesto.

Strategie di test per Message Extension

Query minime: usa una query “hello” o un action command che non tocchi API esterne per isolare il problema.
F12/Console: nel client desktop/web, verifica eventuali errori della Compose Extension nel pannello console.
Developer Portal: Test and distribute per side‑loading controllato dell’ultima build.
Log bot: assicurati che le richieste della ME arrivino al tuo endpoint (403/401 da API terze potrebbero mascherare la diagnosi).

Domande frequenti

Perché in locale funziona e nel tenant di sviluppo no?

In locale spesso testi con un profilo amministratore e con immagini di app lato client; in tenant, l’app passa attraverso controlli di Manage apps, Permission policies e canali del bot. Un incidente di servizio (come TM710191) può amplificare queste differenze.

Il messaggio “disabled by admin” è sempre colpa delle policy?

No. È un messaggio generico. Può dipendere da policy, da incongruenze del manifest.json, dal canale Teams del bot non abilitato o, talvolta, da problemi temporanei lato servizio.

Quanto tempo impiegano le modifiche a propagarsi?

Fino a 1 ora in media. Dopo modifiche significative, esegui sign‑out/sign‑in o ripulisci la cache per forzare il refresh del client.

Serve cambiare tenant o rifare la registrazione dell’app?

Di solito no. Mantieni costanti gli ID e verifica prima stato servizio, policy e canali. Riregistrare l’app con nuovi ID spesso complica approvazioni e distribuzione.

Quando contattare il supporto o la community

Se dopo le verifiche qui elencate il problema persiste, raccogli queste informazioni e apri un thread nel Teams Developer – Microsoft Community Hub o tramite i canali di supporto Microsoft:

Tenant ID e App ID dell’app Teams.
Timestamp e UTC dell’errore con correlationId se disponibile.
Conferma dello stato del canale Microsoft Teams nel bot.
Screenshot dello Status in Manage apps e della policy applicata agli utenti affetti.

Stato finale e raccomandazioni

Dopo la risoluzione dell’incidente TM710191, la Message Extension ha ripreso a funzionare correttamente nell’ambiente di sviluppo. Per prevenire ricadute e velocizzare futuri troubleshooting:

Automatizza un pre‑flight check post‑deploy: stato canali bot, validità endpoints, differenze di manifest.
Mantieni un ambiente di staging con policy identiche al prod per test realistici.
Documenta le policy (Permission/Setup) assegnate ai gruppi che usano l’app.
Prevedi un fallback negli handler della ME (messaggi d’errore chiari e istruzioni per l’utente finale).

Checklist finale stampabile

[ ] Service Health: nessun incidente aperto (TM710191 o simili) sul tenant.
[ ] Teams Admin Center → Manage apps: app Allowed a livello tenant.
[ ] Teams Admin Center → Permission policies: policy dell’utente consente l’app.
[ ] Teams Admin Center → Setup policies: pin/distribuzione coerenti (se usati).
[ ] Azure Bot: canale Microsoft Teams abilitato e Healthy.
[ ] Entra ID: Application ID combacia con botId del manifest; segreti/cert validi.
[ ] Manifest: validDomains, composeExtensions e version corretti.
[ ] Propagazione: attesa fino a 1 ora + sign‑out/sign‑in o pulizia cache.

Appendice: esempi di messaggi utili per l’utente finale

Se gestisci la UX della ME, mostra messaggi contestuali che riducano i ticket di supporto:

“Stiamo verificando le autorizzazioni dell’app nel tuo tenant. Se è un nuovo rilascio, potrebbe essere necessario attendere fino a 60 minuti per la propagazione.”
“Non riesci ancora a usare la funzione? Esci e rientra in Teams per aggiornare le policy assegnate.”

Conclusione

L’errore “The tenant admin disabled this bot” in una Message Extension di Microsoft Teams è spesso il risultato di un gate amministrativo legittimo (policy o approvazioni) o, come nel caso dell’incidente TM710191, di un evento di servizio temporaneo. Seguendo la checklist di questa guida e le verifiche consigliate in Teams Admin Center, Azure Bot e Entra ID, puoi distinguere rapidamente tra problema transitorio e configurazione da correggere, riducendo il tempo medio di ripristino e rendendo più robusto il tuo ciclo di rilascio.

Metadati