jira-rest-api

🚀 Production Deployment Guide: OAuth Authentication

This guide explains how to deploy the Jira REST API Client in production with OAuth authentication for public multi-user access.

🔄 Architecture Overview

Single User Mode (Current Default):

User → Web App → Jira API (shared API token)

Multi User Mode (Production OAuth):

User → OAuth Login → Jira Account → User's Own Access Token → Jira API

📋 Step-by-Step Setup

Step 1: Create Atlassian OAuth App

1. Go to Atlassian Developer Console:
   • Visit: https://developer.atlassian.com/console/myapps/
   • Sign in with your Atlassian account
2. Create New App:
   • Click “Create” → “OAuth 2.0 integration”
   • App name: “Jira REST API Client” (or your preferred name)
   • Click “Create”
3. Configure OAuth Settings:
   • Callback URL: https://your-domain.com/auth/callback
     • For local testing: http://localhost:5000/auth/callback
   • Permissions/Scopes:
     • read:jira-user - Read user profile
     • read:jira-work - Read issues, projects, etc.
     • write:jira-work - Create/update issues, comments
   • Click “Save”
4. Get Credentials:
   • Copy Client ID
   • Copy Client Secret
   • Save these securely!

Step 2: Configure Application

1. Update Environment Variables:

   # Set application to multi-user mode
   APP_MODE=multi_user
      
   # OAuth Configuration
   JIRA_OAUTH_CLIENT_ID=your-client-id-from-atlassian
   JIRA_OAUTH_CLIENT_SECRET=your-client-secret-from-atlassian
   JIRA_OAUTH_REDIRECT_URI=https://your-domain.com/auth/callback
      
   # Remove old single-user settings (optional)
   # JIRA_EMAIL=  (not needed in multi-user mode)
   # JIRA_API_TOKEN=  (not needed in multi-user mode)
   

2. Install OAuth Dependencies:

   pip install -r requirements.txt
   # This now includes: authlib, requests-oauthlib
   

Step 3: Deploy Application

1. Production Deployment Options:
   • Heroku: git push heroku main
   • AWS/Azure: Configure environment variables in your cloud provider
   • Docker: Set environment variables in container
   • VPS: Use systemd service with environment file
2. Set Production Environment Variables:

   export APP_MODE=multi_user
   export JIRA_OAUTH_CLIENT_ID=your-actual-client-id
   export JIRA_OAUTH_CLIENT_SECRET=your-actual-client-secret
   export JIRA_OAUTH_REDIRECT_URI=https://your-domain.com/auth/callback
   export SECRET_KEY=long-random-production-secret-key
   

🔐 Security Benefits

OAuth vs API Token:

Aspect	API Token (Single User)	OAuth (Multi User)
User Authentication	Shared credentials	Individual Jira accounts
Permissions	Admin-level access	User’s actual permissions
Security	One compromised token = full access	Per-user token isolation
Audit Trail	All actions appear as admin	Actions appear as actual users
Token Management	Never expires (manual)	Auto-refresh, can revoke

Production Security Features:

• ✅ No stored passwords - OAuth flow only
• ✅ Temporary tokens - Auto-expiring access tokens
• ✅ Individual permissions - Users see only what they should
• ✅ Revokable access - Users can revoke app access anytime
• ✅ CSRF protection - All forms protected
• ✅ Session management - Secure session handling

🎯 User Experience

For End Users:

1. Visit your app → redirected to Jira login
2. Login with their Jira credentials
3. Authorize your app (one-time)
4. Redirected back to your app
5. See only their accessible projects/issues
6. Actions recorded under their name

For Administrators:

1. No more shared API tokens
2. Individual user audit trails
3. Standard Jira permission management
4. Users can revoke access themselves

🔧 Testing OAuth Flow

Local Testing:

1. Set up local OAuth:

   export APP_MODE=multi_user
   export JIRA_OAUTH_REDIRECT_URI=http://localhost:5000/auth/callback
   # Add your client ID/secret
   

2. Update Atlassian App:
   • Add http://localhost:5000/auth/callback to callback URLs
   • This allows local testing
3. Test Flow:
   • Start app: python web_app.py
   • Visit: http://localhost:5000
   • Should redirect to login page
   • Click “Sign in with Atlassian”
   • Complete OAuth flow

📊 Monitoring & Maintenance

Application Health:

• Monitor OAuth token refresh rates
• Track authentication failures
• Monitor API rate limits per user
• Log user access patterns

User Management:

• Users manage their own access via Atlassian account
• Revoke app access: Atlassian Account Settings → Connected Apps
• No user database needed in your app

🚨 Migration from Single to Multi-User

If You Have Existing Users:

1. Communicate the change - Users need to authenticate individually
2. Set APP_MODE=multi_user - Switches authentication method
3. Update documentation - New login process
4. Keep old setup route - For emergency admin access if needed

Backward Compatibility:

• App detects APP_MODE and routes accordingly
• Single user mode still works for internal/personal use
• Can switch back by changing APP_MODE=single_user

💡 Production Tips

Performance:

• OAuth tokens cached in user sessions
• Automatic token refresh handling
• Rate limiting respected per user

Scalability:

• No shared API token rate limits
• Each user has independent rate limits
• Horizontal scaling friendly (stateless sessions)

Compliance:

• User consent flow built-in
• Individual audit trails
• Data access limited to user permissions
• GDPR-friendly (no password storage)

---

🎉 Result: A production-ready, secure, multi-user Jira client that respects individual permissions and provides enterprise-grade authentication!