Atlassian OAuth Integration

A simple, reusable Node.js implementation of OAuth 2.0 authentication for Atlassian products (Jira, Confluence, etc.) using the Authorization Code flow with PKCE.

Features

• 🔐 Secure OAuth 2.0 authentication with PKCE
• 🎯 Automatic cloud ID detection and storage
• 📦 Ready-to-use Jira API integration
• 🍪 Session management with HTTP-only cookies
• 🚀 Minimal dependencies and easy setup
• 🔄 Support for multiple Atlassian sites per user

Prerequisites

• Node.js (v14 or higher)
• npm or yarn
• An Atlassian account
• Access to Atlassian Developer Console

Quick Start

1. Clone the repository

git clone https://github.com/yourusername/atlassian-oauth.git
cd atlassian-oauth

2. Install dependencies

npm install

3. Create an Atlassian OAuth App

1. Go to Atlassian Developer Console
2. Click "Create" → "OAuth 2.0 integration"
3. Fill in the app details:
   • App name: Your app name
   • App description: Brief description
   • Company: Your company name
4. Set up OAuth 2.0:
   • Callback URL: http://localhost:3978/auth/callback || your production url.
   • Permissions: Configure the following scopes:
     • read:jira-user - View Jira user information
     • read:jira-work - View Jira projects and issues
     • offline_access - Maintain access to data
     • read:me - View user profile
5. Save your app and note down:
   • Client ID
   • Client Secret

4. Configure environment variables

Create a .env file in the project root:

# Required
ATLASSIAN_CLIENT_ID=your-client-id-here
ATLASSIAN_CLIENT_SECRET=your-client-secret-here

# Optional (these have defaults)
PORT=3978
ATLASSIAN_REDIRECT_URI=http://localhost:3978/auth/callback

5. Run the application

npm start

Visit http://localhost:3978 and click "Login with Atlassian" to test the authentication flow.

Project Structure

atlassian-oauth/
├── app.js          # Main Express application
├── auth.js         # OAuth authentication logic
├── config.js       # Configuration management
├── jiraApi.js      # Jira API integration
├── package.json    # Project dependencies
├── .env            # Environment variables (create this)
└── README.md       # This file

API Endpoints

Endpoint	Method	Description
/	GET	Home page with login status
/auth/login	GET	Initiates OAuth flow
/auth/callback	GET	OAuth callback handler
/auth/logout	GET	Clears session and logs out
/api/me	GET	Returns user profile and available sites
/api/projects	GET	Lists all Jira projects

Usage Examples

Getting User Information

After authentication, you can get user information:

// In your route handler
const { getUserProfile } = require('./auth');

app.get('/api/user-info', async (req, res) => {
  try {
    const profile = await getUserProfile(req);
    res.json(profile);
  } catch (error) {
    res.status(401).json({ error: 'Not authenticated' });
  }
});

Accessing Jira Projects

const { getProjects } = require('./jiraApi');

app.get('/api/my-projects', async (req, res) => {
  try {
    const projects = await getProjects(req);
    res.json(projects);
  } catch (error) {
    res.status(500).json({ error: 'Failed to fetch projects' });
  }
});

Creating a Jira Issue

const { createIssue } = require('./jiraApi');

app.post('/api/create-issue', async (req, res) => {
  try {
    const issueData = {
      fields: {
        project: { key: 'PROJ' },
        summary: 'New issue from OAuth app',
        description: 'Issue description',
        issuetype: { name: 'Task' }
      }
    };
    const issue = await createIssue(req, issueData);
    res.json(issue);
  } catch (error) {
    res.status(500).json({ error: 'Failed to create issue' });
  }
});

How It Works

1. Authentication Flow:

   • User clicks "Login with Atlassian"
   • App redirects to Atlassian's OAuth authorization page
   • User approves permissions
   • Atlassian redirects back with authorization code
   • App exchanges code for access token
   • Token and cloud ID are stored in secure cookies

2. Session Management:

   • Access tokens are stored in HTTP-only cookies
   • Sessions expire after 1 hour
   • Cloud ID is automatically detected and stored

3. API Access:

   • All Jira API calls automatically use the stored cloud ID
   • Authentication headers are automatically included

Security Considerations

• 🔒 Uses PKCE (Proof Key for Code Exchange) for enhanced security
• 🍪 Stores tokens in HTTP-only cookies to prevent XSS attacks
• 🚫 Never exposes client secrets to the frontend
• ⏰ Implements proper session expiration
• 🔐 All sensitive data is handled server-side only

Extending the Application

Adding New Scopes

To request additional permissions, modify the scopes in auth.js:

const scope = 'read:jira-user read:jira-work offline_access read:me write:jira-work';

Supporting Confluence

Add Confluence-specific endpoints in a new file confluenceApi.js:

const getSpaces = async (req) => {
  const accessToken = getAccessToken(req);
  const cloudId = getCloudId(req);
  
  const response = await axios.get(
    `https://api.atlassian.com/ex/confluence/${cloudId}/rest/api/space`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Accept': 'application/json'
      }
    }
  );
  
  return response.data;
};

Troubleshooting

Common Issues

1. "Invalid redirect URI" error:

   • Ensure the callback URL in your .env matches exactly with the one in Atlassian Developer Console

2. "401 Unauthorized" errors:

   • Check if your access token has expired
   • Verify that you have the required scopes

3. Cannot access Jira projects:

   • Ensure your Atlassian account has access to at least one Jira site
   • Check that the read:jira-work scope is enabled

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have questions:

• Open an issue on GitHub
• Check the Atlassian OAuth documentation
• Review the CLAUDE.md file for detailed development notes

Acknowledgments

• Built with Express.js
• Uses Atlassian's OAuth 2.0 (3LO) implementation
• Inspired by the need for a simple, reusable Atlassian authentication solution

Note

Since the OAuth authentication flow is the same for all Atlassian products, you can easily extend this project to support Confluence API calls. Simply create a confluenceApi.js file similar to jiraApi.js and use the same authentication tokens and helper functions from auth.js. The access token and cloud ID obtained during login work across all Atlassian products (Jira, Confluence, Trello, etc.) that the user has access to.