Authentification OAuth2

Ce texte a été traduit à l’aide de l’IA. Si vous souhaitez consulter le texte original en anglais, cliquez ici.

OAuth2 permet aux applications d’accéder de manière sécurisée aux sites WordPress.com et Jetpack sans avoir besoin des mots de passe des utilisateurs. Il offre un contrôle précis sur ce à quoi chaque application peut accéder.

OAuth2 permet aux applications de demander uniquement les permissions spécifiques dont elles ont besoin via des « scopes ». Lorsque les utilisateurs autorisent une application, ils peuvent voir et contrôler exactement les accès qu’ils accordent.

Les utilisateurs se connectent avec leur compte WordPress.com et peuvent approuver ou refuser les permissions demandées, gardant ainsi le contrôle sur leurs données tout en connectant des applications en toute sécurité.

Prérequis

Avant de développer votre application OAuth2, vous devez avoir une application WordPress.com enregistrée avec les données suivantes :

1. Client ID : Identifie votre application
2. Client Secret : Authentifie votre application (à garder confidentiel)
3. URI de redirection : L’adresse vers laquelle les utilisateurs sont redirigés après l’autorisation

Vous pouvez obtenir ces identifiants via le gestionnaire d’applications WordPress.com.

Utilisez ce formulaire pour enregistrer une nouvelle application WordPress.com

Points de terminaison OAuth2

Si vous débutez avec OAuth2, vous pouvez en apprendre davantage sur https://oauth.net/. Pour l’intégration avec WordPress.com, vous devez comprendre les points de terminaison OAuth2 principaux disponibles sous l’espace de noms https://public-api.wordpress.com/oauth2/. Ces points de terminaison fonctionnent de manière cohérente pour les sites WordPress.com et les sites connectés à Jetpack.

Point de terminaison d’autorisation

Point de terminaison : https://public-api.wordpress.com/oauth2/authorize

Méthode : GET (via redirection utilisateur)

C’est ici que le flux OAuth2 commence. Une interface d’autorisation est présentée aux utilisateurs pour examiner et approuver les permissions demandées par votre application. Le point de terminaison valide les identifiants de votre application, l’URI de redirection, et génère des codes d’autorisation sécurisés pour l’échange de jetons.

Paramètres requis :

• client_id : l’ID client de votre application
• redirect_uri : doit correspondre à l’URI de redirection enregistrée
• response_type : « code » pour le flux par code d’autorisation ou « token » pour le flux implicite

Paramètres optionnels :

• scope : permissions séparées par des espaces (par défaut, accès à un seul blog)
• state : recommandé pour la protection contre les attaques CSRF
• blog : URL ou ID d’un blog spécifique pour un accès à un site unique

Exemple d’URL d’autorisation (flux Authorization Code) :

https://public-api.wordpress.com/oauth2/authorize?client_id=12345&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=code&scope=posts%20media&state=abc123xyz

Exemple d’URL d’autorisation (flux Implicit) :

https://public-api.wordpress.com/oauth2/authorize?client_id=12345&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=token&scope=posts%20media&state=abc123xyz

Exemple d’URL d’autorisation (blog spécifique) :

https://public-api.wordpress.com/oauth2/authorize?client_id=12345&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=code&blog=yourblog.wordpress.com&scope=posts%20media&state=abc123xyz

Réponse/Action : après approbation de l’utilisateur, redirige vers votre redirect_uri avec :

• Flux Authorization Code : ?code=AUTHORIZATION_CODE&state=YOUR_STATE
• Flux Implicit : #access_token=TOKEN&expires_in=64800&token_type=bearer&site_id=BLOG_ID
• Refus de l’utilisateur : ?error=access_denied

Remarque importante : le paramètre redirect_uri doit correspondre exactement à l’URI de redirection enregistrée lors de la création de votre application. Même des différences mineures (comme un slash final manquant) entraîneront l’échec de l’autorisation. Il s’agit d’une mesure de sécurité visant à empêcher les redirections malveillantes.

Point de terminaison de demande de jeton

Point de terminaison : https://public-api.wordpress.com/oauth2/token

Méthode : POST

Ce point de terminaison sécurisé de serveur à serveur gère deux types d’autorisation différents pour obtenir des jetons d’accès. Choisissez le type d’autorisation approprié en fonction de votre cas d’utilisation :

Authorization Code Grant (utilisation en production)

Utilisez ce type d’autorisation pour toutes les applications en production. Il échange les codes d’autorisation (reçus lors de l’autorisation de l’utilisateur) contre des jetons d’accès tout en gardant votre secret client sécurisé.

Paramètres requis :

• client_id : l’ID client de votre application
• client_secret : le secret client de votre application
• code : le code d’autorisation provenant de l’étape d’autorisation
• grant_type : doit être « authorization_code »
• redirect_uri : doit correspondre à l’URI de redirection d’autorisation

Exemple de requête :

curl -X POST https://public-api.wordpress.com/oauth2/token 
  -d "client_id=12345" 
  -d "client_secret=your_client_secret" 
  -d "code=received_authorization_code" 
  -d "grant_type=authorization_code" 
  -d "redirect_uri=https://yourapp.com/callback"

Password Grant (développement et tests uniquement)

Ce type d’autorisation permet aux propriétaires d’applications d’obtenir des jetons directement en utilisant leurs identifiants WordPress.com, en contournant le flux d’autorisation utilisateur.

Utilisez le Password Grant pour :

• Tester les points de terminaison de l’API pendant le développement
• Les tests automatisés lorsque la simulation d’autorisation utilisateur n’est pas pratique
• Le développement personnel sur vos propres sites WordPress.com

Restrictions de sécurité :

• Fonctionne uniquement avec vos propres identifiants WordPress.com (pas ceux d’autres utilisateurs)
• Nécessite d’exposer les identifiants dans votre code
• Contourne le consentement utilisateur et les avantages de sécurité d’OAuth2
• Ne jamais utiliser dans des applications en production

Paramètres requis :

• client_id : l’ID client de votre application
• client_secret : le secret client de votre application
• grant_type : doit être « password »
• username : votre nom d’utilisateur WordPress.com
• password : votre mot de passe WordPress.com (ou mot de passe d’application si la 2FA est activée)

Exemple de requête :

curl -X POST https://public-api.wordpress.com/oauth2/token 
  -d "client_id=12345" 
  -d "client_secret=your_client_secret" 
  -d "grant_type=password" 
  -d "username=your_username" 
  -d "password=your_password_or_app_password"

Authentification à deux facteurs : si la 2FA est activée, créez un mot de passe d’application dans les Réglages de votre compte WordPress.com et utilisez-le à la place de votre mot de passe habituel.

Chemin de migration : Commencez avec le Password Grant pour faciliter le développement, mais implémentez le flux Authorization Code avant de passer en production. Considérez le Password Grant comme un raccourci de développement qui doit être remplacé par une autorisation utilisateur appropriée dans les applications en production.

Format de la réponse du jeton (les deux types de Grant) :

{
    "access_token": "YOUR_API_TOKEN",
    "blog_id": "blog_id_number", 
    "blog_url": "https://yourblog.wordpress.com",
    "token_type": "bearer"
}

Point de terminaison d’information sur le jeton

Point de terminaison : https://public-api.wordpress.com/oauth2/token-info

Méthode : GET

Fournit une validation et une inspection sécurisées des jetons. Renvoie des informations détaillées sur les jetons, notamment l’ID utilisateur, l’ID du blog et les permissions de portée. Essentiel pour vérifier l’authenticité des jetons, en particulier lorsque ceux-ci sont transmis entre systèmes ou dans des applications mobiles.

Paramètres requis :

• client_id : L’ID client de votre application
• token : Le jeton d’accès à valider

Exemple de requête :

GET https://public-api.wordpress.com/oauth2/token-info?client_id=12345&token=your_access_token_here

Exemple de requête CURL :

curl "https://public-api.wordpress.com/oauth2/token-info?client_id=12345&token=your_access_token_here"

Format de la réponse (jeton valide) :

{
    "client_id": "12345",
    "user_id": "123456789",
    "blog_id": "987654321", 
    "scope": "posts,media"
}

Réponse (jeton invalide) : renvoie une erreur si le jeton n’a pas été autorisé pour votre application ou s’il est invalide.

Point de terminaison d’authentification

Point de terminaison : https://public-api.wordpress.com/oauth2/authenticate

Méthode : GET (via redirection utilisateur)

Un point de terminaison spécialisé pour les applications WordPress.com Connect qui nécessitent uniquement une vérification d’identité utilisateur de base. Optimisé pour la fonctionnalité « Se connecter avec WordPress.com », il est conçu pour la vérification d’identité plutôt que pour la gestion de contenu.

Paramètres requis :

• client_id : l’ID client de votre application
• redirect_uri : doit correspondre à l’URI de redirection enregistrée
• response_type : utilisez « code » pour un échange sécurisé côté serveur

Paramètres optionnels :

• scope : généralement « auth » pour un accès basique au profil
• state : recommandé pour la protection contre les attaques CSRF

Exemple d’URL d’authentification :

https://public-api.wordpress.com/oauth2/authenticate?client_id=12345&redirect_uri=https%3A%2F%2Fyourapp.com%2Fauth-callback&response_type=code&scope=auth&state=random_secure_string

Réponse/Action : après approbation par l’utilisateur, une redirection est effectuée vers votre redirect_uri avec un code d’autorisation. Échangez ce code au point de terminaison de jeton pour recevoir un jeton avec une portée limitée, offrant généralement un accès uniquement à :

Accès API disponible :

• Point de terminaison /me/ pour les informations de base du profil utilisateur
• Données de vérification d’identité de l’utilisateur (ID, nom d’utilisateur, e-mail, avatar_URL, statut de vérification)

Flux de travail OAuth2

WordPress.com prend en charge deux flux OAuth2 principaux, chacun conçu pour différents types d’applications et exigences de sécurité :

Flux Authorization Code (recommandé)

Le flux Authorization Code est le flux OAuth2 standard pour les applications côté serveur où vous pouvez stocker les secrets client de manière sécurisée. Ce flux offre le niveau de sécurité le plus élevé en échangeant un code d’autorisation contre un jeton d’accès via une requête sécurisée de serveur à serveur.

Avantage en matière de sécurité : le secret client n’apparaît jamais dans le code côté client, et les jetons d’accès sont obtenus via des requêtes serveur authentifiées.

Flux Implicit (obsolète)

Le flux Implicit a été conçu pour les applications basées sur le navigateur où le jeton d’accès est renvoyé directement dans le fragment d’URL. Cependant, cette approche est désormais considérée comme moins sécurisée et a été largement abandonnée au profit d’alternatives plus sûres comme PKCE (Proof Key for Code Exchange).

Important : nous recommandons d’utiliser le flux Authorization Code dans la mesure du possible pour une sécurité renforcée.

Portées et permissions OAuth2

La puissance d’OAuth2 réside dans son système de permissions granulaire. Lors de la demande d’autorisation, vous spécifiez des portées (scopes) qui définissent exactement ce à quoi votre application peut accéder.

Portées disponibles

• users : Consulter les informations utilisateur
• sites : Consulter les informations générales et les options du site
• posts : Consulter et gérer les articles
• comments : Consulter et gérer les commentaires des articles
• taxonomy : Consulter et gérer les étiquettes et les catégories
• follow : S’abonner et se désabonner de blogs
• sharing : Connecter des services de réseaux sociaux
• freshly-pressed : Consulter les articles Fraîchement pressé
• notifications : Consulter et gérer les notifications utilisateur
• insights : Consulter les statistiques de votre application
• read : Gérer et consulter les abonnements du Lecteur
• stats : Consulter les statistiques du site
• media : Gérer les médias du site
• menus : Consulter et gérer les menus du site
• batch : Regrouper plusieurs requêtes GET en lot
• videos : Consulter les informations vidéo

Portées spéciales

• global : Accorde un accès complet aux données utilisateur sur l’ensemble des services WordPress.com et des sites connectés
• auth : Portée limitée fournissant un accès uniquement au point de terminaison /me/ pour les flux d’authentification de base. Consultez WordPress.com Connect pour plus d’informations.

Bonnes pratiques pour les portées

Suivez toujours le principe du moindre privilège :

// Request only necessary permissions
const scopes = 'posts,media'; // Not 'global' unless truly needed

Implémenter l’authentification OAuth2

Étape 1 : Requête d’autorisation

Dirigez les utilisateurs vers le point de terminaison d’autorisation avec les paramètres requis :

Paramètres requis

• client_id : L’ID client de votre application
• redirect_uri : Doit correspondre à l’URI enregistrée dans les réglages de votre application
• response_type : Utilisez « code » pour le flux Authorization Code ou « token » pour le flux Implicit

Paramètres optionnels

• blog : URL ou ID d’un blog spécifique pour un accès à un seul site
• scope : Liste de permissions demandées séparées par des espaces
• state : Paramètre de sécurité recommandé pour prévenir les attaques CSRF

Exemple d’URL d’autorisation

const authUrl = `https://public-api.wordpress.com/oauth2/authorize?` +
  `client_id=${clientId}&` +
  `redirect_uri=${encodeURIComponent(redirectUri)}&` +
  `response_type=code&` +
  `scope=posts,media&` +
  `state=${secureRandomString}`;

// // Redirect user to authorization
window.location.href = authUrl;

Étape 2 : Échange du code d’autorisation

Après l’autorisation de l’utilisateur, vous recevrez (à l’emplacement redirect_url) un code d’autorisation qui doit être échangé contre un jeton d’accès.

Échange de jeton côté serveur

Effectuez une requête POST vers le point de terminaison du jeton :

$curl = curl_init( 'https://public-api.wordpress.com/oauth2/token' );

curl_setopt( $curl, CURLOPT_POST, true );
curl_setopt( $curl, CURLOPT_POSTFIELDS, array(
    'client_id' => $your_client_id,
    'redirect_uri' => $your_redirect_url,
    'client_secret' => $your_client_secret_key,
    'code' => $_GET['code'], // The authorization code
    'grant_type' => 'authorization_code'
) );

curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1);

$auth = curl_exec( $curl );
$secret = json_decode( $auth );
$access_token = $secret->access_token;

Réponse réussie

{
    "access_token": "YOUR_API_TOKEN",
    "blog_id": "blog_id_number",
    "blog_url": "https://yourblog.wordpress.com",
    "token_type": "bearer"
}

Étape 3 : Effectuer des appels API authentifiés

Utilisez le jeton Bearer dans l’en-tête Authorization pour toutes les requêtes API :

$access_token = 'YOUR_API_TOKEN';
$curl = curl_init( 'https://public-api.wordpress.com/rest/v1/me/' );

curl_setopt( $curl, CURLOPT_HTTPHEADER, array( 'Authorization: Bearer ' . $access_token ) );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1 );

$response = curl_exec( $curl );

Fonctionnalités avancées d’OAuth2

Gestion de la portée des jetons

Les différentes portées de jetons offrent différents niveaux d’accès :

• Jetons mono-blog : Accordent l’accès à un blog spécifique
• Jetons globaux : Fournissent l’accès à tous les sites WordPress.com et sites Jetpack connectés de l’utilisateur
• Points de terminaison spécifiques à l’utilisateur : Certains points de terminaison (mentions J’aime, abonnements) fonctionnent sur tous les blogs avec n’importe quel jeton utilisateur

OAuth côté client (implicite)

Pour les applications côté client, les jetons peuvent être renvoyés dans le fragment d’URL en utilisant le flux implicite :

https://yourapp.com/callback#access_token=TOKEN&expires_in=64800&token_type=bearer&site_id=BLOG_ID

Considérations importantes :

• Les jetons expirent actuellement au bout de deux semaines
• Utilisez la valeur expires_in pour gérer le renouvellement des jetons
• Convient uniquement aux clients publics où les secrets ne peuvent pas être stockés de manière sécurisée

Validation et gestion des jetons

Gérer correctement les jetons OAuth2 est essentiel pour une application robuste. Cela inclut la validation des jetons, le traitement des réponses de l’API et la gestion élégante de l’expiration des jetons ou des permissions insuffisantes.

Point de terminaison d’information sur le jeton

Vérifiez l’authenticité du jeton à l’aide du point de terminaison d’information sur le jeton :

GET https://public-api.wordpress.com/oauth2/token-info?client_id=your_client_id&token=your_token

Réponse valide :

{
    "client_id": "your_client_id",
    "user_id": "user_id_number",
    "blog_id": "blog_id_number",
    "scope": "posts,media"
}

Développement et tests

Tests avec le Password Grant (propriétaires du client uniquement)

Les propriétaires d’applications peuvent utiliser le password grant pour obtenir le jeton d’authentification :

$curl = curl_init( 'https://public-api.wordpress.com/oauth2/token' );

curl_setopt( $curl, CURLOPT_POST, true );

curl_setopt( $curl, CURLOPT_POSTFIELDS, array(
    'client_id' => $your_client_id,
    'client_secret' => $your_client_secret_key,
    'grant_type' => 'password',
    'username' => $your_wpcom_username,
    'password' => $your_wpcom_password, // Use Application Password if 2FA enabled
) );

curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1);
$auth = curl_exec( $curl );
$auth = json_decode( $auth );
$access_token = $auth->access_token;

Important : Cette méthode nécessite un mot de passe d’application si l’authentification à deux facteurs est activée.

Bonnes pratiques de sécurité et gestion des erreurs

Directives d’implémentation

1. Validation du paramètre state : Validez toujours le paramètre state pour prévenir les attaques CSRF
2. Stockage sécurisé des tokens : Stockez les tokens d’accès de manière sécurisée en utilisant un chiffrement approprié
3. Demande de permissions minimales : Ne demandez que les permissions dont votre application a réellement besoin
4. Communication claire avec l’utilisateur : Expliquez pourquoi des permissions spécifiques sont requises
5. Gestion correcte des erreurs : Gérez les échecs d’autorisation, l’expiration des tokens et les changements de portée de manière élégante

Exigences HTTPS

Toutes les communications OAuth2 doivent utiliser HTTPS pour protéger les tokens et les codes d’autorisation lors de la transmission.

Gestion des tokens

• Stockez les tokens d’accès de manière sécurisée côté serveur
• Implémentez des mécanismes de renouvellement de tokens appropriés
• Fournissez une documentation claire sur le cycle de vie des tokens
• Gérez l’expiration des tokens de manière élégante dans votre application

Gestion des erreurs

Erreurs OAuth2 courantes et leur signification :

• access_denied : L’utilisateur a refusé l’autorisation
• invalid_client : Identifiants client non valides
• invalid_grant : Code d’autorisation non valide ou expiré
• invalid_scope : Le scope demandé est non valide ou indisponible

Implémentez toujours une gestion complète des erreurs afin de fournir aux utilisateurs des retours clairs lorsque des problèmes d’autorisation surviennent.

Conclusion

OAuth2 fournit une méthode d’authentification sécurisée et conviviale pour les intégrations WordPress.com. En mettant en œuvre une gestion appropriée des scopes, des pratiques de sécurité et une gestion des erreurs, vous pouvez créer des applications qui respectent la vie privée des utilisateurs tout en offrant des fonctionnalités puissantes. Le système de permissions granulaires garantit que les utilisateurs gardent le contrôle de leurs données tout en permettant à votre application de fournir des fonctionnalités utiles.

Pour la documentation complète des endpoints de l’API et des exemples supplémentaires, consultez la Référence de l’API REST WordPress.com.