- Les en-têtes PF27 relient les requêtes OAuth au contexte des jetons, du client et du serveur de ressources.
- Les en-têtes JWT identifient la clé de signature et l’algorithme utilisés pour protéger l’intégrité du jeton.
- La gestion des jetons d’accès contrôle le type de jeton, sa durée de validité, ses revendications et son comportement de signature.
- Les autorisations persistantes conservent les données d’autorisation au-delà de la courte durée de vie d’un jeton d’accès.
- Le processus de test utilise un client configuré, Postman ou une application de test OAuth.
En-têtes PF27 : ce qu’ils contrôlent
Les en-têtes PF27 doivent être compris comme les métadonnées de requête et de jeton qui entourent un déploiement OAuth dans PingFederate. Ils ne remplacent ni l’autorisation OAuth, ni l’enregistrement du client, ni le gestionnaire de jetons d’accès, ni le contrat d’attributs. Ils aident plutôt chaque composant à déterminer comment interpréter une requête et comment valider un jeton.
Dans une configuration classique, PingFederate joue le rôle de serveur d’autorisation. Un client OAuth demande une autorisation ou un jeton, tandis qu’un serveur de ressources valide ensuite le jeton d’accès obtenu. Les en-têtes et les revendications impliqués dans cet échange doivent être cohérents avec l’autorisation sélectionnée, la configuration de signature et les attentes du client.
| Domaine | Responsabilité principale | Point de configuration |
|---|---|---|
| Requête OAuth | Transporte le contexte du client et de l’autorisation | ID client, URI de redirection, portée, type de réponse |
| Réponse d’autorisation | Retourne un résultat d’autorisation | Code, état, gestion de la redirection |
| Jeton d’accès | Prouve l’autorisation déléguée | Type de jeton, durée de vie, revendications, émetteur |
| En-tête JWT | Décrit la protection du jeton | Algorithme et ID de clé |
| Requête de ressource | Présente le jeton d’accès à une API | Schéma d’autorisation et jeton porteur |
Contexte de la requête
Les requêtes OAuth identifient le client, l’autorisation demandée, la destination de redirection et la portée demandée. Validez ces valeurs avant de tester l’émission des jetons.
Protection JWT
Un JWT signé contient généralement un identifiant d’algorithme et une référence de clé dans son en-tête protégé. Le service récepteur utilise ces valeurs pour localiser la clé de vérification.
Mappage des jetons
Le mappage des jetons d’accès transfère des valeurs telles que le nom d’utilisateur, l’adresse e-mail, le prénom, le nom ou les groupes dans le contrat du jeton.
Traitez les en-têtes, les revendications et les attributs du contrat comme des couches distinctes. Un JWT correctement signé peut tout de même échouer à l’autorisation si son sujet, son audience, sa portée ou ses attributs utilisateur mappés ne correspondent pas aux attentes du serveur de ressources.
Objets OAuth principaux derrière les en-têtes
Le processus de configuration des en-têtes PF27 le plus fiable commence par les objets OAuth sous-jacents. Le stockage des autorisations persistantes, le mappage du contrat de stratégie vers le contrat d’autorisation, la gestion des jetons d’accès et le mappage des jetons d’accès remplissent chacun une fonction différente. Les configurer dans le bon ordre réduit les erreurs de validation difficiles à interpréter.
Une autorisation persistante stocke les informations liées à l’autorisation pendant une période plus longue que la durée de vie d’un jeton d’accès de courte durée. Sa durée de vie peut être contrôlée par des règles d’inactivité, de durée maximale, d’expiration, de révocation ou de nettoyage. PingFederate peut utiliser une base de données ou un serveur d’annuaire pour le stockage à long terme, tandis que l’option HSQLDB interne convient davantage aux tests qu’aux charges de production.
| Objet OAuth | Ce qu’il stocke ou contrôle | Pourquoi c’est important |
|---|---|---|
| Autorisation persistante | Données d’autorisation à long terme | Prend en charge les demandes de jetons ultérieures et la continuité de l’autorisation |
| Contrat d’autorisation persistante | Attributs utilisateur et d’autorisation | Définit les valeurs conservées avec l’autorisation |
| Mappage du contrat de stratégie vers l’autorisation | Mappe les résultats d’authentification aux données d’autorisation | Relie l’utilisateur authentifié à l’autorisation OAuth |
| Gestionnaire de jetons d’accès | Émet et valide les jetons d’accès | Définit le type de jeton, sa durée de vie et son comportement de signature |
| Mappage des jetons d’accès | Satisfait le contrat d’attributs du jeton | Place les valeurs d’identité dans le jeton |
Stockage des autorisations persistantes
Le stockage des autorisations persistantes doit être choisi en fonction de l’environnement. Une base de données intégrée peut être utile lors d’une démonstration locale, mais les déploiements de production nécessitent généralement une base de données ou un service d’annuaire durable, avec des procédures opérationnelles de sauvegarde, de contrôle d’accès et de maintenance.
La durée de vie de l’autorisation doit également être planifiée avec soin. Un délai d’inactivité peut supprimer les autorisations après une période sans activité, tandis qu’une durée de vie maximale fixe une limite supérieure à leur validité. Le comportement de révocation et de nettoyage doit être testé avant de faire sortir un client de l’environnement de développement.
Mappage du contrat de stratégie vers l’autorisation
Le mappage du contrat de stratégie vers l’autorisation relie le contrat de stratégie d’authentification au contrat d’autorisation persistante. Le mappage peut inclure une clé utilisateur telle qu’un nom d’utilisateur ou une adresse e-mail. Il peut également transporter des valeurs nécessaires ultérieurement au mappage des jetons d’accès.
| Valeur mappée | Objectif habituel | Question de contrôle |
|---|---|---|
| Nom d’utilisateur | Identifiant utilisateur stable | La valeur est-elle unique dans l’annuaire ? |
| Identité destinée à l’utilisateur ou aux audits | La valeur est-elle renseignée de manière cohérente ? | |
| Prénom | Revendication de profil | Est-il requis par le client ou l’API ? |
| Nom | Revendication de profil | L’attribut de l’annuaire utilise-t-il le nom attendu ? |
| Groupes | Données d’autorisation ou d’habilitation | Les valeurs des groupes sont-elles filtrées et correctement limitées ? |
Ne considérez pas une base de données de test locale comme une solution de stockage de production. Confirmez la conservation, le nettoyage, la réplication, la sauvegarde et la révocation des autorisations avant d’utiliser des autorisations persistantes dans un environnement actif.
Gestionnaire de jetons d’accès et configuration de l’en-tête JWT
Le gestionnaire de jetons d’accès est le point central de configuration pour l’émission et la validation des jetons. Un gestionnaire basé sur les JWT définit la manière dont le jeton est signé, sa durée de validité et les revendications ou attributs inclus. L’en-tête JWT protégé identifie généralement l’algorithme de signature via alg et la clé de signature via kid.
Une configuration classique utilise un certificat X.509 pour une signature basée sur RSA ou sur une courbe elliptique. Le certificat de signature actif doit être disponible pour le gestionnaire de jetons, et la clé publique correspondante doit pouvoir être découverte par les services qui valident le jeton.
| Paramètre JWT ou du jeton | Fonction | Vérification pratique |
|---|---|---|
| Type de jeton | Détermine le format du jeton | Confirmer que le client et l’API prennent en charge les JWT |
| Certificat de signature | Signe le jeton | Vérifier la validité, la confiance et la planification de la rotation |
| ID de clé | Identifie la clé de signature active | S’assurer que le validateur peut sélectionner la clé publique correspondante |
| Algorithme JWS | Protège l’intégrité du jeton | Utiliser un algorithme pris en charge par tous les participants |
| Durée de vie du jeton | Définit la durée de validité du jeton d’accès | L’aligner sur le niveau de risque de l’application |
| Revendication d’émetteur | Identifie l’émetteur du jeton | Faire correspondre la valeur attendue par le serveur de ressources |
| Point de terminaison JWKS | Publie les clés de vérification | Utiliser un chemin de point de terminaison unique et accessible |
Séquence de configuration recommandée
Créer le gestionnaire de jetons d’accès
Ouvrez la zone de gestion des jetons d’accès OAuth et créez une instance nommée. Sélectionnez le type de jeton requis par l’intégration, tel qu’un JSON Web Token, puis notez le nom de l’instance pour le mappage ultérieur.
Ajouter le certificat de signature
Ajoutez ou sélectionnez le certificat utilisé pour signer les jetons. Attribuez le certificat de signature actif ou l’ID de clé, puis confirmez que sa clé publique peut être distribuée aux validateurs de jetons.
Définir la durée de vie du jeton
Choisissez une durée de vie adaptée au client et à l’API. Une durée courte peut limiter l’exposition, tandis que le comportement d’actualisation ou d’autorisation doit gérer la continuité de l’autorisation lorsqu’elle est prise en charge.
Définir les revendications JWT
Configurez les informations de l’émetteur et étendez le contrat d’attributs avec des valeurs telles que le nom d’utilisateur, l’e-mail, les groupes ou le sujet. N’incluez que les revendications nécessaires à l’intégration.
Enregistrer et répliquer
Enregistrez le gestionnaire de jetons d’accès et répliquez la configuration sur le cluster lorsqu’un environnement PingFederate en cluster est utilisé. Testez ensuite l’émission et la validation.
La valeur kid mérite une attention particulière lors de la rotation des certificats. Un serveur de ressources peut recevoir un nouveau jeton avant l’actualisation de son cache de clés. La publication d’un point de terminaison JWKS stable et la planification d’une période de chevauchement entre les anciennes et les nouvelles clés peuvent réduire les échecs de validation évitables.
Avant de dépanner le code de l’application, inspectez l’en-tête JWT décodé et confirmez les valeurs alg et kid. Vérifiez ensuite que la clé publique référencée est disponible via la configuration de l’ensemble de clés attendu.
Mappage des jetons d’accès et test des requêtes
Une fois le gestionnaire de jetons d’accès créé, le mappage des jetons d’accès satisfait son contrat d’attributs. Sélectionnez le contrat de stratégie d’authentification concerné et mappez ses valeurs vers le gestionnaire de jetons. C’est à cette étape que les attributs de l’annuaire ou les résultats d’authentification deviennent des revendications utilisables dans le jeton.
Un mappage pratique peut inclure un nom d’utilisateur comme sujet, une adresse e-mail pour l’identité et des groupes pour les décisions d’autorisation. Les noms exacts des attributs dépendent du contrat de stratégie et du schéma d’annuaire configurés ; le mappage doit donc être vérifié plutôt que supposé.
| Attribut du jeton | Source suggérée | Objectif de validation |
|---|---|---|
| Sujet | Contrat de stratégie d’authentification | Identifie le propriétaire autorisé de la ressource |
| Nom d’utilisateur | Contrat de stratégie d’authentification | Correspond à la clé utilisateur de l’application |
| Annuaire ou contrat de stratégie | Fournit une valeur d’identité cohérente | |
| Prénom | Annuaire ou contrat de stratégie | Prend en charge les applications conscientes du profil |
| Nom | Annuaire ou contrat de stratégie | Prend en charge l’affichage ou les besoins d’audit |
| Groupes | Annuaire ou contrat de stratégie | Prend en charge une logique d’autorisation contrôlée |
Liste de contrôle de validation des en-têtes
Avant les tests :
- Confirmer l’ID client, l’URI de redirection et l’autorisation OAuth sélectionnée
- Vérifier que le gestionnaire de jetons d’accès utilise le certificat de signature prévu
- Vérifier que les valeurs alg et kid du JWT correspondent à la clé de vérification publiée
- Confirmer que les mappages du sujet, du nom d’utilisateur, de l’e-mail et des groupes sont renseignés
- Tester l’expiration et la révocation des jetons ainsi que le comportement des autorisations persistantes
Lors des tests avec Postman ou une application de test OAuth, commencez avec une seule autorisation et un seul client. Les flux de code d’autorisation et de code d’autorisation avec PKCE exigent une gestion attentive de la redirection et du vérificateur. Le test des identifiants client est plus direct, car il représente l’identité d’une application plutôt que celle d’un utilisateur final. Les identifiants de mot de passe du propriétaire de la ressource et les flux implicites ne doivent être testés que lorsqu’ils sont explicitement pris en charge par les exigences de sécurité du déploiement.
| Étape de test | Élément à envoyer ou à inspecter | Résultat attendu |
|---|---|---|
| Enregistrement du client | ID client, secret, URI de redirection | Le client est reconnu |
| Requête d’autorisation | Type de réponse, portée, état | L’autorisation se déroule correctement |
| Requête de jeton | Type d’autorisation, code, vérificateur ou secret | Le point de terminaison de jeton émet un jeton |
| Inspection du JWT | En-tête, revendications, expiration | Les valeurs correspondent aux contrats configurés |
| Requête API | Jeton d’accès porteur | Le serveur de ressources l’accepte ou le rejette clairement |
| Test d’expiration | Jeton expiré ou autorisation révoquée | L’accès est refusé avec une erreur exploitable |
Modifiez une seule variable à la fois. Si une demande de jeton échoue, confirmez d’abord les paramètres du client et de l’autorisation. Si l’émission réussit mais que l’API rejette le jeton, inspectez séparément l’en-tête JWT, l’émetteur, le sujet, l’audience, l’expiration et la clé de signature.
Dépannage des en-têtes PF27
La plupart des échecs liés aux en-têtes OAuth appartiennent à un petit nombre de catégories : la requête ne correspond pas au client enregistré, le gestionnaire de jetons ne peut pas signer ou valider le jeton, le contrat de mappage est incomplet ou le serveur de ressources ne parvient pas à localiser la bonne clé de vérification.
Utilisez le tableau des symptômes ci-dessous pour cerner le problème avant de modifier plusieurs valeurs de configuration.
| Symptôme | Cause probable | Première vérification |
|---|---|---|
| L’authentification du client échoue | ID client, secret ou méthode incorrect | Comparer le client enregistré avec la requête |
| Erreur de redirection | URI de redirection non correspondante | Vérifier précisément le schéma, l’hôte, le chemin et le port |
| Le jeton est émis mais l’API le rejette | Incohérence de revendication ou de signature | Inspecter l’émetteur, le sujet, l’audience, l’expiration et la clé |
| La signature JWT ne peut pas être vérifiée | kid incorrect ou clé publique indisponible | Vérifier le point de terminaison JWKS et le certificat |
| Les revendications utilisateur sont vides | Mappage d’attributs incomplet | Vérifier les mappages de stratégie et de jetons d’accès |
| L’autorisation disparaît de manière inattendue | Délai d’inactivité, durée maximale ou nettoyage | Vérifier les paramètres des autorisations persistantes |
| Les nœuds du cluster se comportent différemment | Configuration non répliquée | Comparer et répliquer les paramètres du cluster |
Conservez une trace écrite des valeurs attendues pour chaque environnement. Documentez au minimum l’émetteur, le point de terminaison de jeton, le point de terminaison d’autorisation, l’emplacement JWKS, l’algorithme de signature, l’ID de clé actif, la durée de vie du jeton, l’identifiant client, l’URI de redirection et les revendications requises.
Références faisant autorité consultées le 2026-11-08 :
- RFC 7515 : JSON Web Signature
- RFC 7517 : JSON Web Key
- RFC 6749 : The OAuth 2.0 Authorization Framework
Ne décodez les jetons que dans un environnement contrôlé et évitez de placer de vrais secrets ou des jetons de production dans des outils publics. Un jeton décodé ne constitue pas une preuve de validité ; la signature, l’émetteur, l’audience, l’expiration et les contrôles d’autorisation restent indispensables.
FAQ sur les en-têtes PF27
Q: À quoi servent les en-têtes PF27 ?
Les en-têtes PF27 décrivent un contexte OAuth et JWT important, notamment l’algorithme de signature et l’identification de la clé. Ils fonctionnent avec les paramètres du client, la gestion des jetons d’accès, le mappage des attributs et la validation par le serveur de ressources.
Q: Quelles valeurs de l’en-tête JWT dois-je inspecter en premier ?
Commencez par alg et kid. La valeur alg identifie la méthode de signature, tandis que kid identifie la clé de signature. Inspectez ensuite les revendications du jeton et confirmez que la clé publique correspondante est disponible pour le validateur.
Q: Pourquoi un jeton correctement signé peut-il tout de même échouer au niveau de l’API ?
Une signature valide prouve uniquement que le jeton a été signé par une clé approuvée. L’API peut encore rejeter un émetteur, une audience, un sujet ou une portée incorrects, une valeur d’expiration invalide, une revendication manquante ou un groupe non autorisé.
Q: Le stockage des autorisations persistantes est-il identique au stockage des jetons d’accès ?
Non. Une autorisation persistante conserve des données liées à l’autorisation et peut survivre à un jeton d’accès. Le gestionnaire de jetons d’accès émet et valide les jetons, tandis que le stockage des autorisations prend en charge la continuité, la révocation et les comportements d’autorisation associés.
N’approuvez jamais une intégration OAuth uniquement parce qu’un jeton a été émis. Confirmez ensemble le contrat du jeton, la vérification de la signature, le comportement à l’expiration, le cycle de vie de l’autorisation et les décisions d’autorisation du serveur de ressources.