Twproject si integra con Microsoft Entra ID (ex Azure Active Directory) tramite il login OAuth2 incorporato nel prodotto: l’utente clicca un bottone, si autentica su Microsoft e Twproject lo riconosce dall’indirizzo email. Non serve installare moduli aggiuntivi né toccare Tomcat: la configurazione si fa dalla pagina di amministrazione di Twproject e da una registrazione applicativa su Entra ID.
La guida vale sia per le installazioni on-premise sia per le istanze cloud dedicate. Dove i passi sono diversi, è indicato.
Il meccanismo è un authorization code flow standard. Twproject rimanda l’utente all’endpoint di autorizzazione di Microsoft, riceve il codice sul proprio callback, lo scambia con un access token e interroga lo userinfo endpoint di Microsoft Graph. Dal risultato legge l’email e cerca l’operatore Twproject che ha quell’email come nome di accesso.
Cosa non c’è in questa versione, per evitare aspettative sbagliate:
- SAML 2.0: non è supportato. L’integrazione è OAuth2/OpenID Connect.
- Provisioning automatico: un utente che non esiste già in Twproject non viene creato al primo accesso.
- Sincronizzazione di gruppi e ruoli: aree, ruoli e assegnazioni restano gestiti dentro Twproject.
- SSO silenzioso: a ogni login Twproject chiede a Microsoft di riautenticare l’utente (
prompt=login).
Prerequisiti
Queste condizioni devono essere vere, altrimenti il bottone di login non compare o il login fallisce.
| Prerequisito | Cosa verificare | Dove |
|---|---|---|
| Licenza Enterprise | Il login OAuth2 è disponibile solo con licenza di livello Enterprise. Con una licenza inferiore la scheda non compare e il login non parte. | Amministrazione → Licenza |
| Installazione dedicata | Funziona sulle installazioni on-premise e sulle istanze cloud dedicate. Non è disponibile sul cloud condiviso. | Contratto |
| HTTPS e URL pubblico | Twproject deve essere raggiungibile in https e l’URL pubblico deve essere configurato correttamente: serve a costruire la redirect URI, che Microsoft accetta solo in https. Sulle istanze cloud dedicate è già configurato da Twproject. | Amministrazione → Impostazioni globali → Server config (solo on-premise) |
| Nome di accesso = email aziendale | Ogni persona che entrerà con Entra ID deve avere come nome di accesso esattamente l’indirizzo email che Microsoft restituisce (di norma la mail primaria). Il confronto ignora maiuscole e minuscole. | Scheda persona → Sicurezza/Login |
| Amministratore con email | Chi esegue la configurazione deve già avere come nome di accesso la propria email Entra: il test di attivazione verifica che l’utente restituito da Microsoft sia lui stesso, abilitato e amministratore. | Scheda persona → Sicurezza/Login |
URL pubblico (solo on-premise). In Amministrazione → Impostazioni globali → Server config i campi nome pubblico del server, porta HTTP esposta e protocollo http devono corrispondere all’indirizzo con cui gli utenti raggiungono Twproject. La riga di descrizione mostra l’URL completo che il server userà.
Nome di accesso. Il nome di accesso di ogni persona si vede e si cambia nella scheda Sicurezza/Login della risorsa, con il bottone Modifica il nome di accesso. Nell’esempio qui sotto il nome di accesso è user169 e andrebbe sostituito con l’email dell’utente. Per molti utenti conviene usare le API REST sull’oggetto person.
Un utente senza mailbox in Entra ID non ha il campo email nella risposta di Microsoft e il suo login fallisce anche se il nome di accesso è corretto.
Passo 1: registrare Twproject su Entra ID
Sul portale Microsoft Entra (Entra ID → Registrazioni app → Nuova registrazione) l’amministratore del tenant crea una registrazione con questi valori.
| Campo | Valore |
|---|---|
| Nome | Twproject (o un nome a scelta) |
| Tipi di account supportati | Solo gli account in questa directory organizzativa (tenant singolo) |
| Piattaforma | Web |
| URI di reindirizzamento | La redirect URI mostrata nella scheda OAUTH2 di Twproject (vedi passo 2), copiata esattamente. Ha la forma https://<host>/<contesto>/applications/teamwork/security/oauth/oauthLogin.jsp on-premise e https://<vostra-istanza>.twproject.cloud/applications/teamwork/security/oauth/oauthLogin.jsp sul cloud. |
| Certificati e segreti | Un nuovo segreto client. Copiare il valore subito: dopo non è più leggibile |
| Autorizzazioni API | Microsoft Graph, delegate: openid, profile, email. Concedere il consenso amministratore per il tenant |
Dalla pagina Panoramica della registrazione servono tre dati da passare a chi configura Twproject:
- ID applicazione (client): diventa il Client ID.
- ID directory (tenant): entra negli endpoint di autorizzazione e token.
- Valore del segreto client: diventa il Client secret.
Il segreto ha una scadenza, al massimo 24 mesi. Quando scade nessun utente riesce più a entrare: va segnato a calendario, rigenerato in anticipo e reinserito in Twproject.
Il consenso amministratore evita che ogni utente veda la schermata di consenso di Microsoft al primo accesso. Le policy del tenant (MFA, accesso condizionale) si applicano normalmente, perché l’autenticazione avviene sulle pagine di Microsoft.
Passo 2: configurare Twproject
Tutto si fa da Amministrazione → Sicurezza e autenticazione, da un utente amministratore il cui nome di accesso è già la sua email Entra.
2.1 Far comparire la scheda OAUTH2
La scheda OAUTH2 auth. è nascosta finché non si attiva la personalizzazione CUSTOM_FEATURE_OAUTH_ENABLED. Si trova in Amministrazione → Advanced customization, riga Enable OAUTH2: spuntare la casella, il valore si salva da solo.
Tornando in Sicurezza e autenticazione compare la scheda OAUTH2 auth. accanto a Standard auth. e LDAP/AD auth.
2.2 Compilare la scheda OAUTH2 auth.
Il combo Pre-fill data with OAUTH2 provider con la voce Microsoft compila gli endpoint dal documento di discovery di Microsoft. Usa il tenant common: conviene sostituirlo con il vostro ID directory, così Microsoft accetta solo il vostro tenant. Se dopo il pre-fill i campi restano vuoti, si compilano a mano con i valori qui sotto. On-premise succede quando la Content Security Policy di Twproject blocca la chiamata a login.microsoftonline.com.
| Campo | Valore da inserire |
|---|---|
| Provider ID | MICROSOFT (etichetta libera: compare sul bottone di login, “Autenticarsi con Microsoft”) |
| Token endpoint | https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token |
| Authorization endpoint | https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize |
| User info endpoint | https://graph.microsoft.com/oidc/userinfo |
| Scopes supported | openid profile email (togliere offline_access se il pre-fill lo aggiunge: non serve) |
| Client ID | ID applicazione (client) della registrazione |
| Client secret | Valore del segreto client |
In fondo alla scheda Twproject stampa la redirect URI esatta da registrare su Entra ID e ricorda che il login OAuth usa l’email come nome di accesso. L’avviso in rosso compare finché l’amministratore collegato non ha un’email come nome di accesso.
2.3 Testare e attivare
- Cliccare Test connection and save. Si apre un popup di Microsoft: l’amministratore si autentica con il proprio account Entra.
- Twproject verifica che l’email restituita da Microsoft corrisponda all’amministratore collegato, che sia abilitato e amministratore. Se il controllo passa, i parametri vengono salvati e compare il messaggio di conferma. Se fallisce, il messaggio dice quale email ha restituito Microsoft: è il valore che deve coincidere con il nome di accesso.
- Solo a test riuscito si sblocca Enable OAUTH2 authentication. Cliccandolo il tipo di autenticazione passa a OAuth2, con effetto immediato e senza riavvio.
Da questo momento la pagina di login mostra solo il bottone Microsoft. Prima del punto 3, tutti gli utenti devono avere il nome di accesso allineato all’email (vedi prerequisiti).
Come cambia il login per gli utenti
Oggi la pagina di login chiede nome di accesso e password in due passi.
Con OAuth2 attivo la pagina mostra solo l’invito ad autenticarsi con il provider e un bottone. Username e password spariscono per tutti.
Cosa succede quando l’utente clicca:
- Si apre un popup con la pagina di accesso di Microsoft. Un blocco popup aziendale sul browser impedisce il login: va consentito per l’indirizzo di Twproject.
- Microsoft chiede sempre le credenziali, perché Twproject manda
prompt=login. Le policy del tenant (MFA, accesso condizionale) valgono a ogni accesso. - Microsoft rimanda il browser sul callback di Twproject, che scambia il codice con un token e legge l’email dell’utente.
- Twproject cerca l’operatore con quel nome di accesso. Se esiste ed è abilitato, l’utente entra; se non esiste, vede un errore di login generico.
- Se Twproject ha l’OTP obbligatorio, il passo OTP resta e viene chiesto dopo l’autenticazione Microsoft.
Il cookie “ricordami” di Twproject, se abilitato nelle impostazioni di sicurezza, continua a funzionare: chi lo ha non ripassa da Microsoft a ogni apertura del browser, fino alla scadenza del cookie.
Le API REST con chiave APIKey e gli accessi MCP non cambiano: non passano dalla pagina di login.
Limiti e cose da sapere
- Tutto o niente. Con OAuth2 attivo nessuno entra con username e password. Consulenti esterni, fornitori o account tecnici senza identità Entra non possono più accedere all’interfaccia. Vanno censiti prima dell’attivazione.
- Niente provisioning. Gli utenti si creano in Twproject prima che possano entrare. Un nuovo assunto in Entra non compare da solo.
- Niente gruppi. Aree, ruoli e assegnazioni restano gestiti in Twproject. L’appartenenza ai gruppi Entra non è letta.
- Disattivazione in due posti. Disabilitare una persona in Entra ne blocca il login, ma l’operatore Twproject resta attivo (conta nelle licenze, riceve notifiche). Va disabilitato anche in Twproject.
- Scadenza del segreto. Alla scadenza del client secret il login si ferma per tutti. Serve un promemoria prima della scadenza.
- Popup. Il flusso usa una finestra popup. Il browser deve consentirla per l’indirizzo di Twproject.
- Nessun SSO silenzioso. Microsoft richiede le credenziali a ogni login. Il cookie “ricordami” di Twproject attenua la cosa.
- Segreto in chiaro (on-premise). Il client secret è salvato in chiaro nel file
commons/settings/global.propertiesdell’installazione. I permessi sul file vanno ristretti all’utente di Tomcat.
Ripristino d’emergenza
Se la configurazione si rompe (segreto scaduto, registrazione cancellata, amministratore senza email) e nessuno riesce più a entrare, non si può intervenire dall’interfaccia.
- On-premise: nel file
commons/settings/global.propertiessi impostaAUTHENTICATION_TYPE=ENABLE_STANDARD_AUTHENTICATIONe si riavvia Tomcat. Username e password tornano attivi. - Cloud: scrivete all’assistenza Twproject indicando l’indirizzo della vostra istanza. Ripristiniamo l’autenticazione standard con username e password, dopodiché potete correggere la configurazione e riattivare OAuth2.