# oauth.dkh: OAuth 2.0 para API e inicio de sesión `oauth.dkh` implementa los flujos de OAuth 2.0 que usan los proveedores más comunes: - **client_credentials**: su servidor obtiene un token para hablar con una API, por ejemplo la de PayPal. - **authorization code con PKCE**: el usuario inicia sesión con Google, Microsoft u otro proveedor. Está escrita en DKL sobre [http.dkh](/es/devkron/2.0/bibliotecas/estandar/http.md), [hash.dkh](/es/devkron/2.0/bibliotecas/estandar/hash.md), [url.dkh](/es/devkron/2.0/bibliotecas/estandar/url.md) y el caché de [threads.dkh](/es/devkron/2.0/bibliotecas/estandar/threads.md), y viene con la distribución de Devkron 2.0. ## Cuándo usarla - Llamar a API que piden un token de acceso: pagos (PayPal), mensajería, servicios en la nube. - "Iniciar sesión con Google" o "con Microsoft" en un portal, sin manejar contraseñas. - Renovar el acceso a la cuenta de un usuario con un *refresh token*. Incluya antes todo lo que usa, en este orden: ```dkl #include "functions.dkh" #include "serialize.dkh" #include "threads.dkh" #include "http.dkh" #include "url.dkh" #include "hash.dkh" #include "oauth.dkh" ``` ## Funciones | Función | Devuelve | Descripción | |---|---|---| | `oauth.client_credentials(url_token, client_id, secreto, scope)` | cadena | `access_token`; lo reutiliza del caché del proceso mientras falten más de 60 s para que caduque | | `oauth.authorize_url(url_auth, client_id, redirect_uri, scope, llave_cookie)` | cadena | URL de inicio de sesión con `state` y PKCE (S256); guarda el state y el verificador en la cookie firmada `oauth_state` | | `oauth.exchange_code(url_token, client_id, secreto, redirect_uri, llave_cookie)` | registro | En la página de regreso: valida la cookie y el `state`, canjea el código y devuelve el registro del proveedor; borra la cookie | | `oauth.refresh(url_token, client_id, secreto, refresh_token)` | registro | Tokens nuevos a partir de un *refresh token* | | `oauth.bearer(token)` | registro | `{Authorization: "Bearer …"}` listo para `http.*` | ### oauth.client_credentials Envía `grant_type=client_credentials`, `client_id`, `client_secret` y, si no es `""`, `scope` como formulario (`http.post_form`). Guarda el token en el caché del proceso con una llave que combina URL, cliente, scope y secreto: las llamadas siguientes con los mismos datos devuelven el mismo token sin ir a la red, hasta 60 segundos antes de que caduque (`expires_in`, 3 600 si el proveedor no lo indica). Si el servidor no entrega `access_token`, lanza error con el código HTTP y la descripción del proveedor. ### oauth.authorize_url Arma la URL con `response_type=code`, `client_id`, `redirect_uri`, `scope`, un `state` aleatorio de 32 caracteres (protege contra peticiones falsificadas) y PKCE (`code_challenge` S256 de un verificador de 64 caracteres). El `state` y el verificador se guardan en la cookie `oauth_state`, firmada con HMAC-SHA256 usando `llave_cookie`, con `Path=/;Max-Age=600;HttpOnly;Secure;SameSite=Lax`. No necesita sesión en el servidor. Redirija al usuario con `httpres.redirect`. `llave_cookie` es un secreto de su aplicación, no se envía al proveedor. Con `""` lanza error. ### oauth.exchange_code En la página de regreso (`redirect_uri`) lee `code`, `state`, `error` y la cookie de la petición. Comprueba la firma de la cookie y que el `state` coincida, canjea el código enviando el verificador (`code_verifier`), borra la cookie y devuelve lo que entrega el proveedor: `access_token`, `expires_in` y, según el proveedor, `refresh_token` e `id_token`. Con un cliente público (sin secreto), pase `secreto = ""`: no se envía `client_secret`. ### oauth.refresh Canjea un `refresh_token` por tokens nuevos. Guarde el `refresh_token` protegido: equivale a la contraseña del usuario para ese servicio. ## Ejemplo: token de servicio con client_credentials Contra un servidor de prueba local que entrega tokens `cc-1`, `cc-2`… y rechaza secretos incorrectos: ```dkl #include "dkli.dkh" #! program "token de servicio" { #include "functions.dkh" #include "serialize.dkh" #include "threads.dkh" #include "http.dkh" #include "url.dkh" #include "hash.dkh" #include "oauth.dkh" url_token = "http://127.0.0.1:19590/token" t1 = oauth.client_credentials(url_token, "mi_cliente", "s3cr3t", "facturas.leer") t2 = oauth.client_credentials(url_token, "mi_cliente", "s3cr3t", "facturas.leer") t3 = oauth.client_credentials(url_token, "mi_cliente", "s3cr3t", "facturas.escribir") do print(t1 + " " + t2 + " " + t3) do print(to.json(oauth.bearer(t1))) ref r = oauth.refresh(url_token, "mi_cliente", "s3cr3t", "rt-1") do print("refresh: " + field.str(r, "access_token")) x = oauth.client_credentials(url_token, "mi_cliente", "secreto-incorrecto", "") exception { do print(last_error()) } } ``` Salida: la segunda llamada reutiliza el token del caché; otro scope pide uno nuevo. ``` cc-1 cc-1 cc-2 {"Authorization":"Bearer cc-1"} refresh: at-renovado {1} oauth.client_credentials: el servidor no entregó access_token (HTTP 401): secreto incorrecto[Ln= 20] ``` ### Con PayPal PayPal recibe el cliente y el secreto por formulario. Use su *sandbox* para desarrollar: ```dkl base = "https://api-m.sandbox.paypal.com" token = oauth.client_credentials(base + "/v1/oauth2/token", "MI_CLIENT_ID_DE_EJEMPLO", "MI_SECRETO_DE_EJEMPLO", "") ref orden = http.get_json(base + "/v2/checkout/orders/5O190127TN364715T", oauth.bearer(token)) if http.status() != 200 { do rise_error(1, "PayPal respondió " + str(http.status())) } ``` Este fragmento necesita credenciales de PayPal y no se ejecutó. En el servidor FastCGI solo la primera petición pide el token: PayPal lo entrega con vigencia de varias horas y las peticiones siguientes lo reutilizan. ## Ejemplo: iniciar sesión con Google Registre su aplicación en la consola de Google Cloud (credenciales OAuth tipo "Aplicación web") con la URI de redirección exacta que usará. Un solo controlador hace las dos partes: sin `code`, manda al usuario a Google; con `code`, canjea el código. ```dkl #include "dkli.dkh" #! program "login" { #include "functions.dkh" #include "serialize.dkh" #include "threads.dkh" #include "http.dkh" #include "url.dkh" #include "hash.dkh" #include "oauth.dkh" client_id = "1234567890-ejemplo.apps.googleusercontent.com" secreto = "MI_SECRETO_DE_EJEMPLO" regreso = "https://portal.localhost/auth/regreso" llave_cookie = "MiLlaveDeCookieDeEjemplo_cambie-esto" if httpreq.has("code") || httpreq.has("error") { // Regreso del proveedor: ?code=...&state=... ref t = oauth.exchange_code("http://127.0.0.1:19590/token", client_id, secreto, regreso, llave_cookie) do httpres.ok(t) return } do httpres.redirect(oauth.authorize_url("https://accounts.google.com/o/oauth2/v2/auth", client_id, regreso, "openid email profile", llave_cookie)) exception { do httpres.fail(last_error()) do httpres.status(401) } } ``` Para probarlo, el canje se hizo contra el servidor local (`http://127.0.0.1:19590/token`); con Google la URL es `https://oauth2.googleapis.com/token`. Resultado real, por FastCGI: ``` 1) 302 https://accounts.google.com/o/oauth2/v2/auth parámetros: ['client_id', 'code_challenge', 'code_challenge_method', 'redirect_uri', 'response_type', 'scope', 'state'] state: 32 caracteres code_challenge: 43 S256 cookie: oauth_state Path=/;Max-Age=600;HttpOnly;Secure;SameSite=Lax 2) 200 {"success":true,"data":{"access_token":"at-abc123","refresh_token":"rt-1","verifier_len":64}} ['oauth_state=;Path=/;Max-Age=0'] 3) 401 {"success":false,"message":"{1} oauth.exchange_code: el state no coincide[Ln= 59]"} 4) 401 {"success":false,"message":"{1} oauth.exchange_code: el proveedor respondió access_denied el usuario canceló[Ln= 53]"} ``` En 2) el regreso trae el `state` correcto; en 3), uno alterado; en 4), el usuario canceló en Google. En un sistema real, después del canje **valide el `id_token`** antes de confiar en el correo, y luego cree la sesión de su aplicación: ```dkl ref u = jwt.verify_rs256(field.str(t, "id_token"), "https://www.googleapis.com/oauth2/v3/certs", "https://accounts.google.com,accounts.google.com", client_id) // u.sub es el identificador permanente del usuario en Google; u.email, u.name, u.picture ``` Para Microsoft Entra ID use `https://login.microsoftonline.com//oauth2/v2.0/authorize` y `…/oauth2/v2.0/token`, y el JWKS `https://login.microsoftonline.com//discovery/v2.0/keys`. ## Errores | Mensaje | Causa | |---|---| | `oauth.client_credentials: el servidor no entregó access_token (HTTP n): …` | Credenciales o scope rechazados; el texto final es el `error_description` del proveedor | | `oauth.authorize_url: la llave de la cookie está vacía` | `llave_cookie` es `""` | | `oauth.exchange_code: falta la cookie de estado o está mal formada` | La cookie no llegó: caducó (10 min), el navegador no la guardó (falta HTTPS) o `Path` distinto | | `oauth.exchange_code: la cookie de estado no es válida` | Otra `llave_cookie` o cookie alterada | | `oauth.exchange_code: el state no coincide` | Petición falsificada o repetida | | `oauth.exchange_code: el proveedor respondió …` | El usuario canceló o el proveedor rechazó la solicitud | | `oauth.exchange_code: no se recibió el código` | El regreso no trae `code` | | `oauth.exchange_code: el servidor no entregó access_token …` / `oauth.refresh: …` | El proveedor rechazó el canje (código usado o `redirect_uri` distinta) | ## Advertencias - **El caché de tokens es por proceso**: cada proceso FastCGI pide su propio token y al reiniciar se pide de nuevo. Es normal; los proveedores lo permiten. - **`redirect_uri` debe ser idéntica** en `authorize_url`, en `exchange_code` y en la consola del proveedor: esquema, host, ruta y diagonal final. Una diferencia da `redirect_uri_mismatch`. - **Solo sobre HTTPS**: la cookie lleva `Secure` y el navegador no la envía por HTTP. - `client_id` puede ser público; el **secreto** y la **llave de la cookie** no. Guárdelos fuera del código y del repositorio. - Desarrolle con la cuenta *sandbox* del proveedor y no haga cobros de prueba con tarjetas reales ni inventadas: los proveedores de pago los validan y pueden bloquear la cuenta.