- Los headers de PF27 conectan las solicitudes OAuth con el contexto del token, el cliente y el servidor de recursos.
- Los headers de JWT identifican la clave de firma y el algoritmo utilizados para proteger la integridad del token.
- La gestión de tokens de acceso controla el tipo de token, su duración, sus claims y el comportamiento de firma.
- Las concesiones persistentes conservan los datos de autorización más allá de la corta duración de un token de acceso.
- El flujo de pruebas utiliza un cliente configurado, Postman o una aplicación de pruebas OAuth.
Headers de PF27: qué controlan
Los headers de PF27 se entienden mejor como los metadatos de la solicitud y del token que rodean una implementación de OAuth en PingFederate. No sustituyen la concesión OAuth, el registro del cliente, el gestor de tokens de acceso ni el contrato de atributos. En su lugar, ayudan a cada componente a identificar cómo debe interpretarse una solicitud y cómo debe validarse un token.
En una configuración típica, PingFederate actúa como servidor de autorización. Un cliente OAuth solicita autorización o un token, mientras que posteriormente un servidor de recursos valida el token de acceso resultante. Los headers y claims involucrados en ese intercambio deben ser coherentes con la concesión seleccionada, la configuración de firma y las expectativas del cliente.
| Área | Responsabilidad principal | Enfoque de configuración |
|---|---|---|
| Solicitud OAuth | Transporta el contexto del cliente y de la concesión | ID de cliente, URI de redirección, scope, tipo de respuesta |
| Respuesta de autorización | Devuelve un resultado de autorización | Código, state, gestión de la redirección |
| Token de acceso | Demuestra la autorización delegada | Tipo de token, duración, claims, issuer |
| Header JWT | Describe la protección del token | Algoritmo e ID de clave |
| Solicitud al recurso | Presenta el token de acceso a una API | Esquema de autorización y token bearer |
Contexto de la solicitud
Las solicitudes OAuth identifican el cliente, la concesión solicitada, el destino de redirección y el scope solicitado. Valida estos valores antes de probar la emisión de tokens.
Protección JWT
Un JWT firmado normalmente contiene un identificador de algoritmo y una referencia a la clave en su header protegido. El servicio receptor utiliza estos valores para localizar la clave de verificación.
Asignación del token
La asignación del token de acceso transfiere valores como el nombre de usuario, el correo electrónico, el nombre, el apellido o los grupos al contrato del token.
Trata los headers, los claims y los atributos del contrato como capas independientes. Un JWT correctamente firmado puede seguir fallando en la autorización si su subject, audience, scope o atributos de usuario asignados no coinciden con las expectativas del servidor de recursos.
Objetos OAuth principales detrás de los headers
El flujo de trabajo más fiable para los headers de PF27 comienza con los objetos OAuth subyacentes. El almacenamiento de concesiones persistentes, la asignación de concesiones del contrato de políticas, la gestión de tokens de acceso y la asignación de tokens de acceso cumplen funciones diferentes. Configurarlos en el orden correcto reduce los errores de validación confusos.
Una concesión persistente almacena información relacionada con la autorización durante un periodo más largo que el de un token de acceso de corta duración. Su vigencia puede estar controlada por la inactividad, la duración máxima, la expiración, la revocación o las reglas de limpieza. PingFederate puede utilizar una base de datos o un servidor de directorio para el almacenamiento a largo plazo, mientras que la opción HSQLDB interna es más adecuada para pruebas que para cargas de trabajo de producción.
| Objeto OAuth | Qué almacena o controla | Por qué es importante |
|---|---|---|
| Concesión persistente | Datos de autorización de larga duración | Admite solicitudes de tokens posteriores y la continuidad de la concesión |
| Contrato de concesión persistente | Atributos de usuario y autorización | Define los valores retenidos con la concesión |
| Asignación de concesiones del contrato de políticas | Asigna los resultados de autenticación a los datos de la concesión | Conecta al usuario autenticado con la autorización OAuth |
| Gestor de tokens de acceso | Emite y valida tokens de acceso | Define el tipo de token, la duración y el comportamiento de firma |
| Asignación de tokens de acceso | Completa el contrato de atributos del token | Coloca los valores de identidad en el token |
Almacenamiento de concesiones persistentes
El almacenamiento de concesiones persistentes debe seleccionarse según el entorno. Una base de datos integrada puede ser útil durante una prueba de concepto local, pero las implementaciones de producción generalmente requieren una base de datos o un servicio de directorio duradero, con procedimientos operativos de copia de seguridad, control de acceso y mantenimiento.
La duración de la concesión también debe planificarse cuidadosamente. Un tiempo de espera por inactividad puede eliminar las concesiones después de un periodo sin actividad, mientras que una duración máxima establece el límite superior de validez de la concesión. El comportamiento de revocación y limpieza debe probarse antes de trasladar un cliente más allá del entorno de desarrollo.
Asignación de concesiones del contrato de políticas
La asignación de concesiones del contrato de políticas conecta el contrato de políticas de autenticación con el contrato de concesión persistente. La asignación puede incluir una clave de usuario, como un nombre de usuario o una dirección de correo electrónico. También puede transportar valores que la asignación de tokens de acceso necesitará posteriormente.
| Valor de asignación | Propósito habitual | Pregunta de revisión |
|---|---|---|
| Nombre de usuario | Identificador de usuario estable | ¿El valor es único en el directorio? |
| Correo electrónico | Identidad para el usuario o para auditoría | ¿El valor se completa de forma coherente? |
| Nombre | Claim de perfil | ¿Lo requiere el cliente o la API? |
| Apellido | Claim de perfil | ¿El atributo del directorio utiliza el nombre esperado? |
| Grupos | Datos de autorización o derechos | ¿Los valores de grupo están filtrados y delimitados correctamente? |
No consideres una base de datos de pruebas local como un plan de almacenamiento para producción. Confirma la retención, limpieza, replicación, copia de seguridad y revocación de las concesiones antes de utilizar concesiones persistentes en un entorno activo.
Configuración del gestor de tokens de acceso y del header JWT
El gestor de tokens de acceso es el punto de configuración central para la emisión y validación de tokens. Un gestor basado en JWT define cómo se firma el token, cuánto tiempo permanece válido y qué claims o atributos se incluyen. El header protegido del JWT normalmente identifica el algoritmo de firma mediante alg y la clave de firma mediante kid.
Una configuración habitual utiliza un certificado X.509 para la firma basada en RSA o en curvas elípticas. El certificado de firma activo debe estar disponible para el gestor de tokens, y los servicios que validan el token deben poder localizar la clave pública correspondiente.
| Configuración de JWT o del token | Función | Revisión práctica |
|---|---|---|
| Tipo de token | Determina el formato del token | Confirma que el cliente y la API admiten JWT |
| Certificado de firma | Firma el token | Comprueba la validez, la confianza y la planificación de la rotación |
| ID de clave | Identifica la clave de firma activa | Asegúrate de que el verificador pueda seleccionar la clave pública correspondiente |
| Algoritmo JWS | Protege la integridad del token | Utiliza un algoritmo compatible con todos los participantes |
| Duración del token | Establece la validez del token de acceso | Mantenla alineada con el riesgo de la aplicación |
| Claim issuer | Identifica al emisor del token | Haz coincidir el valor con el esperado por el servidor de recursos |
| Endpoint JWKS | Publica las claves de verificación | Utiliza una ruta de endpoint única y accesible |
Secuencia de configuración recomendada
Crea el gestor de tokens de acceso
Abre el área de gestión de tokens de acceso OAuth y crea una instancia con nombre. Selecciona el tipo de token requerido por la integración, como un JSON Web Token, y registra el nombre de la instancia para la asignación posterior.
Añade el certificado de firma
Añade o selecciona el certificado utilizado para firmar los tokens. Asigna el certificado de firma activo o el ID de clave y confirma que su clave pública pueda distribuirse a los validadores de tokens.
Establece la duración del token
Elige una duración adecuada para el cliente y la API. Una duración corta puede limitar la exposición, mientras que el comportamiento de actualización o de la concesión debe gestionar la autorización continua cuando sea compatible.
Define los claims del JWT
Configura la información del issuer y amplía el contrato de atributos con valores como el nombre de usuario, el correo electrónico, los grupos o el subject. Incluye únicamente los claims necesarios para la integración.
Guarda y replica
Guarda el gestor de tokens de acceso y replica la configuración en el clúster cuando utilices un entorno PingFederate agrupado. Después, prueba la emisión y la validación.
El valor kid requiere especial atención durante la rotación de certificados. Un servidor de recursos puede recibir un token nuevo antes de que se actualice su caché de claves. Publicar un endpoint JWKS estable y planificar un periodo de solapamiento entre las claves antiguas y las nuevas puede reducir los fallos de validación evitables.
Antes de solucionar problemas en el código de la aplicación, inspecciona el header JWT decodificado y confirma los valores alg y kid. Después, verifica que la clave pública referenciada esté disponible mediante la configuración esperada del conjunto de claves.
Asignación de tokens de acceso y pruebas de solicitudes
Después de crear el gestor de tokens de acceso, la asignación de tokens de acceso completa su contrato de atributos. Selecciona el contrato de políticas de autenticación correspondiente y asigna sus valores al gestor de tokens. En este punto, los atributos del directorio o los resultados de autenticación se convierten en claims utilizables del token.
Una asignación práctica puede incluir un nombre de usuario como subject, una dirección de correo electrónico para la identidad y grupos para las decisiones de autorización. Los nombres exactos de los atributos dependen del contrato de políticas y del esquema del directorio configurados, por lo que la asignación debe verificarse en lugar de asumirse.
| Atributo del token | Fuente sugerida | Objetivo de validación |
|---|---|---|
| Subject | Contrato de políticas de autenticación | Identifica al propietario autorizado del recurso |
| Nombre de usuario | Contrato de políticas de autenticación | Coincide con la clave de usuario de la aplicación |
| Correo electrónico | Directorio o contrato de políticas | Proporciona un valor de identidad coherente |
| Nombre | Directorio o contrato de políticas | Admite aplicaciones conscientes del perfil |
| Apellido | Directorio o contrato de políticas | Admite necesidades de visualización o auditoría |
| Grupos | Directorio o contrato de políticas | Admite una lógica de autorización controlada |
Lista de comprobación de validación de headers
Antes de probar:
- Confirma el ID de cliente, la URI de redirección y la concesión OAuth seleccionada
- Verifica que el gestor de tokens de acceso utilice el certificado de firma previsto
- Comprueba que los valores alg y kid del JWT coincidan con la clave de verificación publicada
- Confirma que las asignaciones de subject, nombre de usuario, correo electrónico y grupos estén completas
- Prueba la expiración y revocación del token, así como el comportamiento de las concesiones persistentes
Al realizar pruebas con Postman o una aplicación de pruebas OAuth, comienza con una concesión y un cliente. Los flujos de código de autorización y de código de autorización con PKCE requieren una gestión cuidadosa de la redirección y del verifier. Las pruebas de credenciales de cliente son más directas porque representan la identidad de una aplicación y no la de un usuario final. Las credenciales de contraseña del propietario del recurso y los flujos implícitos solo deben probarse cuando los requisitos de seguridad de la implementación los admitan explícitamente.
| Etapa de prueba | Qué enviar o inspeccionar | Resultado esperado |
|---|---|---|
| Registro del cliente | ID de cliente, secreto, URI de redirección | El cliente es reconocido |
| Solicitud de autorización | Tipo de respuesta, scope, state | La autorización continúa correctamente |
| Solicitud de token | Tipo de concesión, código, verifier o secreto | El endpoint de tokens emite un token |
| Inspección del JWT | Header, claims, expiración | Los valores coinciden con los contratos configurados |
| Solicitud a la API | Token de acceso bearer | El servidor de recursos lo acepta o lo rechaza claramente |
| Prueba de expiración | Token expirado o concesión revocada | El acceso se deniega con un error útil |
Cambia una sola variable cada vez. Si falla una solicitud de token, confirma primero los parámetros del cliente y de la concesión. Si la emisión tiene éxito pero la API rechaza el token, inspecciona por separado el header JWT, el issuer, el subject, la audience, la expiración y la clave de firma.
Solución de problemas de los headers de PF27
La mayoría de los fallos relacionados con headers OAuth pertenecen a un pequeño número de categorías: la solicitud no coincide con el cliente registrado, el gestor de tokens no puede firmar o validar el token, el contrato de asignación está incompleto o el servidor de recursos no puede localizar la clave de verificación correcta.
Utiliza la tabla de síntomas siguiente para acotar el problema antes de cambiar varios valores de configuración.
| Síntoma | Causa probable | Primera comprobación |
|---|---|---|
| Falla la autenticación del cliente | ID de cliente, secreto o método incorrecto | Compara el cliente registrado con la solicitud |
| Error de redirección | La URI de redirección no coincide | Comprueba exactamente el esquema, host, ruta y puerto |
| Se emite el token, pero la API lo rechaza | Los claims o la firma no coinciden | Inspecciona el issuer, subject, audience, expiración y clave |
| No se puede verificar la firma JWT | kid incorrecto o clave pública no disponible | Comprueba el endpoint JWKS y el certificado |
| Los claims del usuario están vacíos | Asignación de atributos incompleta | Revisa las asignaciones de políticas y de tokens de acceso |
| La concesión desaparece inesperadamente | Tiempo de espera por inactividad, duración máxima o limpieza | Revisa la configuración de las concesiones persistentes |
| Los nodos del clúster se comportan de forma diferente | La configuración no se replicó | Compara y replica la configuración del clúster |
Mantén un registro escrito de los valores esperados para cada entorno. Como mínimo, documenta el issuer, el endpoint de tokens, el endpoint de autorización, la ubicación de JWKS, el algoritmo de firma, el ID de clave activo, la duración del token, el identificador del cliente, la URI de redirección y los claims obligatorios.
Referencias autorizadas revisadas el 2026-11-08:
Decodifica los tokens únicamente en un entorno controlado y evita colocar secretos reales o tokens de producción en herramientas públicas. Un token decodificado no demuestra que sea válido; la firma, el issuer, la audience, la expiración y las comprobaciones de autorización siguen siendo importantes.
Preguntas frecuentes sobre los headers de PF27
Q: ¿Para qué se utilizan los headers de PF27?
Los headers de PF27 describen contexto importante de OAuth y JWT, incluidos el algoritmo de firma y la identificación de la clave. Funcionan junto con la configuración del cliente, la gestión de tokens de acceso, la asignación de atributos y la validación del servidor de recursos.
Q: ¿Qué valores del header JWT debo inspeccionar primero?
Comienza con alg y kid. El valor alg identifica el método de firma, mientras que kid identifica la clave de firma. Después, inspecciona los claims del token y confirma que la clave pública correspondiente esté disponible para el validador.
Q: ¿Por qué un token correctamente firmado puede seguir fallando en la API?
Una firma válida solo demuestra que el token fue firmado por una clave de confianza. La API todavía puede rechazar un issuer, audience, subject, scope o valor de expiración incorrectos, un claim faltante o un grupo no autorizado.
Q: ¿El almacenamiento de concesiones persistentes es lo mismo que el almacenamiento de tokens de acceso?
No. Una concesión persistente conserva datos relacionados con la autorización y puede durar más que un token de acceso. El gestor de tokens de acceso emite y valida los tokens, mientras que el almacenamiento de concesiones permite la continuidad, la revocación y otros comportamientos de autorización relacionados.
Nunca apruebes una integración OAuth únicamente porque se haya emitido un token. Confirma conjuntamente el contrato del token, la verificación de la firma, el comportamiento de expiración, el ciclo de vida de la concesión y las decisiones de autorización del servidor de recursos.