Patterns d'authentification dlt

L’authentification est la partie la plus spécifique à chaque API dans tout pipeline. dlt embarque des implémentations pour les patterns que vous rencontrerez dans les APIs de production réelles, ainsi qu’un point d’extension pour ceux qui ne correspondent pas.

Stratégies d’authentification intégrées

Toutes les classes d’authentification se trouvent dans dlt.sources.helpers.rest_client.auth. Importez ce dont vous avez besoin :

from dlt.sources.helpers.rest_client.auth import (
    BearerTokenAuth,
    ApiKeyAuth,
    HttpBasicAuth,
    OAuth2ClientCredentials
)

BearerTokenAuth — Le pattern le plus courant pour les APIs modernes. Ajoute un header Authorization: Bearer <token> à chaque requête.

client = RESTClient(
    base_url="https://api.example.com",
    auth=BearerTokenAuth(token=dlt.secrets["api_token"])
)

Le pattern dlt.secrets["api_token"] lit depuis votre configuration de secrets — ne codez jamais les tokens en dur. Voir Gestion des secrets dlt pour savoir où les stocker et l’ordre de priorité que dlt utilise pour les trouver.

ApiKeyAuth — Pour les APIs qui attendent une clé API dans un header ou un paramètre de requête.

# Clé dans le header
client = RESTClient(
    base_url="https://api.example.com",
    auth=ApiKeyAuth(
        name="X-API-Key",
        api_key=dlt.secrets["api_key"],
        location="header"
    )
)

# Clé dans le paramètre de requête
client = RESTClient(
    base_url="https://api.example.com",
    auth=ApiKeyAuth(
        name="api_key",
        api_key=dlt.secrets["api_key"],
        location="query"
    )
)

HttpBasicAuth — Authentification par nom d’utilisateur et mot de passe. Moins courante dans les APIs modernes, mais encore présente dans les outils internes, les systèmes legacy et certains produits SaaS d’entreprise.

client = RESTClient(
    base_url="https://api.example.com",
    auth=HttpBasicAuth(
        username=dlt.secrets["username"],
        password=dlt.secrets["password"]
    )
)

OAuth2ClientCredentials — OAuth2 serveur à serveur. Le client échange client_id et client_secret contre un token d’accès, puis utilise ce token pour les requêtes API. dlt gère l’acquisition et l’expiration du token automatiquement.

client = RESTClient(
    base_url="https://api.example.com",
    auth=OAuth2ClientCredentials(
        access_token_url="https://api.example.com/oauth/token",
        client_id=dlt.secrets["client_id"],
        client_secret=dlt.secrets["client_secret"]
    )
)

C’est le flux utilisé par la plupart des APIs d’entreprise : Google Ads, Salesforce, beaucoup d’outils CRM. Le flux client credentials (par opposition au flux authorization code) est approprié pour les accès machine à machine sans implication d’un utilisateur.

Authentification déclarative dans REST API Source

Lors de l’utilisation de REST API Source, l’authentification est configurée à l’intérieur du bloc client de votre dictionnaire de configuration :

config = {
    "client": {
        "base_url": "https://api.example.com/v1",
        "auth": {
            "type": "bearer",
            "token": dlt.secrets["api_token"]
        }
    },
    ...
}

Le champ type correspond aux classes d’authentification intégrées : "bearer", "api_key", "http_basic", "oauth2_client_credentials". REST API Source applique la configuration d’authentification à chaque endpoint de la source sauf si elle est remplacée au niveau de l’endpoint.

Étendre pour les flux non standards

Les APIs réelles ne suivent pas toujours les patterns standards. Rotation des tokens de rafraîchissement, types de grant personnalisés, flux d’authentification en plusieurs étapes, tokens intégrés dans les corps de requête — tout cela existe dans la réalité.

Quand vous rencontrez un flux non standard, étendez la classe de base la plus proche et ne remplacez que ce qui diffère :

from dlt.sources.helpers.rest_client.auth import OAuth2ClientCredentials

class CustomOAuth(OAuth2ClientCredentials):
    def build_access_token_request(self):
        # Remplacer la construction de la requête de token pour un type de grant non standard
        return {
            "grant_type": "custom_grant",
            "client_id": self.client_id,
            "client_secret": self.client_secret,
            "scope": "read:all"
        }

Vous héritez de toute la gestion du cache de tokens et de l’expiration depuis la classe de base. Votre remplacement ne change que le comportement spécifique qui est non standard. C’est significativement moins de travail qu’implémenter l’authentification depuis zéro, et le résultat reste dans la mécanique de dlt plutôt que de devenir un wrapper sur mesure.

Authentification en pratique

Quelques points à surveiller :

Ne codez jamais les credentials en dur. Jamais. Utilisez dlt.secrets pour les récupérer depuis votre configuration de secrets. dlt vous dira exactement quelle clé il attendait quand un secret est manquant — les messages d’erreur sont suffisamment précis pour être corrigés immédiatement.

Les tokens peuvent expirer en cours d’exécution. Pour les pipelines de longue durée qui paginent à travers des millions d’enregistrements, les tokens d’accès émis au démarrage peuvent expirer avant que le pipeline ne se termine. OAuth2ClientCredentials gère le rafraîchissement du token automatiquement. Si vous utilisez BearerTokenAuth avec un token de courte durée, vous aurez peut-être besoin de passer à OAuth2 pour supporter des exécutions de plusieurs heures.

Testez l’authentification en premier. Avant de construire la pagination et le chargement incrémental par-dessus, vérifiez que votre configuration d’authentification retourne une réponse valide. Un seul appel client.get("/some-endpoint") confirme que l’authentification fonctionne avant d’investir du temps dans le reste du pipeline.