Integrazione con Microsoft Teams

L’integrazione con Microsoft Teams invia le notifiche di Living Security a utenti e canali tramite l’app Teams di Living Security. Utilizzarla per le assegnazioni di formazione, gli avvisi sul rischio umano, i messaggi di rollout e gli annunci del team di sicurezza. Questa integrazione è destinata esclusivamente alle notifiche. Gli utenti non inviano comandi al bot in Microsoft Teams. Quando l’app viene installata, il bot memorizza il riferimento alla conversazione di Teams per le future notifiche proattive. I messaggi di installazione sono unidirezionali e possono essere personalizzati o disattivati in base ai requisiti di rollout aziendali.

Un amministratore di Microsoft Teams deve comunque caricare, approvare e distribuire l’app Teams di Living Security. Il consenso dell’amministratore di Microsoft Entra User.Read.All è facoltativo e abilita solo la ricerca di riserva tramite indirizzo email o user principal name (UPN).

Per la configurazione della distribuzione di Nudge e Playbook, iniziare da Impostazioni → Comunicazioni → Canali e fare clic sulla scheda Microsoft Teams. Questa pagina descrive la configurazione di base dell’app Teams.

Prerequisiti

Prima di configurare Microsoft Teams, assicurarsi di disporre di:

Un amministratore di Microsoft Teams in grado di caricare e approvare le app dell’organizzazione. La stessa persona può ricoprire entrambi i ruoli di amministratore.
Un amministratore di Microsoft Entra, solo se si desidera abilitare la ricerca di riserva facoltativa tramite email/UPN con il consenso dell’applicazione User.Read.All a livello di tenant
Privilegi di amministratore di Living Security
Un’organizzazione Living Security attiva
I nomi del team e del canale in cui devono essere recapitati gli annunci di sicurezza, se gli annunci nei canali sono abilitati
L’ID tenant di Microsoft Entra, disponibile in Microsoft Entra admin center → Identità → Panoramica

Chi fa cosa

Ruolo	Responsabilità
Amministratore di Living Security	Collega il tenant Microsoft, scarica il pacchetto regionale, configura i messaggi di installazione, convalida la configurazione e invia i test
Amministratore di Microsoft Teams	Carica e consente l’app, la distribuisce agli utenti o ai gruppi previsti e assegna i criteri di configurazione delle app
Amministratore di Microsoft Entra, facoltativo	Concede il consenso dell’applicazione `User.Read.All` all’ID app del bot regionale quando è necessaria la ricerca di riserva tramite email/UPN
Proprietario del team Teams, quando si utilizza la distribuzione nei canali	Installa o approva l’app per il team e il canale previsti

Possono essere persone diverse. Condividere con l’amministratore di Microsoft Teams il checksum del pacchetto, l’ID app di Teams, l’ID app del bot e la popolazione prevista per il rollout. Condividere l’URL di consenso generato con un amministratore di Microsoft Entra solo quando si abilita la ricerca di riserva facoltativa tramite email/UPN. Non condividere altre credenziali di Living Security non correlate.

Configurazione

Aprire il pannello di configurazione di Microsoft Teams

In Living Security, andare a Impostazioni → Comunicazioni → Canali e selezionare Microsoft Teams.Il pannello mostra la regione dell’organizzazione, il nome del file del pacchetto, l’ID app di Teams, l’ID app del bot, il checksum SHA256, lo stato della configurazione del tenant Microsoft, le istruzioni di installazione, i controlli dei messaggi di installazione, la convalida e gli strumenti per le notifiche di test.

La regione mostrata in Living Security corrisponde a quella in cui è ospitata l’organizzazione.

Collegare il tenant Microsoft

In Connect your tenant, inserire l’ID tenant di Microsoft Entra proprietario degli utenti e dei canali Teams che riceveranno le notifiche, quindi fare clic su Save Microsoft tenant. Un tenant Microsoft può appartenere a una sola organizzazione Living Security.Se il controllo del tenant non è disponibile, rivolgersi al responsabile dell’implementazione di Living Security o al contatto di supporto per collegare o modificare il tenant prima di installare l’app.

Living Security mostra Microsoft tenant connected prima di procedere.

Se possibile, collegare il tenant prima di installare l’app Teams. Se l’app è già installata, salvare il tenant e selezionare prima Validate install. Living Security tenta di associare automaticamente l’installazione esistente; reinstallare l’app solo se la convalida non riesce a rilevarla.

Scaricare il pacchetto Teams regionale

Fare clic su Download Teams package. Living Security fornisce un pacchetto ZIP specifico per la regione della propria organizzazione.Prima di apportare qualsiasi modifica, verificare il file scaricato confrontandolo con il checksum SHA256 mostrato in Living Security. Per assegnare all’app un nome e icone personalizzati, seguire la sezione Personalizzare il marchio del pacchetto regionale dopo questa verifica e prima di caricare il pacchetto.

Il checksum del file scaricato corrisponde al checksum SHA256 mostrato in Living Security.

Caricare e installare il pacchetto in Teams admin center

In Microsoft Teams admin center, andare a Teams apps → Manage apps → Actions → Upload new app, quindi caricare il file ZIP scaricato da Living Security.Verificare che:

L’ID app di Teams e l’ID app del bot corrispondano ai valori mostrati in Living Security
Il nome dell’app sia il nome regionale di Living Security oppure il nome impostato in caso di personalizzazione del pacchetto
L’editore sia Living Security. La personalizzazione del marchio del pacchetto non modifica l’editore
L’app sia sbloccata
L’app sia disponibile per gli utenti o i gruppi previsti
L’app sia installata tramite criteri di configurazione delle app o installazione mirata per gli utenti e i team/canali che devono ricevere le notifiche

Microsoft può impiegare del tempo per propagare la disponibilità dell’app e le modifiche ai criteri di configurazione.

Se la convalida o un test non riesce subito dopo una modifica ai criteri dell’app, verificare l’assegnazione del criterio in Microsoft Teams admin center e riprovare al termine della propagazione da parte di Microsoft.

Installare o aprire l'app

Distribuire l’app personale agli utenti previsti. Affinché Living Security possa inviare un test personale a un’installazione rilevata, almeno un utente deve installare o aprire l’app personale di Living Security in Microsoft Teams. In questo modo il bot può acquisire l’identità attendibile dell’utente e il riferimento alla conversazione personale. La sola installazione in un canale non può essere utilizzata per un test personale su un’installazione rilevata.Per la distribuzione nei canali, installare l’app nel team e nel canale previsti in modo che il bot possa acquisire il riferimento alla conversazione di quel canale.

Un utente di destinazione ha installato o aperto l’app personale, oppure l’app è installata nel canale previsto.

Configurare i messaggi di installazione

Nella sezione Install message controls, scegliere se inviare i messaggi di installazione di Teams e personalizzare il testo unidirezionale per la propria organizzazione.Controlli disponibili:

Send install messages
Send personal install messages
Send channel install messages
Default message
Personal message
Channel message

I campi dei messaggi supportano {{installerName}}, che viene sostituito con il nome visualizzato dell’utente che ha installato l’app. Lasciare vuoto un messaggio personale o di canale per utilizzare il messaggio predefinito configurato. Se anche il messaggio predefinito è vuoto, Living Security utilizza il messaggio integrato per quell’ambito.

Convalidare la configurazione

Fare clic su Validate install in Living Security. La convalida verifica che il pacchetto regionale sia disponibile, che la configurazione del tenant Microsoft sia presente e univoca per questa organizzazione Living Security, che le credenziali del bot regionale siano configurate e che sia stata rilevata un’installazione attiva dell’app per il tenant collegato.

La convalida mostra Validation passed prima di inviare notifiche reali.

Inviare le notifiche di test

Per il test personale predefinito, fare clic su Send test to detected installation. Living Security seleziona un’installazione personale attiva rilevata e utilizza la relativa identità attendibile memorizzata e il riferimento alla conversazione. Questo test non richiama Microsoft Graph e non richiede il consenso User.Read.All.Se non viene rilevata alcuna installazione personale, chiedere a un utente di installare o aprire l’app personale di Living Security, selezionare di nuovo Validate install e poi inviare nuovamente il test. Utilizzare il test avanzato mirato tramite email/UPN solo quando la ricerca di riserva facoltativa è abilitata.

La notifica di test unidirezionale compare in Microsoft Teams.

Quando sono necessari dati diagnostici sul recapito, consultare il tentativo corrispondente nel Registro delle comunicazioni.

Personalizzare il marchio del pacchetto regionale

Il pacchetto regionale è un archivio ZIP composto da tre file: manifest.json, color.png e outline.png. È possibile impostare un nome e icone personalizzati dell’app in tale pacchetto prima di caricarlo. Living Security supporta questa procedura per i pacchetti regionali che un amministratore di Teams carica direttamente. Eseguire questa operazione dopo aver scaricato e verificato il pacchetto e prima di caricarlo in Teams admin center.

Decomprimere il pacchetto

Estrarre il file ZIP. Contiene esattamente tre file nella radice dell’archivio: manifest.json, color.png e outline.png.

Sostituire le icone

Sostituire color.png e outline.png con le proprie icone. Mantenere gli stessi due nomi di file.

File	Requisito
`color.png`	PNG a colori, 192 × 192 pixel, senza trasparenza
`outline.png`	PNG trasparente, 32 × 32 pixel

Impostare il nome dell'app

In manifest.json, modificare questi due campi:

name.short: il nome mostrato nell’intestazione dell’app Teams e in altre aree con spazio limitato. Massimo 30 caratteri.
name.full: il nome mostrato nel catalogo delle app e nei dettagli dell’app. Massimo 100 caratteri.
Se un’app Living Security è già stata caricata in Teams admin center, impostare version su un valore superiore alla versione ivi installata. Microsoft Teams rifiuta un aggiornamento che non incrementa la versione, e un nuovo download può avere la stessa versione, o una versione inferiore, rispetto al pacchetto già installato.Leggere la versione installata in Teams admin center, in Teams apps → Manage apps, nella pagina dei dettagli dell’app. Confrontarla con il valore version nel file manifest.json appena scaricato, quindi impostare un valore superiore a entrambi. Mantenere il formato MAJOR.MINOR.PATCH a tre numeri.Ad esempio, se l’app installata è 1.1.1 e il nuovo download è 1.1.0, impostare 1.1.2. Portare il valore 1.1.0 scaricato a 1.1.1 ripeterebbe la versione installata e Teams rifiuterebbe il caricamento.

Lasciare invariati i campi di identità

Non modificare questi campi. Ciascuno di essi contiene l’identità dell’app, del bot o del single sign-on:

id
botId in bots
webApplicationInfo
validDomains
contentUrl e websiteUrl in staticTabs
La modifica di un campo di identità può lasciare l’app installabile ma incapace di recapitare le notifiche o di completare il single sign-on. Validate install verifica il tenant, le credenziali del bot e l’installazione rilevata. Non confronta il manifest con il pacchetto creato da Living Security.

Ricomprimere i tre file

Creare un nuovo archivio ZIP con i tre file. Collocarli nella radice dell’archivio, senza alcuna cartella contenitore. Microsoft Teams rifiuta un pacchetto in cui manifest.json si trovi all’interno di una cartella.

Caricare e verificare

Caricare il file ZIP con il marchio personalizzato in Teams admin center, quindi tornare a Living Security e fare clic su Validate install. Inviare una notifica di test.

La convalida mostra Validation passed e la notifica di test arriva in Microsoft Teams con il nome e le icone personalizzati dell’app.

Editore e checksum

La personalizzazione del marchio imposta il nome e le icone dell’app. Non modifica due aspetti:

L’editore rimane Living Security. I campi developer del manifest indicano Living Security e rimandano al sito web, all’informativa sulla privacy e ai termini di servizio di Living Security. Insieme identificano l’azienda che gestisce il servizio, pertanto Teams continua a mostrare Living Security come editore nella pagina dei dettagli dell’app, nelle finestre di consenso alle autorizzazioni e nei report sull’utilizzo delle app. Il nome e le icone personalizzati sono ciò che gli utenti vedono nell’intestazione dell’app, nel catalogo delle app e nelle notifiche.
Il checksum SHA256 non corrisponde più. Il checksum mostrato in Living Security descrive il pacchetto così come è stato scaricato. Verificarlo prima di modificare i file, quindi registrare il checksum del proprio pacchetto personalizzato nella documentazione del rollout.

Facoltativo: abilitare la ricerca di riserva tramite email/UPN

La normale distribuzione personale utilizza un object ID di Microsoft Entra attendibile già noto a Living Security insieme al riferimento alla conversazione del bot acquisito quando l’utente installa o apre l’app. La distribuzione nei canali utilizza il riferimento memorizzato della conversazione del canale. Nessuno dei due percorsi richiede Microsoft Graph. Se un destinatario non dispone di un object ID Entra attendibile, Living Security può facoltativamente utilizzare Microsoft Graph per individuare il destinatario tramite indirizzo email o UPN. Per abilitare questa ricerca di riserva, chiedere a un amministratore di Microsoft Entra di fare clic su Grant optional User.Read.All consent nel pannello di configurazione di Teams e di approvare l’autorizzazione dell’applicazione Microsoft Graph User.Read.All per l’applicazione Teams regionale di Living Security. Il flusso di consenso dell’amministratore segue questo schema di Microsoft Entra:

https://login.microsoftonline.com/{tenant-id}/adminconsent?client_id={bot-app-id}

Living Security genera questo URL a partire dall’ID tenant collegato e dall’ID app del bot mostrato nel pannello di configurazione. Gli ID hanno scopi diversi:

L’ID app di Teams identifica il pacchetto dell’app installabile in Microsoft Teams admin center.
L’ID app del bot identifica l’applicazione Microsoft Entra del bot regionale ed è l’ID client utilizzato per il flusso facoltativo di consenso dell’amministratore.

Non sostituire l’ID app di Teams nell’URL di consenso. L’integrazione Microsoft Entra ID (Client Credentials) in Connected Integrations è un’integrazione separata e generica. Le sue credenziali o il suo consenso non possono essere riutilizzati dal bot Teams regionale, e il consenso concesso a un’applicazione Entra non correlata non abilita questa ricerca di riserva.

Rendere facoltativo il consenso non rimuove User.Read.All dalle registrazioni esistenti dell’applicazione regionale Living Security. I clienti che hanno già concesso il consenso possono continuare a usare la ricerca di riserva tramite email/UPN senza riconfigurazione.

Tipi di notifica

In base ai diritti dell’organizzazione e ai Playbook configurati, Living Security può inviare:

Notifica	Descrizione
Assegnazioni di formazione	Avvisano gli utenti quando una formazione viene assegnata, è in scadenza o è pronta per essere completata
Promemoria di formazione	Ricordano agli utenti le scadenze imminenti
Avvisi sul rischio umano	Inviano aggiornamenti personalizzati dell’Indice di rischio umano e i passaggi successivi consigliati
Messaggi di rollout	Inviano notifiche unidirezionali di onboarding o rollout durante la distribuzione
Annunci nei canali	Pubblicano le comunicazioni del programma di sicurezza nei canali Teams configurati

Personalizzazione

Le notifiche di Teams utilizzano la configurazione dell’organizzazione Living Security. I campi supportati includono il nome visualizzato del cliente, il logo supportato e i campi del marchio, il testo dei messaggi, gli inviti all’azione, i link di destinazione, il testo del rollout e il testo di supporto/contatto. I messaggi di installazione sono configurabili da Impostazioni → Comunicazioni → Canali → Microsoft Teams → Install message controls. È possibile disattivare completamente i messaggi di installazione, disattivare solo quelli personali o di canale e configurare testi predefiniti, personali o specifici per il canale. Il nome e le icone dell’app Teams provengono dal pacchetto regionale. Per impostare valori personalizzati, vedere Personalizzare il marchio del pacchetto regionale.

Aggiornamento o rimozione dell’app

Quando Living Security fornisce un pacchetto regionale aggiornato, scaricarlo dal pannello del canale Microsoft Teams e caricarlo tramite Teams admin center. Verificare l’ID app, l’ID del bot e il checksum visualizzati prima del rollout.
Le modifiche al marchio non sopravvivono a un aggiornamento del pacchetto. Ogni nuovo pacchetto regionale contiene di nuovo il nome e le icone dell’app Living Security. Riapplicare le modifiche con Personalizzare il marchio del pacchetto regionale prima di caricare il nuovo pacchetto. Conservare in un luogo facilmente reperibile le proprie icone, i due valori del nome e l’ultima versione caricata, in modo che ogni aggiornamento sia una breve ripetizione degli stessi passaggi. Un nuovo pacchetto non ha sempre una versione superiore a quella installata, quindi impostare la versione in base a quanto Teams mostra come installato.
Eseguire di nuovo Validate install e inviare un altro test dopo un aggiornamento dell’app o dei criteri.
La rimozione o il blocco dell’app impedisce le notifiche proattive a quell’utente o canale. Reinstallare l’app e inviare un nuovo test affinché Living Security riceva un evento di installazione di Teams aggiornato.
Se si interrompe la distribuzione tramite Teams, rimuovere Teams dai Playbook pertinenti prima di rimuovere l’app da Microsoft Teams.

Risoluzione dei problemi

Un utente non riceve una notifica personale

Verificare che l’app personale Teams di Living Security sia installata e che l’utente l’abbia aperta, in modo che Living Security disponga di un riferimento alla conversazione aggiornato
Verificare che l’ID tenant Microsoft configurato sia quello del tenant in cui si trova l’utente
Se la diagnostica mostra che è stata tentata la ricerca di riserva tramite email/UPN, verificare che il consenso dell’amministratore User.Read.All sia stato concesso all’ID app del bot visualizzato per il tenant corretto
Quando viene utilizzata la ricerca di riserva tramite email/UPN, verificare che l’email o l’UPN dell’utente in Living Security corrisponda a quello in Microsoft Entra ID
Chiedere all’utente di sbloccare o reinstallare l’app se in precedenza l’ha rimossa o bloccata

Un annuncio nel canale non compare

Verificare che l’app Teams di Living Security sia installata nel team o nel canale di destinazione.
Verificare che la mappatura del canale in Living Security utilizzi il team e il canale corretti.
Verificare se il canale è stato rimosso, rinominato, archiviato o limitato.
Reinstallare l’app nel team o nel canale di destinazione e inviare un’altra notifica di test.

La ricerca facoltativa tramite email/UPN o il consenso non riesce

Verificare che un amministratore di Microsoft Entra abbia concesso il consenso a livello di tenant per Microsoft Graph User.Read.All all’ID app del bot visualizzato.
Verificare che l’ID tenant configurato sia quello del tenant in cui si trovano gli utenti e Teams.
Verificare che l’utente esista in Microsoft Entra ID e non sia un guest di un altro tenant.

Il Registro delle comunicazioni mostra che è richiesto il consenso dell'amministratore Microsoft

La categoria di errore TEAMS_ADMIN_CONSENT_REQUIRED, o l’errore Microsoft AADSTS7000229, indica che una ricerca del destinatario tramite email/UPN ha tentato la ricerca di riserva facoltativa con Microsoft Graph, ma l’app Teams regionale di Living Security non ha alcun service principal (applicazione aziendale) nel tenant Microsoft Entra collegato. I percorsi predefiniti basati su ID attendibile e conversazione memorizzata non richiedono questo consenso. Non si tratta di un secret di Living Security scaduto.

Aprire Impostazioni → Comunicazioni → Canali → Microsoft Teams. È possibile utilizzare anche Open Microsoft Teams setup dall’errore nel Registro delle comunicazioni.
Verificare che sia collegato l’ID tenant di Microsoft Entra corretto.
Se è necessaria la ricerca di riserva tramite email/UPN, chiedere a un amministratore di Microsoft Entra di fare clic su Grant optional User.Read.All consent e di approvare User.Read.All per l’ID app del bot visualizzato. In caso contrario, assicurarsi che il destinatario abbia aperto l’app personale e che Living Security disponga del suo object ID Entra attendibile.
Dopo che Microsoft ha terminato di elaborare il consenso, inviare un test avanzato mirato tramite email/UPN dalla configurazione di Microsoft Teams. Il Registro delle comunicazioni mostra la cronologia di recapito e la diagnostica; non recapita nuovamente il messaggio non riuscito.

La riconfigurazione di Microsoft Entra ID (Client Credentials) non risolve questo errore perché tale integrazione non viene utilizzata per il recapito delle notifiche di Teams.

L'app è installata ma le notifiche non vengono recapitate

Verificare se il bot è stato bloccato, rimosso o disinstallato
Se l’app è stata installata prima che il tenant fosse collegato in Living Security, salvare il tenant e selezionare Validate install in modo che Living Security possa associare l’installazione esistente
Reinstallare l’app solo se la convalida non riesce a rilevare l’installazione esistente
Verificare che l’utente o il canale di destinazione abbia ricevuto l’ultimo evento di installazione dell’app
Inviare una nuova notifica di test dopo aver reinstallato l’app

Esempio di campi dell’evento di installazione utilizzati per la risoluzione dei problemi:

{
  "type": "installationUpdate",
  "action": "add",
  "channelData": {
    "tenant": { "id": "278750d2-8df7-4262-a34d-08d79ad671d8" },
    "team": { "id": "19:team-id@thread.tacv2" },
    "channel": { "id": "19:channel-id@thread.tacv2" }
  },
  "conversation": {
    "id": "19:channel-id@thread.tacv2",
    "conversationType": "channel",
    "tenantId": "278750d2-8df7-4262-a34d-08d79ad671d8"
  }
}

Sicurezza

Living Security utilizza Microsoft Graph User.Read.All solo per la ricerca di riserva facoltativa del destinatario tramite email/UPN. Per impostazione predefinita, l’instradamento delle notifiche personali utilizza un object ID Entra attendibile proveniente dai dati delle entità di Living Security e il riferimento alla conversazione del bot acquisito da Microsoft Teams. Gli object ID e i riferimenti alla conversazione forniti dal chiamante non sono considerati dati di instradamento attendibili. I messaggi di Microsoft Teams vengono recapitati tramite il bot Teams di Living Security dedicato esclusivamente alle notifiche, utilizzando la messaggistica proattiva di Microsoft Teams. Living Security non richiede ai clienti di creare una propria registrazione di applicazione Microsoft Entra né di condividere un client secret di proprietà del cliente per la configurazione standard dell’app Teams. I pacchetti Teams specifici per regione mantengono l’ID app, l’ID del bot e l’endpoint di messaggistica allineati alla regione di Living Security in cui è ospitata l’organizzazione.

Argomenti correlati

Integrazione email

Configurare l’email come canale di recapito.

Integrazione con Slack

Configurare Slack come canale di recapito.

Registro delle comunicazioni

Monitorare lo stato e la cronologia di recapito di Teams.

Autenticazione

Configurazione di Microsoft Entra ID e SSO.

Integrazioni

Configurazione delle integrazioni

Catalogo

Canali in uscita

Prerequisiti

Chi fa cosa

Configurazione

Personalizzare il marchio del pacchetto regionale

Editore e checksum

Facoltativo: abilitare la ricerca di riserva tramite email/UPN

Tipi di notifica

Personalizzazione

Aggiornamento o rimozione dell’app

Risoluzione dei problemi

Sicurezza

Argomenti correlati

Integrazione email

Integrazione con Slack

Registro delle comunicazioni

Autenticazione

Integrazioni

Configurazione delle integrazioni

Catalogo

Canali in uscita

​Prerequisiti

​Chi fa cosa

​Configurazione

​Personalizzare il marchio del pacchetto regionale

​Editore e checksum

​Facoltativo: abilitare la ricerca di riserva tramite email/UPN

​Tipi di notifica

​Personalizzazione

​Aggiornamento o rimozione dell’app

​Risoluzione dei problemi

​Sicurezza

​Argomenti correlati

Integrazione email

Integrazione con Slack

Registro delle comunicazioni

Autenticazione

Prerequisiti

Chi fa cosa

Configurazione

Personalizzare il marchio del pacchetto regionale

Editore e checksum

Facoltativo: abilitare la ricerca di riserva tramite email/UPN

Tipi di notifica

Personalizzazione

Aggiornamento o rimozione dell’app

Risoluzione dei problemi

Sicurezza

Argomenti correlati