Configurazione di Confluence Cloud

Anteprima pubblica: la ricerca federata è in anteprima pubblica. Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Questa pagina descrive come configurare l'istanza Confluence Cloud prima di creare il datastore Confluence Cloud.

Configurare l'autenticazione e le autorizzazioni

Devi configurare l'autenticazione e le autorizzazioni nel centro di amministrazione Atlassian. Questo è fondamentale per consentire al connettore di accedere ai dati e sincronizzarli. Il connettore Confluence Cloud supporta vari metodi di autenticazione, ad esempio le credenziali client OAuth o i token API.

Crea un'app OAuth 2.0

Per creare un'app OAuth 2.0 per l'autenticazione, segui questi passaggi per configurare l'applicazione in Atlassian Developer Console e ottenere l'ID client e il client secret necessari.

Verificare l'accesso di amministratore dell'organizzazione Confluence

Per verificare l'accesso di amministratore dell'organizzazione Confluence:

1. Accedi ad Atlassian con le tue credenziali utente.

2. Seleziona l'app Confluence.

3. Fai clic su Impostazioni.

   Se vedi l'opzione System (Sistema) in Confluence settings (Impostazioni di Confluence), hai accesso come amministratore dell'organizzazione Confluence. In caso contrario, chiedi all'amministratore dell'organizzazione Confluence di fornire l'accesso.

Crea un'app OAuth 2.0

Per creare un'app OAuth 2.0:

1. Accedi all'Atlassian Developer Console.

2. Fai clic sull'icona del profilo e seleziona Developer console (Console per gli sviluppatori).

3. Nella pagina Console, fai clic su Crea e seleziona Integrazione OAuth 2.0.

4. Nella pagina di creazione dell'app:

   1. Inserisci un nome per l'app.

   2. Seleziona la casella di controllo per accettare i termini per gli sviluppatori di Atlassian.

   3. Fai clic su Crea.

5. Nella pagina dell'app:

   1. Nel menu di navigazione, fai clic su Autorizzazione.

   2. Nella tabella Authorization type (Tipo di autorizzazione), seleziona Add (Aggiungi) per OAuth 2.0 (3LO).

6. Nel campo Callback URL (URL di callback), inserisci https://vertexaisearch.cloud.google.com/console/oauth/confluence_oauth.html.

7. Fai clic su Salva modifiche.

Ottieni l'ID client e il client secret

Per ottenere l'ID client e il client secret:

1. Nella pagina dell'app, fai clic su Distribuzione nel menu di navigazione.

2. Nella pagina Distribuzione, segui questi passaggi:

   1. Nella sezione Controlli di distribuzione, seleziona Modifica.
   2. Nella sezione Stato della distribuzione, seleziona Condivisione per attivare la modifica di altri campi.
   3. Compila i seguenti campi obbligatori con le informazioni richieste:
      1. In Vendor (Fornitore), inserisci Google.
      2. In Privacy policy (Norme sulla privacy), inserisci https://policies.google.com.
      3. Per Does your app store personal data? (La tua app memorizza dati personali?), seleziona Yes (Sì).
      4. Seleziona la casella di controllo I confirm that I've implemented the personal data reporting API (Confermo di aver implementato l'API per la generazione di report sui dati personali).
   4. Fai clic su Salva modifiche.

3. Nella pagina dell'app:

   1. Nel menu di navigazione, fai clic su Impostazioni.
   2. Nella pagina delle impostazioni, copia l'ID client e il client secret.

Ottenere un ID istanza e un URL istanza

1. Ottieni l'ID istanza:

   1. Apri una nuova scheda, copia l'URL dell'istanza e aggiungi /_edge/tenant_info all'URL dell'istanza. Ad esempio, https://YOUR_INSTANCE.atlassian.net/_edge/tenant_info.
   2. Vai al link per trovare il valore di cloudId. cloudId è l'ID istanza.

2. Ottieni l'URL dell'istanza:

   1. Vai su atlassian.net e accedi con il tuo account amministratore.
   2. Seleziona l'app che desideri sincronizzare. Ad esempio, sincronizza la prima app.
   3. Trova l'URL dell'istanza (il sottodominio nella barra degli indirizzi).

Concedi ruoli di amministratore

Per concedere all'amministratore Confluence il ruolo Discovery Engine Editor nella console Google Cloud , procedi nel seguente modo:

1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

2. Vai a IAM.

   Vai a IAM

3. Individua l'account utente con accesso amministratore in Confluence e fai clic sull'icona Modifica .

4. Concedi all'amministratore il ruolo Discovery Engine Editor.

Per concedere a un utente un ruolo di amministratore in Atlassian:

1. Accedi ad Atlassian utilizzando un account amministratore.

2. Fai clic sull'icona del menu e seleziona la tua organizzazione. In alternativa, puoi andare ad admin.atlassian.com.

3. Nella pagina Admin (Amministrazione), fai clic sul prodotto e seleziona il pulsante Manage users (Gestisci utenti).

4. Fai clic su Groups (Gruppi) in Manage users (Gestione utenti).

5. Nella pagina Groups (Gruppi):

   1. Fai clic su Crea gruppo.
   2. Inserisci un nome per il gruppo.

Questo gruppo riceve le autorizzazioni richieste dal connettore. Gli utenti aggiunti a questo gruppo ereditano queste autorizzazioni. Il connettore utilizza questo gruppo per autenticarsi e recuperare i documenti.

1. Nella pagina del gruppo, fai clic su Aggiungi prodotto.

2. Seleziona User access admin (Amministratore accesso utente) come ruolo per Confluence.

3. Seleziona Product admin (Amministratore prodotto) come ruolo per Confluence administration (Amministrazione Confluence).

4. Fai clic su Concedi l'accesso.

5. Fai clic su Add group members (Aggiungi membri del gruppo) per aggiungere un account utente o membri del gruppo che il connettore utilizza per l'autenticazione e l'accesso alle risorse richieste.

Configura gli ambiti minimi dell'applicazione

Per configurare OAuth 2.0 e recuperare le credenziali richieste per la configurazione del connettore Confluence, procedi nel seguente modo:

1. Abilita OAuth 2.0:
   1. Fai clic su Autorizzazioni.
   2. Vai all'API Confluence.
   3. Fai clic su Aggiungi.
   4. Fai clic su Configura.
   5. Vai alla scheda Granular scopes (Ambiti granulari) e fai clic su Edit Scopes (Modifica ambiti).
   6. Seleziona i seguenti ambiti.
      • read:attachment:confluence
      • read:configuration:confluence
      • read:content.metadata:confluence
      • read:content-details:confluence
      • read:whiteboard:confluence
      • read:group:confluence
      • read:space:confluence
      • read:user:confluence
      • search:confluence
      • write:page:confluence
      • write:attachment:confluence
   7. Conferma che tutti gli ambiti siano selezionati e salva le modifiche.

Configura un token API in Confluence

Se prevedi di utilizzare un token API per l'autenticazione, devi creare un token API senza ambiti. Questo connettore non supporta i token API con ambiti.

1. Accedi alla Console Atlassian.
2. Fai clic su Genera token API.
3. Inserisci un nome per il token API.
4. Seleziona una data di scadenza per il token API. Il periodo di scadenza del token varia da 1 a 365 giorni.
5. Fai clic su Crea.
6. Salva il token per utilizzarlo in un secondo momento.

Gestisci la visibilità degli utenti

Per rendere l'email dell'utente visibile a chiunque nell'account Atlassian, segui questi passaggi:

1. Accedi all'Atlassian Developer Console.

2. Fai clic sull'icona del profilo e seleziona Developer console (Console per gli sviluppatori).

3. Fai clic sull'icona del profilo utente e seleziona Manage account (Gestisci account).

4. Vai a Profilo e visibilità.

5. Vai a Contact (Contatto) e imposta Who can see this (Chi può vedere questo) su Anyone (Chiunque).

Per rendere visibile l'email dell'utente a chiunque in Confluence:

1. Accedi ad Atlassian con le tue credenziali utente.

2. Seleziona un'app Confluence.

3. Fai clic su Settings (Impostazioni) > System (Sistema).

4. Seleziona General Configuration (Configurazione generale) nel riquadro a sinistra.

5. Fai clic su Edit Settings (Modifica impostazioni).

6. Per User email visibility (Visibilità email utente), seleziona Public (Pubblica).

7. Fai clic su Aggiorna.

Installare e configurare User Identity Accessor per Confluence Cloud

Se gli indirizzi email degli utenti non sono accessibili pubblicamente per impostazione predefinita a causa delle impostazioni della privacy in Confluence Cloud, devi installare l'app User Identity Accessor per Confluence Cloud per recuperare in modo sicuro gli indirizzi email degli utenti. Se gli indirizzi email degli utenti sono già visibili pubblicamente, potresti non dover installare l'app. Per ulteriori informazioni sulla visibilità limitata delle email, vedi Gestire la visibilità degli utenti e concedere ruoli.

Ruoli e autorizzazioni

Per installare e configurare l'app User Identity Accessor per Confluence Cloud, devi disporre del ruolo amministrativo appropriato e concedere le autorizzazioni a livello di app richieste.

• Ruolo richiesto: devi essere un Confluence Site administrator per installare e configurare l'app.
• Autorizzazioni a livello di app: devi concedere le seguenti autorizzazioni durante l'installazione dell'app:
  • Read Email Address: consente all'app di recuperare in modo sicuro gli indirizzi email degli utenti, anche quando la visibilità del profilo è limitata.
  • App Storage scope: consente all'app di leggere e scrivere sul dispositivo di archiviazione.

Installa User Identity Accessor per Confluence Cloud

Per installare l'app User Identity Accessor per Confluence Cloud sul tuo sito Confluence, segui questi passaggi:

1. Vai all'Atlassian Developer Console.

2. Rivedi le autorizzazioni Read Email Address (Leggi indirizzo email) e App Storage scope (Ambito di archiviazione app) e fai clic su Get app (Scarica app).

3. Dall'elenco Select a site to install this app on (Seleziona un sito su cui installare questa app), seleziona il sito Confluence su cui vuoi installare l'app. Questo elenco mostra solo i siti per cui hai accesso amministrativo.

   Nota: per installare l'app, devi essere amministratore di almeno un sito Confluence.

4. Fai clic su Install (Installa) per completare l'installazione dell'app.

Configura User Identity Accessor per Confluence Cloud

Dopo aver installato l'app User Identity Accessor per Confluence Cloud, configura una chiave API che il tuo sistema esterno (ad esempio, il tuo connettore Confluence Cloud) utilizza per chiamare in modo sicuro il webtrigger dell'app per recuperare le email.

Accedi alla pagina di configurazione

Per accedere alla pagina di configurazione dell'app User Identity Accessor per Confluence Cloud in Confluence Cloud, segui questi passaggi:

1. Nella tua istanza Confluence Cloud, fai clic sull'icona Settings (Impostazioni) ⚙️ nel menu di navigazione.
2. Seleziona Apps (App) dal menu.
3. Nella pagina Apps administration (Amministrazione app), individua l'app User Identity Accessor per Confluence Cloud nell'elenco Manage apps (Gestisci app).
4. Fai clic su Configure (Configura) o sul link associato alla tua app. Si apre la pagina di configurazione dedicata dell'app in Confluence.

Configurare la chiave API

Per configurare la chiave API nella pagina di configurazione, segui questi passaggi:

1. Nella sezione API Key Configuration (Configurazione chiave API), specifica la chiave segreta per autenticare le richieste al webtrigger dell'app. Puoi autenticare le richieste utilizzando uno dei seguenti metodi:

   • Enter your own key (Inserisci la tua chiave): digita o incolla la tua chiave API univoca e complessa nel campo Chiave API. Utilizza una chiave di almeno 20-30 caratteri con una combinazione di lettere maiuscole, minuscole, numeri e simboli.

   • Generate a key: fai clic sul pulsante Generate a key (Genera nuova chiave). Il sistema genera e visualizza una chiave casuale complessa nel campo.

     Importante: copia immediatamente la chiave API visualizzata nel campo. Per motivi di sicurezza, potresti non essere in grado di visualizzare di nuovo la chiave completa dopo averla salvata o dopo aver abbandonato la pagina. In caso di perdita, devi impostarne o generarne uno nuovo.

2. Fai clic su Save API Key (Salva chiave API). Un messaggio di operazione riuscita conferma che la chiave è stata salvata in modo sicuro.

Nota: la chiave API generata o creata in questa sezione funge da valore per il campo Confluence Identity Sync Forge Client Secret (Client secret Forge per la sincronizzazione delle identità in Confluence) nella sezione Advanced Options (Opzioni avanzate) durante la configurazione del connettore.

Testa la configurazione dell'app

Verifica che l'app User Identity Accessor per Confluence Cloud sia configurata correttamente inviando una richiesta dal tuo sistema esterno e confermando che gli indirizzi email degli utenti vengano restituiti correttamente.

Recupera l'URL del webtrigger

1. Nella pagina Apps administration (Amministrazione app), individua la sezione Webtrigger URL (URL webtrigger), che mostra l' URL univoco specifico per il tuo sito Confluence e l'installazione di questa app:
   • Il tuo sistema esterno deve chiamare questo URL per richiedere le email degli utenti. Ad esempio, https://YOUR_INSTANCE_ID.hello.atlassian-dev.net/x1/WEBTRIGGER_ID, dove YOUR_INSTANCE_ID è l'identificatore dell'istanza Confluence Cloud e WEBTRIGGER_ID è l'identificatore unico dell'endpoint webtrigger generato per la tua app.
2. Fai clic sul pulsante Copy URL (Copia URL) o copia l'intero URL.

Configura il sistema esterno

• Configura il tuo sistema esterno che deve recuperare le email degli utenti Confluence con la chiave API e l'URL del webtrigger ottenuti nei passaggi precedenti.

  • URL endpoint: l'URL del webtrigger che hai copiato.
  • Metodo HTTP: POST

  • Intestazioni obbligatorie:

    • Tipo di contenuti: application/json

    • X-Api-Key: YOUR_API_KEY

      Sostituisci YOUR_API_KEY con la chiave API che hai impostato o generato nella sezione Configurare la chiave API.

Comando curl di esempio

Questo esempio mostra la chiamata al web trigger User Identity Accessor per Confluence Cloud, che accetta un array di ID account e restituisce gli indirizzi email.

curl --location --request POST 'https://YOUR_INSTANCE_ID.hello.atlassian-dev.net/x1/ENDPOINT_PATH' \
--header 'X-Api-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
   "accountIds": [
       "ACCOUNT_ID_1",
       "ACCOUNT_ID_2"
   ]
}'

Sostituisci:

• YOUR_INSTANCE_ID con l'ID istanza Confluence Cloud
• ENDPOINT_PATH con il percorso dell'endpoint API
• YOUR_API_KEY con la chiave API che hai impostato o generato nella sezione Configura la chiave API
• ACCOUNT_ID con gli ID account Atlassian che desideri come target

Risposta prevista

[{"accountId":"ACCOUNT_ID_1","emailAddress":"EMAIL_ADDRESS_1"},
 {"accountId":"ACCOUNT_ID_2","emailAddress":"EMAIL_ADDRESS_2"}]

Sostituisci:

• ACCOUNT_ID_X con gli ID account Atlassian effettivi
• USER_EMAIL_X con gli indirizzi email degli utenti restituiti dalla chiamata API

Implementa le best practice per la sicurezza

Per confermare la sicurezza della tua chiave API, segui questi suggerimenti:

• Memorizza la chiave API in modo sicuro nella configurazione del connettore Confluence Cloud.
• Verifica che tutte le comunicazioni con l'URL webhook avvengano tramite HTTPS. Questo è il valore predefinito per i web trigger User Identity Accessor per Confluence Cloud.

Supporto per User Identity Accessor per Confluence Cloud

Le offerte di assistenza sono disponibili a partire da Google per l'app User Identity Accessor per Confluence Cloud, che può includere la manutenzione e aggiornamenti regolari per mantenere l'app aggiornata. Se riscontri problemi o hai domande specifiche sulle funzionalità dell'app, contatta l'assistenzaGoogle Cloud .