MCP JIRA Server

# ADFS Authentication with Kerberos This document explains how to use ADFS authentication with the MCP JIRA server. ## Overview The ADFS authentication mode uses your Kerberos credential cache (krb5cc) to: 1. Authenticate with ADFS using Kerberos SSO 2. Obtain SAML/OAuth tokens from ADFS 3. Use those tokens to access JIRA APIs ##Configuration ### Environment Variables Add the following to your `.env` file: ```bash # Set auth method to ADFS AUTH_METHOD=adfs # JIRA URL JIRA_URL=https://jira.yourcompany.com # Kerberos principal for SSO KERBEROS_PRINCIPAL=HTTP/jira.yourcompany.com@REALM # Optional: ADFS server URL (for SAML token acquisition) ADFS_URL=https://adfs.yourcompany.com # Optional: Keytab file path (if not using kinit) KERBEROS_KEYTAB_PATH=/path/to/your.keytab ``` ## Authentication Flow ### Method 1: Direct Kerberos to JIRA (Recommended) If your JIRA instance supports Kerberos/SPNEGO directly: 1. The server uses your Kerberos credential cache 2. Authenticates directly to JIRA using HTTP Negotiate/SPNEGO 3. No ADFS_URL needed ```bash # Initialize Kerberos ticket kinit your.username@REALM # Run server python -m mcp_jira ``` ### Method 2: ADFS SAML Token If you need ADFS SAML tokens: 1. The server reads your Kerberos credentials from ccache 2. Authenticates with ADFS using Kerberos SSO 3. Requests SAML token from ADFS WS-Trust endpoint 4. Uses SAML token to access JIRA ```bash # Set ADFS URL in .env ADFS_URL=https://adfs.yourcompany.com # Initialize Kerberos ticket kinit your.username@REALM # Run server python -m mcp_jira ``` ## Kerberos Credential Cache The authentication module automatically uses the Kerberos credential cache: ### Default Location - Linux/macOS: `/tmp/krb5cc_$(id -u)` or value of `KRB5CCNAME` - Windows: In-memory cache or file specified by `KRB5CCNAME` ### Custom Cache Location Set the environment variable before running: ```bash export KRB5CCNAME=/path/to/custom/krb5cc_file python -m mcp_jira ``` ## Troubleshooting ### No Kerberos Ticket **Error**: `No valid Kerberos ticket found` **Solution**: ```bash # Get a new ticket kinit your.username@REALM # Verify ticket klist # Check expiration klist -A ``` ### ADFS Token Acquisition Failed **Error**: `ADFS token acquisition failed` **Solutions**: 1. Verify ADFS_URL is correct 2. Check network connectivity to ADFS 3. Ensure JIRA URL matches the service principal 4. Try direct Kerberos mode (remove ADFS_URL) ### Authentication Logs Enable debug logging: ```bash DEBUG=true LOG_LEVEL=DEBUG ``` Then check logs for detailed authentication flow. ## Comparison with Other Auth Methods | Method | Use Case | Required Config | |--------|----------|----------------| | `kerberos` | Direct Kerberos to JIRA | KERBEROS_PRINCIPAL | | `adfs` | ADFS federation with Kerberos SSO | KERBEROS_PRINCIPAL, optional ADFS_URL | | `api_token` | Simple token-based auth | JIRA_EMAIL, JIRA_API_TOKEN | | `basic` | Username/password (not recommended) | JIRA_USERNAME, JIRA_PASSWORD | ## Benefits of ADFS Authentication - **Single Sign-On**: Use your existing Kerberos ticket - **No Password Storage**: Leverages system credentials - **Enterprise Integration**: Works with corporate ADFS infrastructure - **Token Refresh**: Automatic token renewal using Kerberos - **Fallback Support**: Can use direct Kerberos if ADFS is unavailable ## Example: Full Setup ```bash # 1. Configure environment cat > .env << EOF JIRA_URL=https://jira.example.com AUTH_METHOD=adfs KERBEROS_PRINCIPAL=HTTP/jira.example.com@EXAMPLE.COM ADFS_URL=https://adfs.example.com EOF # 2. Initialize Kerberos kinit username@EXAMPLE.COM # 3. Verify ticket klist # 4. Run MCP server source .venv/bin/activate python -m mcp_jira # 5. Server will automatically: # - Read Kerberos credentials from ccache # - Authenticate with ADFS # - Obtain tokens for JIRA access ``` ## Security Notes - Kerberos tickets are stored in the credential cache securely - The server never stores passwords - Tokens are cached in memory only - Use `KERBEROS_MUTUAL_AUTH=true` for mutual authentication - Regularly renew Kerberos tickets (e.g., via cron with kinit)