Guía: integrar el OAuth de Cubicornio en tu app

Cubicornio actúa como Authorization Server OAuth 2.0. Tus bundles o apps externas pueden delegar el login a Cubicornio usando Authorization Code + PKCE, igual que con Google o GitHub.

1 Flujo general (igual para todos los lenguajes)

● Creas una OAuth App en el Dev Portal (/dev/oauth/apps) y obtienes tu client_id y client_secret.
● Registras una Redirect URI (callback) en la app. Debe coincidir exactamente con la URL que usarás en tu backend.
● En tu backend (Flask, Node, etc.) registras un proveedor OAuth apuntando a: Autorización: https://cubicornio.com/dev/oauth/authorize
Token: https://cubicornio.com/dev/oauth/token
● Tu app redirige al usuario a /dev/oauth/authorize con response_type=code, client_id, redirect_uri, scope y (opcionalmente) PKCE.
● El usuario ve el login/consent de Cubicornio, se autentica y autoriza tu app.
● Cubicornio redirige a tu redirect_uri con un parámetro code (Authorization Code).
● Tu backend intercambia ese code por un access_token (y refresh_token) en /dev/oauth/token.
● Con ese Bearer token ya puedes llamar APIs de Cubicornio en nombre del usuario logueado.

2 ¿Qué trae el access_token de Cubicornio?

El access_token es un JWT que representa al usuario de Cubicornio que aceptó el consent:

◆ sub / id → login.idusers del usuario en Cubicornio.
◆ roles y permissions → mismos roles/permisos que el usuario tiene dentro de Cubicornio.
◆ client_id y client_owner_id → identifican la OAuth App y su dueño.
◆ scopes, exp, iat, etc.

Tu app no necesita decodificar el token para autorización interna: basta con enviarlo en Authorization: Bearer <access_token> cuando llame APIs de Cubicornio.

0 Antes de escribir código: crea tu OAuth App

1. Entra a /dev/oauth/apps.
2. Crea una nueva OAuth App con Nombre, Homepage URL y una sola Redirect URI.
3. Cuando se cree, copia tu client_id y client_secret (sólo se muestran una vez).
4. Guárdalos en el .env de tu bundle o app:

CUBICORNIO_CLIENT_ID=tu_client_id
CUBICORNIO_CLIENT_SECRET=tu_client_secret

# Endpoints OAuth fijos de Cubicornio (no hace falta ponerlos en .env)
# Autorización: https://cubicornio.com/dev/oauth/authorize
# Token:        https://cubicornio.com/dev/oauth/token

Ejemplos por lenguaje / framework

La lógica del flujo es la misma en todos los lenguajes. Sólo cambia cómo registras el proveedor y defines las rutas de login / callback.

Python · Flask (bundle dentro de Cubicornio o app externa)

A Registrar el proveedor OAuth con Authlib

En tu bundle Flask (o app Flask externa), registra al proveedor cubicornio usando CUBICORNIO_CLIENT_ID y CUBICORNIO_CLIENT_SECRET del .env.

from authlib.integrations.flask_client import OAuth
import os

oauth = OAuth(app)

cubicornio = oauth.register(
    name="cubicornio",
    client_id=os.getenv("CUBICORNIO_CLIENT_ID"),
    client_secret=os.getenv("CUBICORNIO_CLIENT_SECRET"),
    access_token_url="https://cubicornio.com/dev/oauth/token",
    authorize_url="https://cubicornio.com/dev/oauth/authorize",
    api_base_url="https://cubicornio.com/api/",
    client_kwargs={
        # Ajusta scopes según lo que ofrezcamos
        "scope": "bundle:read offline_access",
    },
)

B Ruta de login: redirigir a Cubicornio

Define una ruta que redirija a /dev/oauth/authorize. El redirect_uri debe ser exactamente el mismo que registraste en tu OAuth App.

from flask import Blueprint, redirect, url_for, session, request

oauth_login = Blueprint("oauth_login", __name__)

@oauth_login.route("/login/cubicornio")
def login_cubicornio():
    # Conserva ?next=/ruta/que/quieres luego del login
    next_url = request.args.get("next") or "/"
    session["login_next"] = next_url

    redirect_uri = url_for("oauth_login.cubicornio_callback", _external=True)
    # redirect_uri debe coincidir EXACTO con el registrado en la OAuth App
    return cubicornio.authorize_redirect(redirect_uri)

C Callback: intercambiar el code por tokens

Authlib se encarga de llamar a /dev/oauth/token con grant_type=authorization_code. Obtendrás un access_token y un refresh_token.

from flask import redirect, url_for

@oauth_login.route("/login/cubicornio/callback")
def cubicornio_callback():
    # Authlib maneja el intercambio code -> token
    token = cubicornio.authorize_access_token()
    access_token = token["access_token"]
    refresh_token = token.get("refresh_token")

    # Aquí decides cómo mapear esto a tu usuario local.
    # Opciones:
    #   - guardar access_token en sesión
    #   - crear/actualizar un registro "linked to Cubicornio"
    #   - etc.
    session["cubicornio_access_token"] = access_token
    session["cubicornio_refresh_token"] = refresh_token

    next_url = session.pop("login_next", "/")
    return redirect(next_url)

D Usar el Bearer token en tus llamadas a Cubicornio

Cuando tu bundle necesite llamar APIs de Cubicornio, envía el token en el header Authorization. Desde el lado de Cubicornio, tus roles y permisos se respetarán igual que dentro del ERP.

import requests

API_BASE = "https://cubicornio.com/api"

def call_cubicornio(access_token: str, path: str):
    url = f"{API_BASE}{path}"
    headers = {
        "Authorization": f"Bearer {access_token}",
    }
    resp = requests.get(url, headers=headers, timeout=15)
    resp.raise_for_status()
    return resp.json()

# Ejemplo:
# data = call_cubicornio(session["cubicornio_access_token"], "/dev/some-endpoint")