Authentication Setup

Complete guide to setting up secure authentication with Confluence Cloud using OAuth 2.0.

Overview

The MCP Confluence ADF server uses OAuth 2.0 for secure, token-based authentication with Confluence Cloud. This provides:

Secure Access: No need to store passwords or API keys
Scoped Permissions: Access only what your app needs
Automatic Refresh: Tokens refresh automatically
Revocable Access: Can be revoked from Atlassian account settings

Prerequisites

Confluence Cloud instance (not Server/Data Center)
Atlassian Account with admin access to your Confluence
Developer Console Access to create OAuth apps

Step 1: Create OAuth App in Atlassian Developer Console

Access Developer Console

Go to developer.atlassian.com
Sign in with your Atlassian account
Click your profile icon → "Developer console"

Create New App

Click "Create app"
Enter app name: "Claude Code MCP Server" (or your preferred name)
Click "Create"

Configure OAuth 2.0

In your app, click "Authorization" in left menu
Next to "OAuth 2.0 (3LO)", click "Configure"
Enter Callback URL: http://localhost:9000/oauth/callback
Click "Save changes"

Add Required Permissions

Click "Permissions" in left menu
Next to "Confluence API", click "Add"
Select these required scopes:

Essential Scopes

read:confluence-content.all    - Read all content
write:confluence-content       - Create/edit content  
read:content:confluence        - Read content (granular)
write:content:confluence       - Write content (granular)
read:space:confluence          - Access spaces
read:page:confluence           - Read pages
write:page:confluence          - Create/edit pages
search:confluence              - Search functionality
offline_access                 - Token refresh

Additional Scopes (Recommended)

read:confluence-content.summary     - Content summaries
read:confluence-space.summary       - Space information

Click "Save" after adding all scopes

Get Your Credentials

Click "Settings" in left menu
Copy your Client ID and Client Secret
Keep these secure - you'll need them for authentication

Step 2: Initialize OAuth in Claude Code

Start Authentication Flow

In Claude Code, run:

Set up OAuth authentication with Confluence using:
- Client ID: [your-client-id]
- Client Secret: [your-client-secret]

Or use the tool directly:

{
  "tool": "confluence_oauth_init",
  "parameters": {
    "clientId": "your-client-id-from-console",
    "clientSecret": "your-client-secret-from-console"
  }
}

Expected Response:

OAuth initialization started

📱 Next step: Visit this URL to authorize the application:
https://auth.atlassian.com/authorize?...

 This URL will expire in 10 minutes

Complete Authorization

Continue with:

Complete OAuth authentication and open my browser

Or:

{
  "tool": "confluence_oauth_complete", 
  "parameters": {
    "openBrowser": true
  }
}

Step 3: Browser Authorization Flow

Authorization Process

Browser Opens to Atlassian authorization page
Sign In to your Atlassian account (if not already signed in)
Review App Permissions:
- App name and description
- Requested scopes/permissions
- Which Confluence sites it can access
Click "Accept" to grant permissions
Automatic Redirect back to callback server
Success Page displays "Authentication Successful!"
Browser tab closes automatically

What Happens During Authorization

PKCE Security: Uses Proof Key for Code Exchange for enhanced security
State Parameter: Prevents CSRF attacks
Secure Token Exchange: Authorization code exchanged for access tokens
Local Storage: Tokens stored securely on your machine

Step 4: Verify Authentication

Check Status

Check my Confluence authentication status

Expected Output:

OAuth Authentication Active

Status: Connected and ready
Cloud ID: [your-confluence-cloud-id]  
Client Configured: Yes
Ready for API calls: Yes
🔄 Token Refresh: Automatic
Storage: Secure keychain (macOS) / Credential Manager (Windows) / File (Linux)

Test Connection

List my Confluence spaces

If authentication is working, you'll see your accessible Confluence spaces.

Token Management

Automatic Token Refresh

Access tokens expire after 1 hour
Refresh tokens are used automatically to get new access tokens
No user intervention required for token refresh
Refresh tokens expire after 90 days of inactivity

Token Storage Security

macOS: Keychain Access

Stored in system keychain
Encrypted and secure
Access controlled by macOS

Windows: Credential Manager

Windows Credential Manager
Encrypted storage
User-specific access

Linux: File-based with permissions

Stored in ~/.mcp/confluence-adf/oauth-tokens.json
File permissions: 600 (owner read/write only)
JSON format with encrypted sensitive data

Managing Tokens

Check Token Status

Check Confluence authentication status

Clear/Reset Authentication

Clear my Confluence authentication

This will:

Remove all stored tokens
Clear OAuth state
Require re-authentication for next use

Troubleshooting Authentication

Common Issues

1. "Invalid Client" Error

Cause: Client ID or secret incorrect Solution: Verify credentials from Developer Console

2. "Redirect URI Mismatch"

Cause: Callback URL doesn't match app configuration Solution: Ensure callback URL in app matches http://localhost:9000/oauth/callback

3. "Insufficient Scope" Error

Cause: Missing required OAuth scopes Solution: Add all required scopes in Developer Console

4. "Site Access Denied"

Cause: App doesn't have access to your Confluence site Solution:

Check site admin settings
Ensure your account has appropriate permissions

5. Browser Doesn't Open

Cause: System browser configuration Solution:

Copy authorization URL manually
Paste in browser to complete flow

6. Tokens Expired

Cause: Refresh token expired (90 days inactive) Solution: Re-run authentication flow

Debugging Steps

Check MCP Server Logs:

# View server output for error messages
tail -f ~/.mcp/confluence-adf/logs/server.log

Verify App Configuration:
- Client ID and secret correct
- All required scopes added
- Callback URL exact match
Test Network Connectivity:
```
curl -I https://api.atlassian.com
```

Clear and Retry:

Clear Confluence authentication
Set up OAuth authentication again

Security Best Practices

App Configuration

Use descriptive app names that identify their purpose
Request minimal scopes needed for functionality
Regular review of app permissions in Atlassian account

Token Handling

Never share client secrets or tokens
Rotate credentials periodically (create new app if needed)
Monitor access in Atlassian account security settings
Revoke unused apps from account settings

Development vs Production

Separate apps for development and production use
Different callback URLs for different environments
Environment-specific credentials

Advanced Configuration

Custom Callback Port

If port 9000 is unavailable:

{
  "tool": "confluence_oauth_init",
  "parameters": {
    "clientId": "your-client-id", 
    "clientSecret": "your-client-secret",
    "redirectUri": "http://localhost:8080/oauth/callback"
  }
}

Update your app's callback URL to match.

Multiple Confluence Instances

For multiple Confluence clouds:

Create separate OAuth apps for each instance
Use different client credentials for each
Authenticate separately for each instance

Headless Authentication

For server environments without browsers:

Generate authorization URL on development machine
Complete authorization flow manually
Export/import tokens to server environment

API Rate Limits

Confluence Cloud API has rate limits:

Standard: 10 requests per second per app
Burst: Up to 100 requests in short periods
Daily: 10,000 requests per day per app

The MCP server handles rate limiting automatically:

Request queuing and throttling
Exponential backoff on rate limit errors
Automatic retry with appropriate delays

Next Steps

Once authentication is complete:

Quick Start Guide - Start using Confluence tools
Confluence Content Tools - Available operations
MCP Tool Discovery - Finding and using tools
Claude Code Integration - Advanced workflows

PreviousClaude Code Integration NextConfluence Content Tools

Last updated 5 days ago