Skip to main content
Version: v1.7.5

Confluence OAuth setup

Overview​

Confluence Cloud OAuth enables users to connect their Atlassian accounts and import documents from Confluence without sharing an API token or a Confluence account's username and password.

note

For the user steps to import documents, see Import from Confluence. For setting details and configuration through the API or SDK, see Data connectors and OAuth.

Prerequisites​

  • An Atlassian account with permission to create OAuth 2.0 apps in the Atlassian developer console.
  • Organization administrator access in Atlassian Administration, if the organization blocks user-installed apps. See third-party app access.
  • Administrator access to Enterprise h2oGPTe.
  • Connector linking turned on for the Enterprise h2oGPTe deployment. See Data connectors and OAuth.
  • An Enterprise h2oGPTe deployment with a public HTTPS URL.

Step 1: Create an OAuth 2.0 (3LO) app​

  1. Sign in to the Atlassian developer console.
  2. Select Create > OAuth 2.0 integration.
  3. Enter a name (for example, H2O GPTe Confluence Connector).
  4. Under Access type, select Resource-level to limit access to the site each user selects during authorization, or Account-level to grant access to every site in the user's account.
  5. Agree to the developer terms and select Create.
  6. In the new app, go to Distribution and turn on sharing. Until sharing is on, only your Atlassian account can authorize the app.

Create a new OAuth 2.0 (3LO) integration form with the app name entered and access type options

Step 2: Add API permissions​

The connector needs scopes from two separate APIs in the developer console: the Confluence API (to read content) and the User identity API (to identify the user who authorized the connection).

Confluence API​

  1. In the app, go to Permissions.

  2. Next to Confluence API, select Add.

  3. Select Configure for the Confluence API.

  4. Select the Granular scopes tab.

  5. Select Edit Scopes.

  6. In the Edit Confluence API dialog, select the following scopes:

    ScopePurpose
    read:page:confluenceRead Confluence pages.
    read:space:confluenceRead Confluence spaces.
    read:attachment:confluenceRead attachments and embedded images.
    read:hierarchical-content:confluenceList subpages.

  7. Select Save.

Edit Confluence API dialog with granular scopes selected and a Save button

User identity API​

  1. In the app, go to Permissions.

  2. Next to User identity API, select Add.

  3. Select Configure for the User identity API.

  4. Select Edit Scopes.

  5. In the Edit User identity API dialog, select the following scope:

    ScopePurpose
    read:meIdentify the Atlassian user who authorized the connection.

  6. Select Save.

Edit User identity API dialog with the read scope checkbox and a Save button

note

You don't add offline_access in the developer console. Enterprise h2oGPTe requests it when Confluence OAuth Scopes includes it. Without it, users must reconnect each time their access expires.

The scopes you select here, across both APIs, must match Confluence OAuth Scopes in Step 5. If they don't, users see a scope error when they connect.

Step 3: Configure authorization settings​

  1. In the app, go to Authorization.
  2. Next to OAuth 2.0 (3LO), select Configure.
  3. In Callback URLs, enter https://<your-h2ogpte-domain>/api/v1/connectors/confluence/callback.
  4. Select Save changes.

Authorization page in the Atlassian developer console showing the OAuth 2.0 (3LO) callback URL field

Step 4: Copy the Client ID and Secret​

  1. In the app, go to Settings.
  2. Copy the Client ID and save it. You enter it in the System Dashboard in Step 5.
  3. Copy the Secret and save it securely.

Settings page in the Atlassian developer console showing the Client ID and Secret fields

important

Treat the Secret the same way you would a password. Anyone who has both the Client ID and Secret can impersonate this app.

Step 5: Configure Confluence OAuth in Enterprise h2oGPTe​

  1. In Enterprise h2oGPTe, click Account Circle.

  2. Select System Dashboard.

  3. In the Configuration section, click System settings.

  4. Scroll down to the OAUTH category.

  5. Set the following values:

    SettingValue to enter
    Confluence OAuth Client IDThe Client ID from Step 4.
    Confluence OAuth Client SecretThe Secret from Step 4. Stored encrypted.
    Confluence OAuth Redirect URLThe callback URL from Step 3. The value must match exactly.
    Confluence OAuth Scopesread:me read:space:confluence read:page:confluence read:hierarchical-content:confluence read:attachment:confluence offline_access. Replace any other value in the field.

Confluence OAuth settings in the OAUTH category of System settings

For per-setting details and configuration through the REST API or Python SDK, see Data connectors and OAuth.

Step 6: Get the app approved (if required)​

If your Atlassian organization blocks user-installed apps, users see "Your site admin must authorize this app" until an administrator allows it. Ask an Atlassian organization administrator to allow the app from Apps > Sites > your site > Connected apps in Atlassian Administration. Organizations that don't block user-installed apps can skip this step.

Verify the connection​

  1. Click Account Circle, and then select Connectors.
  2. On the Data Connectors page, find the Confluence card and click Connect.
  3. Accept the Atlassian consent screen.

The Confluence card then shows Disconnect.

Troubleshooting​

Confluence doesn't appear on the Data Connectors page​

Cause: Confluence OAuth Client ID is empty in System settings.

Resolution: Set Confluence OAuth Client ID in the OAUTH category of System settings.

Invalid redirect URI​

The Atlassian authorization page shows an error that the redirect_uri isn't registered for the client.

Cause: The callback URL in the Atlassian developer console doesn't match the value configured in Enterprise h2oGPTe.

Resolution: Verify that the Confluence OAuth Redirect URL in the System Dashboard exactly matches the Callback URL in the app's Authorization settings. The protocol (https://), domain, and path (/api/v1/connectors/confluence/callback) must all match.

App requires organization approval​

Users see "Your site admin must authorize this app" when they try to connect.

Cause: The Atlassian organization restricts which apps users can authorize, and no organization administrator has approved this app yet.

Resolution: Ask an Atlassian organization administrator to approve the app (see Step 6).

Users see a scope or permission error​

Cause: The scopes configured on the Atlassian app (Step 2) don't match, or are narrower than, the scopes configured in Confluence OAuth Scopes (Step 5).

Resolution: Confirm that the scopes on the Atlassian app match Confluence OAuth Scopes, except offline_access. To skip a content type, such as attachments, remove its scope from both places.

Token refresh fails or users must reconnect​

Cause: The offline_access scope is missing from Confluence OAuth Scopes, or the user revoked access to the app from the Atlassian side.

Resolution:

  • Confirm that offline_access appears in Confluence OAuth Scopes in the System Dashboard.
  • Ask the user to reconnect from the Data Connectors page.

Best practices​

  • Store secrets securely: Use environment-specific credentials and don't commit secret values to version control.
  • Request only the scopes you need: Match the scopes on the Atlassian app to what your users actually import (for example, omit read:attachment:confluence if you never import attachments or embedded images).
  • Data connectors and OAuth - Per-setting reference for SharePoint, Confluence, and Snowflake OAuth configuration
  • Import from Confluence - End-user workflow for importing Confluence documents into a collection, including API token authentication
  • Secret Manager - Store a Confluence username and API token as an alternative to OAuth
  • Connectors - Overview of all available data connectors
Feedback