Ir al contenido

Autorización

El flujo es OAuth 2.0 Authorization Code con PKCE S256 obligatorio. Tu aplicación nunca ve la contraseña ni la sesión de la persona: recibe tokens propios, que solo valen para lo que se autorizó y que la persona puede anular cuando quiera.

  1. Tu aplicación genera un code_verifier, su code_challenge y un state.
  2. Abre el navegador en GET /api/v1/oauth/authorize con esos datos.
  3. La plataforma lleva a la persona a su pantalla de consentimiento. Si no tiene sesión, entra o se registra y vuelve a esa pantalla.
  4. La persona ve el nombre de tu aplicación y los permisos que pides, y pulsa Autorizar o Cancelar.
  5. El navegador vuelve a tu dirección de retorno con code y state, o con error y state.
  6. Tu aplicación comprueba el state y cambia el code y el code_verifier por un token de acceso y uno de refresco en POST /api/v1/oauth/token.
  7. Llama a /api/v1/connect/… con Authorization: Bearer <access_token>.
  8. Cuando el token de acceso caduca, lo renueva con el de refresco, que rota en cada uso.
Valor Cómo
code_verifier Aleatorio criptográficamente seguro, de 43 a 128 caracteres de A-Z a-z 0-9 - . _ ~
code_challenge BASE64URL(SHA256(code_verifier)) sin relleno =: siempre 43 caracteres
state Aleatorio, obligatorio, de hasta 512 caracteres. Lo devolvemos intacto

Genera los tres en cada intento y guárdalos solo en memoria hasta que vuelva la respuesta. plain no se admite como método de PKCE.

Puedes comprobar tu implementación con el ejemplo del apéndice B de RFC 7636: el verificador dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk produce el reto E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM.

Depende de cómo esté registrada tu aplicación, y el esquema decide la regla:

Tipo de aplicación redirect_uri Cómo se compara
De escritorio http://127.0.0.1:{puerto}{ruta} o http://[::1]:{puerto}{ruta} El puerto es libre; la ruta debe ser una registrada, exacta
Alojada en la web https://… completa Exactamente, carácter a carácter, como se registró

Para una aplicación de escritorio:

  • abre un servidor HTTP solo en la interfaz de loopback, en un puerto libre que te dé el sistema operativo (puerto 0), justo antes de abrir el navegador, y ciérralo al recibir la respuesta;
  • usa la IP literal, nunca localhost: no se admite (RFC 8252 §8.3);
  • la dirección no lleva consulta ni fragmento.

Abre la autorización en el navegador del sistema, no en una vista web incrustada en tu aplicación: en el navegador la persona ve la dirección real de la plataforma, usa su sesión y su gestor de contraseñas, y tu aplicación no puede leer lo que escribe.

GET https://api.lectoresbeta.com/api/v1/oauth/authorize
?client_id=TU_CLIENT_ID
&redirect_uri=http://127.0.0.1:53682/callback
&response_type=code
&scope=works:read works:write feedback:read credits:read
&state=…
&code_challenge=…
&code_challenge_method=S256

Codifica los parámetros como en cualquier URL (los espacios de scope, como %20 o +).

Parámetro Obligatorio Valor
client_id Sí El que te dimos
redirect_uri Sí Ver el apartado anterior
response_type Sí code
scope Sí Permisos separados por espacios. Ver Permisos
state Sí Tu valor aleatorio
code_challenge Sí El reto PKCE
code_challenge_method Sí S256

La respuesta es un 302 a la pantalla de consentimiento. A partir de ahí no hay nada que hacer hasta que el navegador vuelva a tu dirección de retorno.

Pide solo los permisos que tu aplicación usa. La persona los ve uno a uno antes de decidir.

  • Si el client_id no existe o tu aplicación está desactivada, o la redirect_uri no es una de las registradas, el navegador no vuelve a tu aplicación: la persona ve el error en la propia página (422, con code INVALID_CONNECTED_APP_CLIENT o INVALID_REDIRECT_URI). Redirigir ahí convertiría el endpoint en un redirector abierto.
  • Cualquier otro error vuelve a tu dirección de retorno con error, error_description y tu state:
error Cuándo
unsupported_response_type response_type no es code
invalid_request Falta state o pasa de 512 caracteres; PKCE ausente, no S256 o reto inválido
invalid_scope Un permiso no existe, la lista está vacía o pide algo que tu aplicación no tiene permitido
access_denied La persona pulsó Cancelar
  • Si no tiene sesión, entra o crea su cuenta y vuelve a la pantalla de consentimiento.
  • Para autorizar necesita tener la cuenta activada con el enlace que le enviamos por correo. Si no lo está, la pantalla se lo pide y puede volver a pulsar Autorizar después.
  • La petición de autorización caduca a los 10 minutos. Si caduca, la pantalla le pide volver a empezar desde tu aplicación: inicia el flujo de nuevo, con verificador y state nuevos.
  • La pregunta se hace siempre, aunque la persona ya hubiera autorizado tu aplicación. Autorizar de nuevo suma los permisos pedidos a los que ya tenía.
GET http://127.0.0.1:53682/callback?code=…&state=…
  • Comprueba que state es exactamente el que enviaste. Si no, descarta la respuesta.
  • Si llega error, no hay código. access_denied es una respuesta normal: la persona dijo que no.
  • Responde al navegador con una página sencilla («Ya puedes volver a la aplicación») y cierra el servidor local.

El código dura 60 segundos y sirve una sola vez. Canjéalo en cuanto llegue.

Ventana de terminal
curl -X POST https://api.lectoresbeta.com/api/v1/oauth/token \
-d grant_type=authorization_code \
-d client_id=TU_CLIENT_ID \
-d code=EL_CODIGO \
-d redirect_uri=http://127.0.0.1:53682/callback \
-d code_verifier=TU_VERIFICADOR

El cuerpo va como formulario (application/x-www-form-urlencoded), no como JSON, y la redirect_uri tiene que ser la misma que usaste al abrir la autorización.

{
"access_token": "8f2c…",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "41d9…",
"scope": "works:read works:write feedback:read credits:read"
}

scope es lo que la persona concedió: compruébalo en vez de suponerlo.

Si el código se presenta dos veces, damos por hecho que se ha filtrado y revocamos todos los tokens emitidos con él. Tu aplicación tendría que volver a pedir autorización.

Ventana de terminal
curl https://api.lectoresbeta.com/api/v1/connect/me \
-H "Authorization: Bearer EL_ACCESS_TOKEN"

Los tokens son opacos: no intentes decodificarlos ni deducir nada de su forma. Solo valen en /api/v1/connect/…; en cualquier otra ruta de la API reciben 401.

Ventana de terminal
curl -X POST https://api.lectoresbeta.com/api/v1/oauth/token \
-d grant_type=refresh_token \
-d client_id=TU_CLIENT_ID \
-d refresh_token=EL_REFRESH_TOKEN

La respuesta tiene la misma forma que el canje, con un par nuevo. El token de refresco que enviaste ya no vale.

Dos reglas que hay que respetar sí o sí:

  • Guarda el nuevo token de refresco antes de hacer nada más. Si lo pierdes, la persona tendrá que volver a autorizar.
  • No renueves dos veces a la vez con el mismo token. Si tu aplicación tiene varios hilos o ventanas, serializa la renovación. Un token de refresco ya usado que se presenta de nuevo significa que dos partes lo tienen, y en ese caso revocamos toda la familia de tokens de esa autorización, también el par que acabas de recibir.

Puedes pedir menos permisos al renovar con scope (por ejemplo -d scope=works:read); nunca más de los concedidos (invalid_scope).

Ventana de terminal
curl -X POST https://api.lectoresbeta.com/api/v1/oauth/revoke \
-d client_id=TU_CLIENT_ID \
-d token=EL_REFRESH_TOKEN

Revocar cualquiera de los dos tokens revoca todos los tokens de esa autorización. La respuesta es 200 aunque el token no exista (RFC 7009).

La autorización en sí se mantiene: tu aplicación sigue apareciendo en la lista de aplicaciones conectadas de la persona, y para volver a entrar pasará por el navegador otra vez.

Qué Dura
Petición de autorización 10 minutos
Código de autorización 60 segundos, un solo uso
Token de acceso 1 hora
Token de refresco 30 días, un solo uso (rota al renovar)

Mientras la persona use tu aplicación al menos una vez cada 30 días, no tendrá que volver a autorizar.

Todo esto surte efecto en la siguiente petición, sin esperar a que nada caduque:

  • la persona retira el acceso en Configuración → Aplicaciones conectadas;
  • desactivamos tu aplicación;
  • la cuenta de la persona queda bloqueada o se borra;
  • se detecta la reutilización de un código o de un token de refresco.

Cambiar la contraseña no desconecta las aplicaciones: no la conocen.

Qué hacer: ante un 401 con WWW-Authenticate: Bearer error="invalid_token", renueva una vez. Si la renovación responde invalid_grant, la autorización ya no vale: borra los tokens guardados y vuelve a empezar el flujo.

  • Aplicación de escritorio: en el almacén seguro del sistema operativo (Keychain en macOS, Credential Manager en Windows, Secret Service / libsecret en Linux). Nunca en ficheros de configuración en claro.
  • Aplicación alojada en la web: en tu servidor, cifrados y asociados a tu usuario. Nunca en el navegador.
  • Nunca en logs, informes de errores ni analíticas: ni los tokens, ni el código, ni el verificador.

Los tres endpoints de /oauth comparten un límite de 60 peticiones cada 5 minutos por dirección IP. Una aplicación que se comporta bien hace unas pocas por hora. Al superarlo se responde 429 con Retry-After.

Ejemplo completo (aplicación de escritorio)

Sección titulada «Ejemplo completo (aplicación de escritorio)»

Un ejemplo mínimo en Python, solo con la biblioteca estándar, para entender las piezas. No es código de producción: no guarda los tokens en el almacén seguro ni gestiona reintentos.

import base64, hashlib, http.server, json, secrets, urllib.parse, urllib.request, webbrowser
API = "https://api.lectoresbeta.com/api/v1"
CLIENT_ID = "TU_CLIENT_ID"
SCOPE = "works:read works:write feedback:read credits:read"
verifier = secrets.token_urlsafe(64)[:96]
challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
state = secrets.token_urlsafe(16)
received = {}
class Callback(http.server.BaseHTTPRequestHandler):
def do_GET(self):
query = urllib.parse.urlparse(self.path).query
received.update({k: v[0] for k, v in urllib.parse.parse_qs(query).items()})
self.send_response(200)
self.send_header("Content-Type", "text/html; charset=utf-8")
self.end_headers()
self.wfile.write("Ya puedes volver a la aplicación.".encode())
def log_message(self, *args):
pass
server = http.server.HTTPServer(("127.0.0.1", 0), Callback)
redirect_uri = f"http://127.0.0.1:{server.server_port}/callback"
webbrowser.open(f"{API}/oauth/authorize?" + urllib.parse.urlencode({
"client_id": CLIENT_ID, "redirect_uri": redirect_uri, "response_type": "code",
"scope": SCOPE, "state": state, "code_challenge": challenge, "code_challenge_method": "S256",
}))
server.handle_request()
assert received.get("state") == state, "state no coincide"
assert "code" in received, f"sin código: {received}"
form = urllib.parse.urlencode({
"grant_type": "authorization_code", "client_id": CLIENT_ID, "code": received["code"],
"redirect_uri": redirect_uri, "code_verifier": verifier,
}).encode()
with urllib.request.urlopen(urllib.request.Request(f"{API}/oauth/token", data=form)) as response:
tokens = json.load(response)
print(tokens["scope"], tokens["expires_in"])

Última actualización: