> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-server-langgraph.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication Issues

> Troubleshooting guide for JWT, Keycloak, and OpenFGA authorization issues

# Authentication Issues

This guide covers common authentication and authorization problems.

## JWT Token Validation Fails

**Symptom**: `401 Unauthorized` or `Invalid token`

**Diagnosis**:

```bash theme={null}
# Decode JWT to inspect claims
echo "YOUR_JWT_TOKEN" | base64 -d | jq .

# Check token expiration
python3 <<EOF
import jwt
token = "YOUR_JWT_TOKEN"
decoded = jwt.decode(token, options={"verify_signature": False})
print(f"Expires: {decoded.get('exp')}")
print(f"Issued: {decoded.get('iat')}")
EOF
```

**Common Causes**:

### 1. Token Expired

```python theme={null}
# Solution: Implement token refresh
from datetime import datetime, timedelta

if token_exp < datetime.utcnow() + timedelta(minutes=5):
    # Refresh token before it expires
    new_token = refresh_jwt_token(refresh_token)
```

### 2. Wrong Public Key

```bash theme={null}
# Verify Keycloak public key matches
curl http://keycloak:8080/realms/mcp-server/protocol/openid-connect/certs

# Check AUTH_PUBLIC_KEY_URL in config
echo $AUTH_PUBLIC_KEY_URL
```

### 3. Missing Required Claims

```json theme={null}
// Token must include:
{
  "sub": "user-id",
  "preferred_username": "username",
  "realm_access": {
    "roles": ["user", "admin"]
  }
}
```

***

## Keycloak Connection Refused

**Symptom**: `ConnectionError: ('Connection aborted.', ConnectionRefusedError(111, 'Connection refused'))`

**Solutions**:

### 1. Keycloak Not Ready

```bash theme={null}
# Wait for Keycloak to fully start
docker-compose logs -f keycloak

# Look for: "Keycloak 25.0.0 started in XXms"
```

### 2. Wrong Keycloak URL

```bash theme={null}
# Check KEYCLOAK_URL environment variable
echo $KEYCLOAK_URL

# Should match Keycloak service name in docker-compose.yml
# Inside container: http://keycloak:8080
# From host: http://localhost:8080
```

### 3. Keycloak Admin Credentials Invalid

```bash theme={null}
# Reset Keycloak admin password
docker-compose exec keycloak \
  /opt/keycloak/bin/kcadm.sh set-password \
  --username admin \
  --new-password admin \
  --realm master
```

***

## OpenFGA Authorization Denied

**Symptom**: `403 Forbidden` or `OpenFGA authorization check failed`

**Diagnosis**:

```bash theme={null}
# Check OpenFGA connection
curl http://openfga:8080/healthz

# List stores
curl http://openfga:8080/stores

# Check user permissions
curl -X POST http://openfga:8080/stores/YOUR_STORE_ID/check \
  -H "Content-Type: application/json" \
  -d '{
    "tuple_key": {
      "user": "user:alice",
      "relation": "read",
      "object": "document:readme"
    }
  }'
```

**Common Issues**:

### 1. Store ID Not Set

```bash theme={null}
# Verify OPENFGA_STORE_ID environment variable
echo $OPENFGA_STORE_ID

# Create store if missing
curl -X POST http://openfga:8080/stores \
  -H "Content-Type: application/json" \
  -d '{"name": "mcp-server"}'
```

### 2. Missing Relationship Tuples

```bash theme={null}
# Write relationship tuple
fga tuple write --store-id $OPENFGA_STORE_ID \
  user:alice member organization:acme
```

### 3. Authorization Model Not Set

```bash theme={null}
# Upload authorization model
curl -X POST http://openfga:8080/stores/$OPENFGA_STORE_ID/authorization-models \
  -H "Content-Type: application/json" \
  -d @config/openfga-model.json
```

***

## Service Principal Authentication Failed

**Symptom**: `403 Forbidden` when using API key or service principal token

**Diagnosis**:

```bash theme={null}
# Check service principal exists
curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://localhost:8000/api/v1/service-principals

# Verify API key is valid
curl -H "X-API-Key: $API_KEY" \
  http://localhost:8000/api/v1/health
```

**Solutions**:

### 1. API Key Not Active

```python theme={null}
# Check API key status
from mcp_server_langgraph.auth import api_key_service

key_info = await api_key_service.get_key_info(api_key)
if not key_info.is_active:
    print("API key is inactive")
```

### 2. Service Principal Disabled

```bash theme={null}
# Enable service principal
curl -X PATCH -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://localhost:8000/api/v1/service-principals/$SP_ID \
  -d '{"is_active": true}'
```

### 3. Incorrect Scopes

```json theme={null}
// Verify API key has required scopes
{
  "scopes": ["read:agents", "write:agents", "execute:tools"]
}
```

***

## CORS Errors

**Symptom**: `Access-Control-Allow-Origin` errors in browser console

**Solution**:

```python theme={null}
# Configure CORS in settings
CORS_ORIGINS = [
    "http://localhost:3000",
    "https://your-frontend-domain.com"
]

# Or in environment variable
export CORS_ORIGINS="http://localhost:3000,https://your-domain.com"
```

***

## Still Having Issues?

If you're still experiencing authentication problems:

1. **Enable Debug Logging**: Set `LOG_LEVEL=DEBUG` to see detailed auth flow
2. **Check Network**: Ensure services can communicate (DNS, firewall)
3. **Review Configuration**: Verify all auth-related environment variables
4. **Search Issues**: Check [GitHub Issues](https://github.com/vishnu2kmohan/mcp-server-langgraph/issues)