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.
| Entorno | Emisor | Documento de descubrimiento |
|---|---|---|
| Producción | https://app.parkour.design | https://app.parkour.design/.well-known/openid-configuration |
| Pruebas | https://parkour-test.web.app | https://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:
| Capacidad | Valor actual |
|---|---|
| Tipo de respuesta | code |
| Tipos de concesión | authorization_code, refresh_token |
| Autenticación del cliente | client_secret_basic, client_secret_post |
| Firma del token de identidad | RS256 |
| Métodos PKCE | S256, plain |
| Scopes | openid, profile, email |
| Atributos | sub, 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
statede alta entropía y de un solo uso; - un
nonceOIDC 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:
- rechaza un
stateausente o inesperado; - rechaza una transacción del navegador caducada o ya consumida;
- consume la transacción para que la llamada de retorno no se pueda repetir;
- gestiona un
errorde 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:
- obtén las claves del
jwks_uridel documento de descubrimiento; - elige la clave identificada por el
kiddel JWT; - exige una firma
RS256; - exige que el emisor coincida exactamente;
- exige el client ID como audiencia;
- valida la caducidad y la hora de emisión con un pequeño margen de desfase de reloj;
- exige el
nonceoriginal; - usa
subcomo 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
| Token | Duración | Tratamiento en el cliente |
|---|---|---|
| Código de autorización | 5 minutos | Intercambiarlo una vez y no guardarlo después de usarlo |
| Token de identidad | 15 minutos | Validarlo una vez; no usarlo como token portador de una API |
| Token de acceso | 15 minutos | Guardarlo en el servidor y enviarlo solo a las API de recursos de Parkour Design |
| Token de actualización | 30 días | Cifrarlo 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_requestdel procesamiento del consentimiento redirigen a esa URL de retorno conerrory elstateoriginal; - 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
400en JSON.
Los errores del token y de la API de recursos también usan un cuerpo JSON compacto:
{"error": "invalid_grant"}
| Error | Significado |
|---|---|
invalid_client | Cliente ausente, desconocido, inactivo o autenticado incorrectamente |
invalid_redirect_uri | URI de retorno ausente o no registrada; es un código propio de la implementación actual de Parkour Design |
invalid_scope | Conjunto de scopes vacío o no aprobado |
invalid_request | Faltan campos o la combinación de PKCE no es válida |
access_denied | El usuario rechazó el consentimiento |
invalid_grant | Código o token de actualización no válido, caducado, reutilizado o vinculado incorrectamente |
unsupported_response_type | Respuesta de autorización distinta de code |
unsupported_grant_type | Tipo de concesión de token no admitido |
invalid_token | Token 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,
stateynonce, pero no los exige; los clientes de los socios deben exigirlos. - El documento de descubrimiento anuncia PKCE
plain; los clientes de los socios deben usarS256. - 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
openiden 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.