# webauth.dkl `webauth.dkl` (dkl-web) tiene las funciones comunes de autenticación y autorización: encontrar el token de sesión de la petición y resolver un manifiesto de privilegios contra los datos del usuario. ```dkl #include "functions.dkh" #include "serialize.dkh" #include "cookies.dkl" #include "webauth.dkl" ``` `auth.token` usa `cookie.get`, así que incluya `cookies.dkl` antes cuando busque el token en cookies (la configuración predeterminada lo hace). ## auth.token: encontrar el token de sesión ```dkl t = auth.token() ``` Devuelve el token de sesión de la petición, o `""` si no hay. Busca en las ubicaciones del registro global `@http_token_locations`, en el orden en que están sus miembros. Este es su valor predeterminado: ```dkl using @http_token_locations { @"get":"ids,token" @"cookie":"__induxsoft_token" @"form":"session_id" @"json":"ids,token" @"bearer":@true @"header":"" @"custom_auth":@true } ``` | Miembro | Busca en | Valor | |---|---|---| | `get` | Parámetros de la URL | Nombres separados por comas, en orden | | `cookie` | Cookies | Nombres separados por comas | | `form` | Campos de un formulario `x-www-form-urlencoded` | Nombres separados por comas | | `json` | Miembros del cuerpo JSON | Nombres separados por comas | | `bearer` | Encabezado `Authorization: Bearer ` ([RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)) | `@true` o `@false` | | `header` | Un encabezado HTTP propio | Nombres separados por comas, **con guion bajo** en lugar de guion (`X_Token` para `X-Token`), porque nginx los pasa como `HTTP_X_TOKEN` | | `custom_auth` | Todo el contenido del encabezado `Authorization` | `@true` o `@false` | Con la configuración predeterminada, el orden de búsqueda es: parámetro `ids`, parámetro `token`, cookie `__induxsoft_token`, campo de formulario `session_id`, miembros `ids` y `token` del JSON, `Authorization: Bearer`, y por último el texto completo de `Authorization`. La primera ubicación con valor gana. A cualquier token encontrado se le quitan los apóstrofos (`'`). Resultados reales con 2.0 (un programa que responde `{"token": auth.token()}`): | Petición | Resultado | |---|---| | `GET /?ids=AAA` | `AAA` | | `GET /?token=BBB` | `BBB` | | `Cookie: __induxsoft_token=CCC` | `CCC` | | `POST` con `session_id=DDD` (formulario) | `DDD` | | `Authorization: Bearer GGG` | `GGG` | | `Authorization: HHH` | `HHH` | | `GET /?ids=AAA` y `Authorization: Bearer GGG` | `AAA` (el parámetro va primero) | | Nada | `""` | **Defecto conocido del cuerpo JSON.** En la versión actual de dkl-web, cuando el token viene en el cuerpo JSON (`{"ids":"EEE"}` o `{"token":"FFF"}`), `auth.token` no devuelve el token sino un número sin sentido (en la prueba, `15`): la línea del caso `json` llama a `trim` con dos argumentos. Mientras se corrige, no envíe el token en el cuerpo JSON: use `Authorization: Bearer`, que es lo recomendado para clientes REST, o lea el miembro usted mismo con `from.json(@@(@http_context,"$request/POST_STRING"))`. ### Cambiar dónde se busca Defina `@http_token_locations` **después** de incluir `webauth.dkl` (al incluirse, la biblioteca pone los valores predeterminados). Por ejemplo, solo un encabezado propio y luego Bearer: ```dkl #include "dkli.dkh" #! program "token" { #include "functions.dkh" #include "serialize.dkh" #include "cookies.dkl" #include "webauth.dkl" new @http_token_locations { @"header": "X_Token" @"bearer": @true } new r { @"token": auth.token() } @http_context<"response/output">: "text" @http_context<"response/text">: to.json(r) } ``` | Petición | Resultado | |---|---| | `X-Token: XYZ` | `{"token":"XYZ"}` | | `Authorization: Bearer GGG` | `{"token":"GGG"}` | | `GET /?ids=AAA` | `{"token":""}` (ya no se busca en la URL) | Si el IdP del sitio (`_protected/idp/default.dk`) es el que llama a `auth.token`, haga el cambio en el IdP o en `auth.dk` antes de cargarlo. ## auth.checkPrivs: qué privilegios tiene el usuario ```dkl ref privs = auth.checkPrivs(login, manifiesto) ``` | Parámetro | Contenido | |---|---| | `login` | Registro con los datos del usuario: `uid`, `memberships/workspaces`, `memberships/teams`, `memberships/roles` y cualquier otro campo (`email`...). Es lo que deja el IdP en `session/user` | | `manifiesto` | Registro de privilegios: cada llave es un privilegio y su valor es una lista de **condiciones**; basta cumplir una | Devuelve una lista con los nombres de los privilegios del manifiesto que el usuario cumple. | Condición | Se cumple si | |---|---| | `{"user": "pedro"}` | `uid` es `pedro` | | `{"user": "+"}` | Siempre (cualquier usuario, con o sin sesión) | | `{"user": "*"}` | El usuario es anónimo (`uid` = `*`, como lo arma `auth.dk` cuando no hay sesión) | | `{"workspace": "x"}` | `x` está en `memberships/workspaces` | | `{"team": "x"}` | `x` está en `memberships/teams` | | `{"role": "x"}` | `x` está en `memberships/roles` | | `{"campo": "valor"}` | El campo `campo` del usuario vale `valor` (por ejemplo, `{"email":"ana@ejemplo.com"}`) | Cada condición se evalúa por su primer par llave-valor. ## auth.findStrInList: ¿está en la lista? ```dkl si = auth.findStrInList(lista, valor) ``` Devuelve `@true` si `valor` está en la lista de cadenas. Con lista nula o valor vacío devuelve `@false`. ## Ejemplo ```dkl #include "dkli.dkh" #! program "privilegios" { #include "functions.dkh" #include "serialize.dkh" #include "cookies.dkl" #include "webauth.dkl" ref manifiesto = from.json(' { "read": [{"user":"+"}], "write": [{"team":"administradores"}, {"user":"juan"}], "other": [{"user":"pedro"}], "admin": [{"role":"sistemas"}] }') ref login = from.json(' { "uid": "pedro", "memberships": { "teams": ["administradores","gerentes"], "roles": [], "workspaces": [] } }') ref privs = auth.checkPrivs(login, manifiesto) do print(to.json(privs)) puede_escribir = auth.findStrInList(privs, "write") es_admin = auth.findStrInList(privs, "admin") do print("write: " + str(puede_escribir) + " admin: " + str(es_admin)) } ``` Salida real: ```text ["read","write","other"] write: 1 admin: 0 ``` `pedro` obtiene `read` (todos), `write` (es del equipo `administradores`) y `other` (por su `uid`), pero no `admin` (no tiene el rol `sistemas`). El ejemplo de la documentación 1.0 omitía la coma entre `"write"` y `"other"` y escribía `maniefiesto` al llamar a `auth.checkPrivs`; aquí están corregidos. (`from.json` tolera la coma faltante, pero no la escriba así: otros lectores de JSON sí la rechazan.) ## Errores típicos | Síntoma | Causa y solución | |---|---| | `auth.token()` devuelve un número al mandar el token en JSON | Defecto conocido (arriba): use `Authorization: Bearer` | | `auth.token()` no encuentra el encabezado propio | Escriba el nombre con guion bajo (`X_Token`) | | `Función: cookie.get no reconocida` | Falta `#include "cookies.dkl"` antes de `webauth.dkl` | | `auth.checkPrivs` devuelve vacío | Los nombres de equipos, roles o espacios del manifiesto deben coincidir exactamente con los del usuario (en el IdP de base de datos, los equipos son los `sys_guid` de `usergroup`) |