Confluence Cloud Configuration

Setup Confluence Cloud

The connector uses a regular user to index content. There are two options for authentication of that user.

OAuth2 is the Atlassian-recommended method of authentication where an application acts on behalf of a user with limited permissions.

The API token is an application-bound high complexity password. The connector logs in as that user and has all privileges of the user.

OAuth2 app

The configuration with OAuth2 is a two step process. First you need to register the OAuth app and then you need to give that app permission to act on behalf of the technical user.

App registry

  1. Access the Atlassian Developer platform as the technical user.

  2. Click on "Create" and then "OAuth 2.0 integration".

    cc oauth 1 dev console

  3. Select a descriptive name and click "Create". This name will be displayed as part of the authorization dialogue.

    cc oauth 2 create app

  4. You will be redirected to the app overview. Click on "Permissions" in the left sidebar.

    cc oauth 3 overview

  5. In the middle pane, for the API "Confluence API", click "Add".

    cc oauth 4 scopes

  6. The button will change its label to "Config…​". Click it again.

    cc oauth 5 scope added

  7. Choose the tab "Granular Scopes" and click the "Edit Scopes" button.

    cc oauth 6 add scopes

  8. Add the following scopes:

    • read:space:confluence

    • read:attachment:confluence

    • read:blogpost:confluence

    • read:page:confluence

    • read:folder:confluence

    • read:content-details:confluence

    • read:content.metadata:confluence

    • read:group:confluence

    • read:user:confluence

  9. Click on "Save"

    cc oauth 7 edit scopes

  10. These should be the resulting scopes

    cc oauth 8 scopes

  11. On the left panel, click on "Authorization"

    cc oauth 9 authorization

  12. For authorization type "OAuth 2.0 (3LO)", click "Add"

    cc oauth 10 auth summary

  13. Set the Callback URL to "http://localhost:13131". A different port can be used but then the authorization steps have to be adjusted.

    cc oauth 11 callback

  14. On the left panel, click on "Settings"

    cc oauth 12 settings

  15. In the section "Authentication details", copy the "Client ID" and the "Secret". You will need them for both the authorization step and the connector configuration.

    cc oauth 13 settings details

User authorization

  1. Navigate to the OAuth2 token fetcher tool, that is located inside the connector installation directory.

    <INST_DIR>/tools/oauth2-tokenfetcher-<version>.

  2. Start a commandline interface (Bash, PowerShell, Cmd, Terminal)

  3. Execute the following command, using the application id and secret from before:

    bin\oauth2-tokenfetcher(.bat) --api confluencecloud -i <CLIENT_ID> -s <SECRET>

  4. The tool will now try to open a web browser and direct it to the OAuth2 login page of Atlassian.

    NOTE

    If the tool cannot open a browser, it will display a URL which you then have to copy into browser yourself. If the installation server of the connector has no browser capabilities, you will have to copy the whole folder oauth2-tokenfetcher-<version> to a computer which has them and continue from there.

  5. Log into the account that created the app

  6. Review the requested scopes

    cc oauth 14 request scopes

  7. In "Authorize for site:" select the correct target tenant and click on "Accept"

  8. The tool will notify you about successfully retrieving the OAuth 2.0 token.

    cc oauth 15 refresh token

  9. Return to the commandline interface. The tool has now completed and displays an access and a refresh token.

  10. Copy the refresh token.

You will need the client id, client secret and this refresh token during the configuration of the connector.

NOTE

The Atlassian API regularly invalidates the refresh token. If the connector has to be reconfigured or does not synchronize the token for more than 30 days, a new refresh token has to be obtained.

API token

  1. Log into your Atlassian instance using your technical account. The generated API token enables the connector to read all documents that the technical account has access to. Therefore, the technical account must have access to all documents, which should be crawled.

  2. In the top right, click on your profile picture

  3. Click on "Manage Account"

    cc 1 account

  4. Click on "Security"

    cc 2 account overview

  5. In the "API token" section, click on "Create and manage API tokens"

    cc 3 account security

  6. Click on "Create API token"

    cc 4 api token

  7. Choose meaningful label and click "Create"

    cc 5 api token name

  8. Click on "Copy" or the eye symbol and copy the API token manually. Then click on "Close"

    cc 6 api token password

  9. Your new API token will show up in the summary table. If exposed, you will also be able to revoke single tokens by clicking "Revoke" on the entry and then confirming once more.

    cc 7 api token summary

You will need the user email address and the API token for the connector configuration.

Export Users to CSV

If a user restricts access to their eMail address, the connector cannot use the standard REST API to query it. The user would then lose access to all but public documents. As an alternative, a CSV export that maps user IDs to user emails can be used. Confluence Cloud provides a detailed manual on how to export all users here.

  1. Log into admin.atlassian.com using an account with admin privileges.

  2. Click on the middle pane "Directory" and then "Users" on the left.

    cc centralized users

  3. Click on the three dots next to the button "Invite Users". The button "Export users" will appear. Click it.

    cc centralized export button

  4. A pop-up will show. Check "All users in the organization" (default) and "Only active users". Do not add additional data. Proceed by clicking the blue button "Export users".

    cc export users

  5. An email will be sent to the admin. Open the email and click the download link. Save the .csv file to a location, which can be accessed by the connector.

  6. The user .csv file should be updated regularly to capture newly added active users.

The option "Group membership → Pivot to column" should not be selected to avoid having multiple rows per user, as it can negatively affect performance.