Collega Microsoft e Google

Come funziona una connessione

• Provider e modalità. provider è microsoft o google. mode è own_app, la tua app Microsoft Entra o il tuo account di servizio Google, oppure screenrig_app, l’app di screenRIG, che approva un amministratore di Microsoft 365 o il titolare di un account Google.
• Stato. Una connessione resta in pending_consent finché qualcuno non approva l’app di screenRIG. È ready finché ha credenziali che l’ultimo tentativo non ha rifiutato, ed error quando Microsoft o Google le hanno rifiutate: last_error ne dice il motivo, e un successo successivo la riporta a ready. Una limitazione o un’interruzione non cambia nulla.
• I segreti restano sigillati. Un segreto, una chiave o un token di aggiornamento non viene mai più mostrato. Una lettura indica se ne è conservato uno e dà un suggerimento: gli ultimi quattro caratteri di un segreto client Microsoft, o l’indirizzo di un account di servizio Google.
• Provala. Un test accede e conserva il risultato. Per Microsoft elenca anche le autorizzazioni dell’applicazione Graph che il token ottenuto porta.
• Modificala. Modificare le credenziali della tua app riporta la connessione a ready e cancella il suo ultimo errore. Una connessione in modalità app di screenRIG può solo essere rinominata: chiedi un nuovo link di consenso per cambiare chi l’ha approvata.
• Eliminala. L’eliminazione viene rifiutata (resource_conflict) finché un’origine, una connessione Power BI o un account di sincronizzazione dei media legge tramite la connessione. Non chiude il lato del fornitore: il tenant conserva l’app di screenRIG finché un amministratore non la rimuove, e un account Google conserva la sua concessione finché il titolare non la revoca.
• Limite. Un’organizzazione ha fino a 50 connessioni su tutti i suoi progetti.

La tua app o quella di screenRIG

Microsoft

La tua app

Registra un’app nell’interfaccia di amministrazione di Microsoft Entra, aggiungi un segreto client (copia il suo valore, non il suo ID), dai all’app le autorizzazioni dell’applicazione indicate sotto e concedi il consenso dell’amministratore. Crea la connessione con l’ID della directory o il dominio principale come config.tenant_id (common, organizations e consumers vengono rifiutati), l’ID dell’applicazione come config.client_id e il valore del segreto client come secret.

L’app di screenRIG, con il consenso dell’amministratore

Crea la connessione in modalità screenrig_app, senza impostazioni e senza segreto. La risposta contiene consent_url, un link monouso valido per 24 ore. Invialo a un amministratore di Microsoft 365 e a nessun altro: è la credenziale di quel solo consenso.

1. L’amministratore apre il link e approva l’app di screenRIG per il tenant.
2. Microsoft torna a screenRIG, che chiede all’amministratore di accedere a quel tenant. La connessione registra il tenant in cui è avvenuto l’accesso, mai uno che una richiesta si limita a dichiarare.
3. screenRIG accede una volta al tenant con l’autorizzazione ricevuta. La connessione diventa ready.

Un link funziona una sola volta. Un link più recente, un consenso concluso o un’eliminazione chiude uno più vecchio, e puoi chiedere un nuovo link in qualsiasi momento: per rinnovare una connessione passata a error, o per collegare un altro tenant. Se l’amministratore rifiuta o l’accesso non si completa, la connessione registra consent_denied o consent_failed (con il codice AADSTS di Microsoft) e mantiene il consenso in sospeso, così lo stesso link può essere riaperto. Una connessione che già funziona non viene mai degradata da un secondo consenso rifiutato. Se il tenant rimuove l’app di screenRIG, la connessione indica consent_revoked: chiedi a un amministratore di approvare di nuovo.

L’approvazione vale per tenant. Una volta che un amministratore ha approvato l’app di screenRIG, chiunque possa accedere al tenant può collegarlo a un progetto proprio, quindi restringi ciò che l’app può leggere, come sotto. Eliminare l’applicazione aziendale in Microsoft Entra chiude l’accesso di tutti i progetti.

Cosa può leggere l’app

Un test della connessione elenca quali di queste autorizzazioni il token porta. Avvisa quando è presente solo Sites.Selected, perché ogni sito ha ancora bisogno della sua concessione, e fallisce quando non ne è presente nessuna.

Google

La tua app

Crea un account di servizio in Google Cloud, abilita l’API di Google Calendar e scarica la sua chiave JSON (al massimo 16 KiB). Dai alla connessione l’intero file come secret: screenRIG lo controlla al salvataggio. Poi condividi ogni calendario di sala con l’indirizzo dell’account di servizio, oppure attiva la delega a livello di dominio per l’account nella console di amministrazione con l’ambito https://www.googleapis.com/auth/calendar.events.readonly e indica un subject sull’origine.

L’app di screenRIG

Il link di consenso apre la pagina di consenso di Google. Il titolare dell’account concede l’accesso in sola lettura agli eventi del calendario (l’ambito calendar.events.readonly, con openid e email perché screenRIG sappia quale account ha approvato). Se la persona deseleziona l’autorizzazione del calendario, il consenso fallisce. Un’origine legge i calendari che quell’account può vedere, quindi l’account deve vedere ogni calendario di sala che l’origine elenca, e un’origine di una tale connessione non può indicare un subject. Quando Google smette di riconoscere la concessione, la connessione indica reconnect_required: chiedi un nuovo link.

Usare una connessione

• Origini delle sale riunioni. Imposta connection_id su un’origine microsoft365 o google_calendar al posto di tenant, client_id e client_secret, oppure di service_account_key. Funzionano entrambe le modalità. Le credenziali inline continuano a funzionare, ma non si possono mescolare con connection_id.
• Sincronizzazione dei media di SharePoint e OneDrive. Un account di sincronizzazione Microsoft 365 accetta connection_id al posto di tenant_id, client_id e secret.
• Power BI. Una connessione Power BI accetta il connection_id di una connessione Microsoft in modalità own_app, al posto di tenant, ID client e segreto propri. Microsoft non descrive un’app di un altro tenant che genera token di incorporamento nel tenant di un cliente, quindi l’app di screenRIG viene rifiutata per Power BI. Un amministratore di Power BI deve comunque attivare le impostazioni dell’entità servizio e aggiungere l’app a ogni area di lavoro.

Un’origine la cui connessione manca, è in attesa di approvazione o è dell’altro provider indica config_invalid. Quando Microsoft o Google rifiuta l’accesso, l’origine indica auth_failed e la connessione passa a error.

Crearne una

Crea una connessione nella dashboard o con POST /api/connections. Per la tua app Microsoft:

{
  "provider": "microsoft",
  "mode": "own_app",
  "name": "Contoso rooms",
  "config": {"tenant_id": "contoso.com", "client_id": "CLIENT_ID"},
  "secret": "CLIENT_SECRET_VALUE"
}

Per l’app di screenRIG, senza impostazioni e senza segreto:

{"provider": "google", "mode": "screenrig_app", "name": "Campus rooms"}

La risposta alla seconda contiene consent_url e consent_expires_at: invia il link alla persona che approva. POST /api/connections/ID/connect crea un nuovo link, e POST /api/connections/ID/test accede e conserva il risultato. Tieni i segreti nel file della richiesta, non nella riga di comando.

connection_app_not_configured significa che il server non ha un’app di screenRIG per quel provider: crea la connessione con la tua app. connection_limit_reached significa che l’organizzazione ne ha 50: elimina una che nessuno legge, o riutilizza una connessione esistente.

Correlato

• Origini dati: le origini delle sale che usano una connessione.
• Riferimento API: ogni route delle connessioni.
• Single sign-on: come accedono le persone. Una connessione serve al lavoro che gira senza nessuno connesso.