OAuth2 Client

Client OAuth2 générique pour SPIP.

Ce plugin fournit une API native permettant à d’autres plugins SPIP d’utiliser des services OAuth2 ou OpenID Connect (OIDC), sans dépendance à une bibliothèque OAuth2 externe.

Il prend en charge les flux :

• authorization_code
• refresh_token
• client_credentials

Il prend également en charge PKCE et OpenID Connect.

Le plugin est avant tout une brique technique : il ne fournit pas d’interface utilisateur pour configurer un fournisseur OAuth2. Les plugins qui l’utilisent fournissent leur propre configuration et leur propre interface si nécessaire.

Installation

Le plugin s’installe comme les autres plugins SPIP.

Pré-requis

• SPIP 4.0 ou supérieur
• PHP 8.x
• extension PHP OpenSSL
• extension PHP cURL

Aucune bibliothèque OAuth2 externe n’est nécessaire.

Configuration

OAuth2 Client ne possède pas de configuration générale obligatoire dans l’espace privé.

La configuration d’un fournisseur OAuth2 est fournie par le plugin qui utilise OAuth2 Client.

Deux possibilités sont prévues :

• utiliser le provider générique, en fournissant les endpoints et les paramètres nécessaires ;
• utiliser un provider spécifique, fourni par un plugin tiers.

Le provider générique permet notamment de configurer :

• l’endpoint d’autorisation ;
• l’endpoint de token ;
• l’identifiant et le secret du client ;
• l’URL de redirection ;
• les scopes ;
• PKCE ;
• OpenID Connect.

Utilisations

Obtenir un access token

Pour un flux utilisateur authorization_code, l’API principale est :

include_spip('inc/oauth2_client');

$token = oauth2_client_get_access_token(
    $app,
    $config,
    $mode = 'session',
    $id_user = null
);

$app est l’identifiant de la configuration OAuth2 utilisée.

Le paramètre $mode définit le contexte de stockage du token :

• session : token associé à la session courante ;
• user : token associé à un auteur SPIP ;
• cron : token technique global.

En mode user, $id_user est l’identifiant (id_auteur) de l’auteur SPIP auquel le token doit être associé.

Le token est alors stocké par OAuth2 Client et associé à cet auteur SPIP. Cette association permet notamment de retrouver ultérieurement le token et les informations d’identité qui lui sont associées avec oauth2_client_get_user().

oauth2_client_get_access_token() gère le cycle du flux authorization_code :

• récupération d’un token encore valide ;
• échange du code d’autorisation ;
• PKCE, lorsqu’il est activé ;
• validation OpenID Connect, lorsqu’elle est activée ;
• renouvellement du token avec un refresh_token ;
• stockage du token.

En mode session, l’appel peut déclencher la redirection vers le fournisseur OAuth2 lorsque l’autorisation de l’utilisateur est nécessaire.

Exemple avec le provider générique

L’exemple suivant utilise le provider générique en mode user. Le token obtenu est associé à l’auteur SPIP identifié par $id_auteur.

include_spip('inc/oauth2_client');

$token = oauth2_client_get_access_token(
    $app,
    [
        'provider'           => 'generic',
        'authorize_endpoint' => 'https://provider.example/authorize',
        'token_endpoint'     => 'https://provider.example/token',
        'client_id'          => $client_id,
        'client_secret'      => $client_secret,
        'redirect_uri'       => $redirect_uri,
        'scope'              => 'openid profile email',

        'pkce' => [
            'enabled' => true,
            'method'  => 'S256',
        ],

        'oidc' => [
            'enabled' => true,
        ],

        'issuer' => 'https://provider.example',
    ],
    'user',
    $id_auteur
);

La configuration exacte dépend du fournisseur utilisé.

Récupérer les informations d’identité

Lorsqu’un token OAuth2/OIDC a été enregistré pour un utilisateur SPIP, les informations d’identité associées à ce token peuvent être récupérées avec :

include_spip('inc/oauth2_client');

$user = oauth2_client_get_user($app, 'user', $id_auteur);

• $app : identifiant de la configuration OAuth2 utilisée ;
• 'user' : contexte dans lequel le token a été enregistré ;
• $id_auteur : identifiant (id_auteur) de l’utilisateur SPIP auquel le token est associé.

La fonction recherche le token correspondant et retourne les informations d’identité qui lui sont associées.

Lorsque le token contient un id_token OpenID Connect, les informations d’identité peuvent notamment être extraites de celui-ci :

[
    'sub'         => '',
    'email'       => '',
    'username'    => '',
    'given_name'  => '',
    'family_name' => '',
    'name'        => '',
]

Les champs disponibles dépendent des informations présentes dans l’id_token.

Fonctionnement

OAuth2 Client sépare les différentes responsabilités :

• les providers décrivent la manière de communiquer avec un fournisseur OAuth2 ;
• les grants implémentent les différents flux OAuth2 ;
• le stockage gère les tokens et le contexte des échanges ;
• les pipelines permettent aux plugins tiers d’adapter le comportement du plugin.

Providers

Un provider peut être :

• générique, avec les endpoints fournis dans la configuration ;
• spécifique, lorsqu’un fournisseur nécessite une implémentation particulière.

Un provider spécifique peut être fourni par un autre plugin sans modifier le plugin OAuth2 Client.

Grants

Les grants actuellement pris en charge sont :

• authorization_code
• refresh_token
• client_credentials

Pipelines

Trois pipelines principaux permettent aux plugins tiers d’intervenir dans le fonctionnement d’OAuth2 Client :

• oauth2_client_authorization_provider : provider utilisé pour générer l’URL d’autorisation ;
• oauth2_client_token_provider : provider utilisé pour obtenir ou rafraîchir un token ;
• oauth2_client_grant : grant utilisé pour un type de flux OAuth2.

Sécurité

Le plugin prend en charge notamment :

• génération et vérification du state ;
• stockage temporaire du contexte OAuth2 ;
• PKCE avec la méthode S256 ;
• nettoyage des contextes temporaires ;
• gestion de l’expiration et du renouvellement des tokens ;
• validation des données OpenID Connect ;
• validation cryptographique des JWT via OpenSSL.

Développement et ToDo

OAuth2 Client est conçu pour être extensible sans modifier son cœur.

Les extensions doivent privilégier :

• les providers spécifiques ;
• les grants spécifiques ;
• les pipelines prévus par le plugin.

Le provider générique permet de répondre à l’essentiel des cas d’usage sans avoir besoin d’en créer de nouveraux spécifiques. De même pour les grants fournis.