Confluence Connector - Authentication

Overview

The Confluence Connector authenticates in two directions:

1. Confluence authentication – to read pages and attachments from Confluence Cloud or Data Center.

2. Unique platform authentication – to ingest content into the Unique knowledge base.

This guide covers both authentication paths, including credential setup, secret management, and token flows.

Confluence Authentication Methods

• Confluence Cloud supports only OAuth 2.0 two-legged (2LO).

• Confluence Data Center 10.1+ supports both OAuth 2.0 (2LO) and Personal Access Token (PAT). OAuth 2.0 (2LO) is recommended.

• Confluence Data Center below 10.1 must use Personal Access Token (PAT), as OAuth 2.0 (2LO) is not available on those versions.

Unique Platform Authentication Methods

The connector's tenant YAML field for selecting the Unique auth mode is serviceAuthMode (not authMode).

Note: The Helm chart values.yaml uses unique.authMode, which the Helm template maps to serviceAuthMode in the generated tenant config YAML.

Setup Steps

1. Create a Unique Service User

The connector requires a service user in the Unique platform (Zitadel). The user must exist in Zitadel so that a valid x-user-id can be referenced.

Zitadel authorizations (role assignments) are only enforced in external mode. In cluster_local mode, the Unique platform does not check Zitadel authorizations. The x-user-id must reference an actual existing service user, but its assigned roles are irrelevant.

In external mode, the service user must have the following authorizations:

This user identity is referenced:

• In cluster_local mode: as the x-user-id header value in serviceExtraHeaders. This must be the ID of an actual service user in Zitadel. It cannot be an arbitrary value.

• In external mode: implicitly via the Zitadel client credentials (zitadelClientId / zitadelClientSecret).

Steps:

1. Navigate to Zitadel.
2. Create a new service user.
3. For external mode: assign the required authorizations listed above and generate a client secret. For cluster_local mode: no authorizations or client secret are needed.
4. Note the user ID (and for external mode, the client ID and client secret) for configuration.

2. Create the Root Scope in Unique

The connector requires a pre-existing root scope in Unique. The root scope ID is configured in the tenant YAML under ingestion.scopeId. If the scope does not exist at startup, the connector fails.

At startup, the connector automatically grants itself access on the root scope and will create child scopes for each Confluence space that has content to ingest. See the Scope Hierarchy for details.

3. Set Up Confluence Authentication

Option A: OAuth 2.0 (2LO) -- Cloud

Required tenant YAML fields:

confluence:
  instanceType: cloud
  baseUrl: https://your-domain.atlassian.net
  cloudId: your-cloud-id
  auth:
    mode: oauth_2lo
    clientId: your-oauth-client-id
    clientSecret: os.environ/CONFLUENCE_CLIENT_SECRET

Option B: OAuth 2.0 (2LO) -- Data Center

Required tenant YAML fields:

confluence:
  instanceType: data-center
  baseUrl: https://confluence.your-company.com
  auth:
    mode: oauth_2lo
    clientId: your-confluence-app-client-id
    clientSecret: os.environ/CONFLUENCE_CLIENT_SECRET

Option C: Personal Access Token -- Data Center Below 10.1 Only (Not Recommended)

Required tenant YAML fields:

confluence:
  instanceType: data-center
  baseUrl: https://confluence.your-company.com
  auth:
    mode: pat
    token: os.environ/CONFLUENCE_PAT

4. Set Up Unique Platform Authentication

Option A: Cluster-Local

Required tenant YAML fields:

unique:
  serviceAuthMode: cluster_local
  serviceExtraHeaders:
    x-company-id: your-company-id
    x-user-id: your-user-id
  ingestionServiceBaseUrl: http://node-ingestion.<namespace>:8091
  scopeManagementServiceBaseUrl: http://node-scope-management.<namespace>:8094

Option B: External (Zitadel)

Required tenant YAML fields:

unique:
  serviceAuthMode: external
  zitadelOauthTokenUrl: https://auth.your-unique-instance.com/oauth/v2/token
  zitadelProjectId: your-zitadel-project-id
  zitadelClientId: confluence-connector
  zitadelClientSecret: os.environ/ZITADEL_CLIENT_SECRET
  ingestionServiceBaseUrl: https://ingestion.your-unique-instance.com
  scopeManagementServiceBaseUrl: https://scope-management.your-unique-instance.com

Secret Resolution

Secret fields in the tenant YAML support the os.environ/ENV_VAR_NAME format to resolve values from environment variables at runtime:

os.environ/ENV_VAR_NAME

Providing Secrets in Kubernetes

Use Kubernetes Secrets to inject environment variables into the connector pod. The Helm chart supports this via the connector.envVars field in values.yaml:

connector:
  envVars:
    - name: CONFLUENCE_CLIENT_SECRET
      valueFrom:
        secretKeyRef:
          name: confluence-connector-secret
          key: CONFLUENCE_CLIENT_SECRET
    - name: ZITADEL_CLIENT_SECRET
      valueFrom:
        secretKeyRef:
          name: confluence-connector-secret
          key: ZITADEL_CLIENT_SECRET

Best Practices

• Rotate before expiration – create the new secret before the old one expires to avoid downtime
• Use Kubernetes Secrets or a secret manager – never store secrets in ConfigMaps or plain text
• Monitor for authentication failures – failed token acquisition is logged and indicates an expired or revoked secret
• Document rotation procedures – include secret rotation in your operational runbook

Troubleshooting

OAuth Token Acquisition Failure

Symptom: Failed to acquire Confluence {instanceType} token via OAuth 2.0 2LO in logs.

PAT Authentication Failure

Symptom: 401 Unauthorized responses from Confluence Data Center.

Secret Resolution Failure

Symptom: Config validation fails with an empty string error for a secret field.