Menú de la documentación
Según el socio Última actualización: 27 de julio de 2026

Autenticación

Implementa el flujo de código de autorización, valida los tokens de identidad de Parkour Design y gestiona los tokens de actualización rotativos.

Este documento describe el flujo implementado actualmente para una aplicación confidencial de un socio que se conecta a Parkour Design. El registro de clientes y el acceso a producción requieren una aprobación técnica y de seguridad.

Contrato actual: el protocolo está desplegado y se usa en integraciones coordinadas. No es un servicio de autorización de autoservicio. Parkour Design proporciona por un canal seguro el client ID, el secreto del cliente, las URI de redirección registradas y los scopes permitidos.

Entornos y descubrimiento

Usa el descubrimiento de OpenID Connect en lugar de construir las URL de los endpoints.

EntornoEmisorDocumento de descubrimiento
Producciónhttps://app.parkour.designhttps://app.parkour.design/.well-known/openid-configuration
Pruebashttps://parkour-test.web.apphttps://parkour-test.web.app/.well-known/openid-configuration

Obtén el documento de descubrimiento al arrancar la aplicación, guárdalo en caché durante un tiempo limitado y actualízalo cuando cambien las claves de firma. Exige que el issuer devuelto coincida exactamente con el emisor configurado.

El documento de descubrimiento actual publica:

CapacidadValor actual
Tipo de respuestacode
Tipos de concesiónauthorization_code, refresh_token
Autenticación del clienteclient_secret_basic, client_secret_post
Firma del token de identidadRS256
Métodos PKCES256, plain
Scopesopenid, profile, email
Atributossub, email, email_verified, name

Usa client_secret_basic y PKCE S256. No uses plain, aunque el servidor actual lo anuncie por compatibilidad.

Requisitos previos para el registro

Envía a Parkour Design lo siguiente antes de la implementación:

  • el nombre de la aplicación y el responsable técnico;
  • las URI de redirección de pruebas y de producción;
  • los scopes solicitados y el recorrido del usuario;
  • los contactos para la entrega y la rotación de credenciales;
  • los requisitos de cierre de sesión, desvinculación de cuentas y conservación de datos.

La comparación de las URI de redirección es exacta. El esquema, el host, el puerto, la ruta, las mayúsculas y minúsculas y la barra final deben coincidir con el valor registrado. Usa una URL de retorno sin cadena de consulta ni fragmento.

El servicio actual admite clientes de servidor confidenciales. No se admiten clientes públicos solo de navegador ni nativos, porque cada solicitud de token requiere un secreto del cliente.

Secuencia de autorización

1. Crear la transacción del navegador

Genera y guarda en el servidor:

  • un valor state de alta entropía y de un solo uso;
  • un nonce OIDC de alta entropía;
  • un verificador PKCE y su desafío SHA-256;
  • el destino previsto después del inicio de sesión;
  • un tiempo de caducidad corto.

Vincula estos valores a la sesión del navegador del usuario. No pongas el secreto del cliente, el verificador ni los tokens en una URL.

2. Redirigir al usuario

Construye la URL de autorización a partir del authorization_endpoint del documento de descubrimiento:

GET {authorization_endpoint}
  ?response_type=code
  &client_id={client_id}
  &redirect_uri={url_encoded_registered_redirect_uri}
  &scope={url_encoded_approved_scopes}
  &state={state}
  &nonce={nonce}
  &code_challenge={base64url_sha256_verifier}
  &code_challenge_method=S256

Usa solo los scopes aprobados durante el registro del cliente. openid email profile es un ejemplo para cuando se han aprobado los tres scopes; pedir cualquier scope no aprobado devuelve invalid_scope.

Parkour Design autentica al usuario y le pide su consentimiento. Una respuesta correcta devuelve:

{redirect_uri}?code={authorization_code}&state={state}

Una solicitud denegada devuelve:

{redirect_uri}?error=access_denied&state={state}

3. Validar la llamada de retorno

Antes de intercambiar el código:

  1. rechaza un state ausente o inesperado;
  2. rechaza una transacción del navegador caducada o ya consumida;
  3. consume la transacción para que la llamada de retorno no se pueda repetir;
  4. gestiona un error de OAuth sin intentar el intercambio de tokens.

Los códigos de autorización caducan a los cinco minutos y solo se pueden usar una vez.

4. Intercambiar el código en el servidor

Envía una solicitud codificada como formulario desde el servidor del socio:

curl --request POST "${TOKEN_ENDPOINT}" \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=${CODE}" \
  --data-urlencode "redirect_uri=${REDIRECT_URI}" \
  --data-urlencode "code_verifier=${CODE_VERIFIER}"

El redirect_uri debe ser idéntico al valor usado en la solicitud de autorización.

Una respuesta correcta tiene actualmente esta forma:

{
  "access_token": "<signed JWT>",
  "refresh_token": "<opaque token>",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "email openid profile",
  "id_token": "<signed JWT>"
}

Las respuestas de token usan Cache-Control: no-store y Pragma: no-cache. El id_token solo se devuelve cuando se concede openid.

Validar la identidad

Valida el token de identidad antes de abrir una sesión en el sistema del socio:

  1. obtén las claves del jwks_uri del documento de descubrimiento;
  2. elige la clave identificada por el kid del JWT;
  3. exige una firma RS256;
  4. exige que el emisor coincida exactamente;
  5. exige el client ID como audiencia;
  6. valida la caducidad y la hora de emisión con un pequeño margen de desfase de reloj;
  7. exige el nonce original;
  8. usa sub como identificador estable del usuario de Parkour Design.

Atributos actuales del token de identidad:

{
  "iss": "https://app.parkour.design",
  "sub": "<opaque Parkour Design user ID>",
  "aud": "<client ID>",
  "email": "user@example.com",
  "email_verified": true,
  "name": "Example User",
  "token_use": "id_token",
  "iat": 0,
  "exp": 0,
  "nonce": "<authorization nonce>"
}

No vincules cuentas solo por el correo electrónico. Guarda iss y sub como clave de identidad externa. Trata el correo electrónico y el nombre como atributos de perfil que pueden cambiar.

UserInfo está disponible cuando el token de acceso contiene openid:

curl "${USERINFO_ENDPOINT}" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Accept: application/json"
{
  "sub": "<opaque Parkour Design user ID>",
  "email": "user@example.com",
  "email_verified": true,
  "name": "Example User"
}

Tokens de acceso y de actualización

TokenDuraciónTratamiento en el cliente
Código de autorización5 minutosIntercambiarlo una vez y no guardarlo después de usarlo
Token de identidad15 minutosValidarlo una vez; no usarlo como token portador de una API
Token de acceso15 minutosGuardarlo en el servidor y enviarlo solo a las API de recursos de Parkour Design
Token de actualización30 díasCifrarlo en reposo y sustituirlo de forma atómica después de cada actualización

Los tokens de actualización rotan con cada uso correcto:

curl --request POST "${TOKEN_ENDPOINT}" \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=${REFRESH_TOKEN}"

La respuesta contiene un nuevo token de acceso y un token de actualización que sustituye al anterior. No contiene un nuevo token de identidad. Serializa las operaciones de actualización por cada usuario y sesión del cliente, y sustituye después de forma atómica el token de actualización guardado. Reutilizar un token antiguo devuelve invalid_grant.

Parkour Design consume el token de actualización antiguo antes de devolver el nuevo. Si un tiempo de espera agotado o una respuesta perdida hacen que el resultado sea desconocido, no repitas la solicitud a ciegas con el token antiguo. Borra el estado local de los tokens e inicia un nuevo flujo de autorización. Las solicitudes de actualización simultáneas para la misma sesión crean el mismo riesgo.

La duración actual del token de actualización es deslizante: cada rotación correcta inicia un nuevo periodo de 30 días. Parkour Design no ofrece actualmente endpoints de revocación ni de introspección de tokens. Al desconectar en la aplicación del socio hay que borrar los tokens guardados. Un token de acceso puede seguir siendo válido hasta que caduquen sus 15 minutos.

Usar los tokens de acceso a la API

Los tokens de acceso de Parkour Design siempre tienen la audiencia parkour-api. Solo sirven como credenciales para las API de recursos de Parkour Design descritas en Intercambio de datos. No los reenvíes nunca a una API del socio ni a otro tercero; los recursos que gestiona el socio deben usar su propio mecanismo de autorización.

Los tokens de identidad sirven para establecer la identidad y una sesión en el sistema del socio. No uses un token de identidad para llamar a ninguna API.

Comportamiento actual de los scopes

Los scopes de identidad actuales son openid, email y profile. La API de recursos coordinada autoriza actualmente el acceso a los resúmenes de eventos y proyectos con openid; todavía no ofrece scopes de lectura específicos.

Es una limitación de la implementación actual, no un modelo para nuevas API. Los scopes solicitados y los recursos accesibles se confirman durante el registro del cliente. Los futuros contratos de recursos pueden introducir scopes específicos.

Los tokens actuales y UserInfo incluyen el correo electrónico y el nombre de forma más amplia de lo que indicarían los scopes email y profile por separado. Aun así, los clientes deben pedir solo los scopes aprobados y no deben contar con que este comportamiento más amplio se mantenga.

Gestión de errores

El endpoint de autorización tiene dos canales de error:

  • una vez validada la URI de redirección, la denegación del consentimiento y algunos errores invalid_request del procesamiento del consentimiento redirigen a esa URL de retorno con error y el state original;
  • los fallos de validación anteriores a establecer una URL de retorno de confianza, incluidos los del cliente, la URI de redirección, el scope, el tipo de respuesta y PKCE, devuelven directamente una respuesta HTTP 400 en JSON.

Los errores del token y de la API de recursos también usan un cuerpo JSON compacto:

{"error": "invalid_grant"}
ErrorSignificado
invalid_clientCliente ausente, desconocido, inactivo o autenticado incorrectamente
invalid_redirect_uriURI de retorno ausente o no registrada; es un código propio de la implementación actual de Parkour Design
invalid_scopeConjunto de scopes vacío o no aprobado
invalid_requestFaltan campos o la combinación de PKCE no es válida
access_deniedEl usuario rechazó el consentimiento
invalid_grantCódigo o token de actualización no válido, caducado, reutilizado o vinculado incorrectamente
unsupported_response_typeRespuesta de autorización distinta de code
unsupported_grant_typeTipo de concesión de token no admitido
invalid_tokenToken portador de la API ausente, mal formado, caducado o no válido

No muestres al usuario final las respuestas de token sin procesar ni los diagnósticos del protocolo. Registra un ID de correlación, el endpoint, el estado y un código de error seguro, sin registrar códigos, tokens, secretos, valores de nonce ni datos personales.

Limitaciones actuales

  • El registro de clientes y la retirada del consentimiento se coordinan a mano.
  • El servidor acepta PKCE, state y nonce, pero no los exige; los clientes de los socios deben exigirlos.
  • El documento de descubrimiento anuncia PKCE plain; los clientes de los socios deben usar S256.
  • No hay endpoints de revocación ni de introspección de tokens, registro dinámico ni cierre de sesión estándar.
  • La reutilización de un token de actualización no revoca toda la familia de tokens.
  • Los tokens de acceso siguen siendo válidos hasta su caducidad después de cerrar la sesión en local.
  • La autorización de recursos actual usa openid en lugar de scopes de recursos específicos.

Revisa estas limitaciones durante la incorporación y no sustituyas en silencio lo que se describe aquí por supuestos de otro proveedor OAuth.