B24Workflows OAuth Server v2.3 - Documentació Completa

📖 Què és i què fa

B24Workflows OAuth Server v2.3 és un servidor OAuth multiusuari que permet a aplicacions externes accedir de forma segura a la API de Bitrix24 mitjançant tokens OAuth individuals per cada usuari.

🎯 Objectiu Principal

Facilitar l'accés programàtic a Bitrix24 des d'aplicacions externes (Python, PHP, JavaScript, etc.) sense haver de gestionar manualment el procés complex d'OAuth per cada usuari.

🔥 Característiques Clau v2.3

✅ Validació UTC Robusta

Verificació d'expiració de tokens amb comparació UTC independent del timezone local.

🗑️ Cleanup Automàtic

Sistema de neteja de tokens expirats amb informes detallats i programació automàtica.

🌍 Interfície Bilingüe

Missatges i documentació en català i espanyol per als usuaris d'Evenia.

📊 Dashboard Integrat

Monitorització visual amb Streamlit i mètriques en temps real.

🏗️ Arquitectura del Sistema

[Aplicació Externa] 
        ↓
[Traefik 2.11.24 HTTPS]
        ↓  
[B24Workflows OAuth Server v2.3]
        ↓
[SQLite Database] ←→ [Bitrix24 OAuth API]
        ↓
[Streamlit Dashboard]
                

📦 Components Tècnics

Frontend: FastAPI + Streamlit dashboard
Base de Dades: SQLite amb taules user_tokens i tokens
Proxy Invers: Traefik 2.11.24 amb certificats wildcard HTTPS
Container: Python 3.11 slim amb usuari non-root
Ports: 8000 (FastAPI) + 8501 (Streamlit) via Traefik

🔄 Flux de Funcionament OAuth

1. Sol·licitud Inicial

POST /api/v2/request-user-token
{
  "user_email": "usuari@evenia.ad",
  "domain": "bitrix.evenia.ad"  
}
                

2. Verificació de Token Existent

Si existeix token vàlid: Retorna {"status": "token_exists"}
Si token expirat o inexistent: Retorna {"status": "authorization_needed", "authorization_url": "..."}

3. Procés d'Autorització (Si cal)

GET /login/user/{user_email}?domain=bitrix.evenia.ad
# ↓ Redirect automàtic a Bitrix24 OAuth
                

4. Recuperació de Token

GET /api/v2/get-user-token/{user_email}?domain=bitrix.evenia.ad
# ↓ Retorna access_token vàlid per fer crides a Bitrix24
                

🌐 Endpoints Disponibles

🔑 API OAuth v2 (Principals)

POST /api/v2/request-user-token

Sol·licitar token OAuth per un usuari específic

GET /api/v2/get-user-token/{user_email}

Recuperar token vàlid (no expirat) per un usuari

🏥 Monitorització i Status

GET /health

Health check del servei

GET /status

Status detallat del sistema

🗑️ Sistema de Cleanup v2.3

GET /api/v2/admin/tokens-analysis

Anàlisi completa de tokens (requereix admin_key)

POST /api/v2/admin/cleanup-tokens

Cleanup manual de tokens expirats (requereix admin_key)

✅ Sistema de Validació UTC v2.3

El sistema implementa una validació robusta d'expiració UTC que resol els problemes de tokens expirats que es retornaven com a vàlids:

🔧 Millores Implementades

Parsing robust de dates: Suporta formats amb i sense "T", amb i sense microsegons
Comparació UTC: Independent del timezone local del servidor
Missatges bilingües: Errors d'expiració en català i espanyol
Logging informatiu: Registra tokens vàlids i expirats per debugging

🎯 Flux Correcte

Usuari demana token → request_user_token()
Sistema busca token → get_valid_user_token()
Si troba token:
- ✅ Verifica si és vàlid (no expirat) amb UTC
- Si és vàlid → Retorna "token_exists"
- ❌ Si és expirat → Error 401 + genera nova autorització
Si no troba token → Genera nova autorització

🗑️ Sistema de Cleanup v2.3

Sistema automàtic de neteja de tokens expirats amb anàlisi matemàtic i informes detallats.

📊 Anàlisi per 250 Usuaris

Ús realista: ~156 tokens nous/setmana, ~670 tokens/mes
Sense cleanup: 8,036 tokens/any, creixement BD de 4MB
Impacte cleanup: ~156 tokens expirats/setmana a eliminar

🔧 Components del Sistema

Script CLI: cleanup_expired_tokens.py amb flags --dry-run, --report, --json
Endpoints API: Cleanup manual i anàlisi via REST API
Automatització Docker: Cron job setmanal (diumenge 02:00)

🛠️ Exemples d'Integració

Exemple Python

import requests

# Configuració
BASE_URL = "https://b24oauth.evenia.dev"
USER_EMAIL = "usuari@evenia.ad"
DOMAIN = "bitrix.evenia.ad"

# Sol·licitar token
response = requests.post(
    f"{BASE_URL}/api/v2/request-user-token",
    headers={"Content-Type": "application/json"},
    json={"user_email": USER_EMAIL, "domain": DOMAIN},
    verify=False
)

result = response.json()

if result["status"] == "token_exists":
    # Obtenir el token
    token_response = requests.get(
        f"{BASE_URL}/api/v2/get-user-token/{USER_EMAIL}?domain={DOMAIN}",
        verify=False
    )
    
    if token_response.status_code == 200:
        token_data = token_response.json()
        access_token = token_data["access_token"]
        
        # Usar el token amb Bitrix24
        bitrix_response = requests.get(
            f"https://{DOMAIN}/rest/user.current",
            params={"auth": access_token}
        )
        print("Dades usuari:", bitrix_response.json())
                

Exemple cURL

# Sol·licitar token
curl -k -X POST "https://b24oauth.evenia.dev/api/v2/request-user-token" \
  -H "Content-Type: application/json" \
  -d "{\"user_email\": \"usuari@evenia.ad\", \"domain\": \"bitrix.evenia.ad\"}"

# Obtenir token existent
curl -k "https://b24oauth.evenia.dev/api/v2/get-user-token/usuari@evenia.ad?domain=bitrix.evenia.ad"
                

🧪 Comandes de Verificació Completes

Health Checks

# Health check bàsic
curl -k -s "https://b24oauth.evenia.dev/health" | python -m json.tool

# Status detallat
curl -k -s "https://b24oauth.evenia.dev/status" | python -m json.tool

# Debug de base de dades
curl -k -s "https://b24oauth.evenia.dev/api/v2/database-debug" | python -m json.tool
                

Sistema de Cleanup

# Anàlisi de tokens (sense eliminar)
curl -k -s "https://b24oauth.evenia.dev/api/v2/admin/tokens-analysis?admin_key=admin_cleanup_2025" | python -m json.tool

# Dry run del cleanup (simulació)
curl -k -X POST -s "https://b24oauth.evenia.dev/api/v2/admin/cleanup-tokens?admin_key=admin_cleanup_2025&dry_run=true" | python -m json.tool

# Cleanup real (eliminar tokens expirats)
curl -k -X POST -s "https://b24oauth.evenia.dev/api/v2/admin/cleanup-tokens?admin_key=admin_cleanup_2025&dry_run=false" | python -m json.tool
                

OAuth i Tokens

# Sol·licitar token (amb fitxer JSON per evitar problemes PowerShell)
# Crear test_request.json amb: {"user_email": "omolist@evenia.ad", "domain": "bitrix.evenia.ad"}
curl -k -X POST "https://b24oauth.evenia.dev/api/v2/request-user-token" -H "Content-Type: application/json" -d @test_request.json

# Obtenir token existent
curl -k -s "https://b24oauth.evenia.dev/api/v2/get-user-token/omolist@evenia.ad?domain=bitrix.evenia.ad" | python -m json.tool
                

Test de Token Expirat

# Crear token expirat per proves
docker exec b24workflows-local python3 -c "
import sqlite3; from datetime import datetime, timedelta
conn = sqlite3.connect('/app/data/b24workflows_v2.db')
cursor = conn.cursor()
cursor.execute('DELETE FROM user_tokens WHERE user_email = ?', ('test_expirat@evenia.ad',))
expired_time = datetime.utcnow() - timedelta(hours=3)
expired_str = expired_time.strftime('%Y-%m-%d %H:%M:%S.%f')
cursor.execute('INSERT INTO user_tokens (user_email, domain, access_token, refresh_token, expires_at, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)', ('test_expirat@evenia.ad', 'bitrix.evenia.ad', 'TOKEN_EXPIRAT_TEST', 'REFRESH_EXPIRAT', expired_str, expired_str, expired_str))
conn.commit(); print(f'Token expirat creat: {expired_str}'); conn.close()"

# Provar token expirat (ha de donar error 401)
curl -k -s "https://b24oauth.evenia.dev/api/v2/get-user-token/test_expirat@evenia.ad?domain=bitrix.evenia.ad" | python -m json.tool
                

📋 Configuració Traefik Crítica

🔴 Labels Traefik Essencials

Aquests labels són obligatoris per al funcionament correcte del sistema:

# OBLIGATORI: Habilita routing automàtic Traefik
- "traefik.enable=true"

# ROUTING PRINCIPAL: Host específic per accés extern  
- "traefik.http.routers.b24workflows-api.rule=Host(`b24oauth.evenia.dev`)"

# SEGURETAT: Només HTTPS, no HTTP
- "traefik.http.routers.b24workflows-api.entrypoints=websecure"
- "traefik.http.routers.b24workflows-api.tls=true"

# PRIORITATS: Evita conflictes entre serveis del mateix contenidor
- "traefik.http.routers.b24workflows-api.priority=100"
- "traefik.http.routers.b24workflows-streamlit.priority=200"

# SERVEIS EXPLÍCITS: Evita confusió automàtica Traefik
- "traefik.http.routers.b24workflows-api.service=b24workflows-api-service"
- "traefik.http.services.b24workflows-api-service.loadbalancer.server.port=8000"

# XARXA: CRUCIAL per comunicació Traefik ↔ Contenidor
- "traefik.docker.network=traefik-public"
                

🐳 Desplegament Docker

Requeriments del Sistema

Docker Engine: v20.10+ o superior
Docker Compose: v2.0+ o superior
Traefik: v2.11.24 (exactament aquesta versió)
Certificats HTTPS: Wildcard *.evenia.dev
DNS: Resolució b24oauth.evenia.dev → IP servidor
Ports: 80, 443 disponibles per Traefik

Passos de Desplegament

# 1. Crear xarxa compartida Traefik
docker network create traefik-public

# 2. Desplegar Traefik
docker-compose -f docker-compose-traefik.yml up -d

# 3. Construir imatge amb sqlite3 fix
docker build -t b24workflows:local .

# 4. Desplegar aplicació
docker-compose -f docker-compose-b24workflows.yml up -d

# 5. Verificació post-desplegament
curl -k https://b24oauth.evenia.dev/health
curl -k https://b24oauth.evenia.dev/docs
                

⚡ Punts Crítics d'Implementació

🔴 SQLite3 Fix + Validació UTC

El servidor utilitza sqlite3 directe amb validació robusta UTC per verificar l'expiració de tokens. Aquest fix és obligatori per al funcionament correcte.

🔴 Certificats Wildcard

Utilitza certificats wildcard del servidor de producció per evitar conflictes al navegador.

🔴 Configuració Traefik

Les línies de prioritat i serveis explícits són essencials per evitar conflictes de routing.

✅ Estat v2.3

Sistema completament operatiu i verificat amb validació de tokens robusta i cleanup automàtic.