Confluence Cloud configuration

Public preview: The federated search is in public preview. This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This page describes how to set up and configure your Confluence Cloud instance before creating the Confluence Cloud data store.

Set up authentication and permissions

You need to set up authentication and permissions in the Atlassian administrator account center. This is crucial for allowing the connector to access and synchronize data. The Confluence Cloud connector supports various authentication methods, such as OAuth client credentials or API tokens.

Create an OAuth 2.0 app

To create an OAuth 2.0 app for authentication, follow these steps to set up the application in your Atlassian Developer Console and obtain the necessary client ID and client secret.

Verify Confluence organization administrator access

To verify Confluence organization administrator access, do the following:

1. Sign-in to Atlassian with your user credentials.

2. Select the Confluence app.

3. Click Settings.

   If you see the System option under Confluence settings, you have Confluence organization administrator access. Otherwise, request your Confluence organization administrator to provide access.

Create OAuth 2.0 app

To create an OAuth 2.0 app, do the following:

1. Sign in to the Atlassian Developer Console.

2. Click the profile icon and select Developer console.

3. In the Console page, click Create and select OAuth 2.0 Integration.

4. In the app creation page, do the following:

   1. Enter a name for the app.

   2. Select the checkbox to agree to Atlassian's developer terms.

   3. Click Create.

5. In the app page, do the following:

   1. From the navigation menu, click Authorization.

   2. In the Authorization type table, select Add for OAuth 2.0 (3LO).

6. In the Callback URL field, enter https://vertexaisearch.cloud.google.com/console/oauth/confluence_oauth.html.

7. Click Save changes.

Obtain client ID and client secret

To obtain the client ID and client secret, do the following:

1. In the app page, from the navigation menu click Distribution.

2. In the Distribution page, do the following:

   1. In the Distribution controls section, select Edit.
   2. In the Distribution status section, select Sharing to enable editing other fields.
   3. Enter information in the following mandatory fields:
      1. For Vendor, enter Google.
      2. For Privacy policy, enter https://policies.google.com.
      3. For Does your app store personal data?, select Yes.
      4. Select I confirm that I've implemented the personal data reporting API checkbox.
   4. Click Save changes.

3. In the app page, do the following:

   1. From the navigation menu, click Settings.
   2. From the settings page, copy your Client ID and Client secret.

Obtain an instance ID and instance URL

1. Obtain the instance ID:

   1. Open a new tab, copy the instance URL, and append /_edge/tenant_info to the instance URL. For example, https://YOUR_INSTANCE.atlassian.net/_edge/tenant_info.
   2. Navigate to the link to find the cloudId value. The cloudId is your instance ID.

2. Obtain the instance URL:

   1. Go to atlassian.net and sign in with your administrator account.
   2. Select the app you want to sync. For example, sync the first app.
   3. Find the instance URL (the subdomain in the address bar).

Grant administrator roles

To grant the Confluence administrator the Discovery Engine Editor role in the Google Cloud console, do the following:

1. In the Google Cloud console, go to the Gemini Enterprise page.

2. Navigate to IAM.

   Go to IAM

3. Locate the user account that has administrator access in Confluence and click the Edit icon .

4. Grant the Discovery Engine Editor role to the administrator.

To grant a user an administrator role in Atlassian, do the following:

1. Sign in to Atlassian using an organization administrator account.

2. Click the menu icon and select your organization. Alternatively, you can go to admin.atlassian.com.

3. On the Admin page, click the product and select the Manage users button.

4. Click Groups under User management.

5. On the Groups page:

   1. Click Create group.
   2. Enter a name for the group.

This group receives permissions required by the connector. Users added to this group inherit these permissions. The connector uses this group to authenticate and fetch documents.

1. On the Group page, click Add product.

2. Select User access admin as the role for Confluence.

3. Select Product admin as the role for Confluence administration.

4. Click Grant Access.

5. Click Add group members to add a user account or group members that the connector uses to authenticate and access the required resources.

Configure minimum application scopes

To configure OAuth 2.0 and retrieve the required credentials for your Confluence connector setup, do the following:

1. Enable OAuth 2.0:
   1. Click Permissions.
   2. Go to Confluence API.
   3. Click Add.
   4. Click Configure.
   5. Go to the Granular scopes tab and click Edit scopes.
   6. Select the following scopes.
      • 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. Confirm that all the scopes are selected and save your changes.

Set up an API token in Confluence

If you plan to use an API token for authentication, you must create an API token without scopes. This connector doesn't support API tokens with scopes.

1. Sign in to Atlassian Console.
2. Click Create API token.
3. Enter a name for the API token.
4. Select an expiration date for the API token. The token expiration period ranges from 1 to 365 days.
5. Click Create.
6. Save the token for later use.

Manage user visibility

To make the user's email visible to anyone in the Atlassian account, follow these steps:

1. Sign in to the Atlassian Developer Console.

2. Click the profile icon and select Developer console.

3. Click the user profile icon and select Manage account.

4. Navigate to Profile and visibility.

5. Go to Contact and set the Who can see this as Anyone.

To make the user's email visible to anyone in Confluence, follow these steps:

1. Sign in to Atlassian with your user credentials.

2. Select a Confluence app.

3. Click Settings > System.

4. Select General Configuration in the left pane.

5. Click Edit Settings.

6. For User email visibility, select Public.

7. Click Update.

Install and configure User Identity Accessor for Confluence Cloud

If user email addresses aren't publicly accessible by default due to privacy settings in Confluence Cloud, you must install the User Identity Accessor for Confluence Cloud app to securely retrieve user email addresses. If user email addresses are already publicly visible, you might not need to install the app. For more information about restricted email visibility, see Manage user visibility and grant roles.

Roles and permissions

To install and configure the User Identity Accessor for Confluence Cloud app, you must have the appropriate administrative role and grant the required app-level permissions.

• Required role: You must be a Confluence Site administrator to install and configure the app.
• App-level permissions: You must grant the following permissions during the app installation:
  • Read Email Address: Allows the app to securely retrieve user email addresses, even when profile visibility is restricted.
  • App Storage scope: Enables the app to read and write to its storage device.

Install User Identity Accessor for Confluence Cloud

To install the User Identity Accessor for Confluence Cloud app on your Confluence site, follow these steps:

1. Navigate to Atlassian Developer Console.

2. Review the Read Email Address and App Storage scope permissions and click Get app.

3. From the Select a site to install this app on list, select the Confluence site where you want to install the app. This list displays only the sites for which you have administrator access.

   Note: You must be an administrator of at least one Confluence site to install the app.

4. Click Install to complete the app installation.

Configure User Identity Accessor for Confluence Cloud

After you've installed the User Identity Accessor for Confluence Cloud app, configure an API key that your external system (for example, your Confluence Cloud Connector) uses to securely call the app's webtrigger to fetch emails.

Access the configuration page

To access the User Identity Accessor for Confluence Cloud app's configuration page in Confluence Cloud, follow these steps:

1. In your Confluence Cloud instance, click the Settings ⚙️ icon in the navigation menu.
2. Select Apps from the menu.
3. On the Apps administration page, locate your app, User Identity Accessor for Confluence Cloud, in the Manage apps list.
4. Click Configure or the link associated with your app. The app's dedicated configuration page opens within Confluence.

Set up the API key

To set up the API key on the configuration page, follow these steps:

1. In the API Key Configuration section, specify the secret key for authenticating requests to the app's webtrigger. You can authenticate requests using either of the following methods:

   • Enter your own key: Type or paste your own strong, unique API key into the API Key field. Use a key of at least 20–30 characters with a mix of uppercase letters, lowercase letters, numbers, and symbols.

   • Generate a key: Click the Generate New Key button. The system generates and displays a strong, random key in the field.

     Important: Immediately copy the API key displayed in the field. For security reasons, you might be unable to view the full key again after saving or navigating away. If lost, you need to set or generate a new one.

2. Click Save API Key. A success message confirms that the key is securely saved.

Note: The API key generated or created in this section serves as the value for the Confluence Identity Sync Forge Client Secret field in the Advanced Options section during Connector setup.

Test the app configuration

Verify that the User Identity Accessor for Confluence Cloud app is configured correctly by sending a request from your external system and confirming that user email addresses are returned successfully.

Get the webtrigger URL

1. On the Apps administration page, locate the Webtrigger URL section, which displays the unique URL specific to your Confluence site and this app installation:
   • Your external system must call this URL to request user emails. For example, https://YOUR_INSTANCE_ID.hello.atlassian-dev.net/x1/WEBTRIGGER_ID, where YOUR_INSTANCE_ID is your Confluence Cloud instance identifier and WEBTRIGGER_ID is the unique identifier for the webtrigger endpoint generated for your app.
2. Click the Copy URL button or copy the entire URL.

Configure your external system

• Configure your external system that needs to fetch Confluence user emails with the API key and webtrigger URL obtained in the previous steps.

  • Endpoint URL: The webtrigger URL you copied.
  • HTTP Method: POST

  • Required Headers:

    • Content-Type: application/json

    • X-Api-Key: YOUR_API_KEY

      Replace YOUR_API_KEY with the API key you set or generated in the Set up the API key section.

Example curl command

This example demonstrates calling the User Identity Accessor for Confluence Cloud webtrigger, which accepts an array of account IDs and returns the email addresses.

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"
   ]
}'

Replace:

• YOUR_INSTANCE_ID with your Confluence Cloud instance ID
• ENDPOINT_PATH with the API endpoint path
• YOUR_API_KEY with the API key you set or generated in the Set up the API key section
• ACCOUNT_ID with Atlassian account IDs you want to target

Expected response

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

Replace:

• ACCOUNT_ID_X with actual Atlassian account IDs
• USER_EMAIL_X with user email addresses returned from your API call

Implement security best practices

To confirm the security of your API key, follow these recommendations:

• Store the API key securely within your Confluence Cloud Connector's configuration.
• Verify that all communication with the webhook URL occurs over HTTPS. This is the default for User Identity Accessor for Confluence Cloud webtriggers.

Support for User Identity Accessor for Confluence Cloud

Support offerings are available from Google for the User Identity Accessor for Confluence Cloud app that can include maintenance and regular updates to keep the app up to date. If you encounter any issues or have questions specific to the app functionality, contact Google Cloud Support.