Lorsque l’on met en place de l’au­then­ti­fi­ca­tion OpenID Connect (OIDC) sur son API, souvent l’in­té­gra­tion avec swag­ger (via le package Python drf-spec­ta­cu­lar) n’est pas réali­sée. Cela veut dire que votre équipe de déve­lop­pe­ment perd la capa­cité d’uti­li­ser cette inter­face pour travailler et tester les requêtes API.

Dans cet article, je vous montre comment confi­gu­rer le paquet Python drf-spec­ta­cu­lar pour ajou­ter les jetons d’au­then­ti­fi­ca­tion *OIDC* sur les requêtes émises par swag­ger.

Atten­tion, cet article ne couvre pas la mise en place d’une authen­ti­fi­ca­tion OIDC sur votre API, pour ce sujet vous devriez regar­der la librai­rie django_pyoidc.

Commen­cez par vous munir des iden­ti­fiants du client OIDC qui va servir à géné­rer des jetons. De mon côté, en géné­ral je mets en place deux clients OIDC sur mes projets Django avec une API :

• un client OIDC pour vali­der les jetons entrants
• un client OIDC pour faire de l’au­then­ti­fi­ca­tion sur le site d’ad­mi­nis­tra­tion

J’uti­lise le deuxième client OIDC côté swag­ger pour géné­rer les jetons.

1 – Modi­fi­ca­tion du fichier settings.py

Modi­fier le para­mètre SPEC­TA­CU­LAR_SETTINGS comme suit :

SPECTACULAR_SETTINGS = {
    "SWAGGER_UI_OAUTH2_CONFIG": {
        "clientId": os.getenv("SSO_CLIENT_ID"), # à modifier
        "clientSecret": os.getenv("SSO_CLIENT_SECRET"), # à modifier
        "scopes": [], # optionnel, dépend de l'authentification que vous faîtes
    },
}

2 – Ajout d’une vue pour enre­gis­trer le jeton

Pour que swag­ger puisse enre­gis­trer le jeton OIDC, il a besoin d’avoir une vue de call­back.

Cette vue doit être décla­rée dans votre fichier urls.py.

from drf_spectacular.views import (
    SpectacularAPIView,
    SpectacularSwaggerOauthRedirectView,
    SpectacularSwaggerView,
)

urlpatterns += [
    # Ces deux vues sont à configurer en regardant la doc de drf-spectacular
    path("api/schema/", SpectacularAPIView.as_view(), name="schema"),
    path(
        "api/docs/", SpectacularSwaggerView.as_view(url_name="schema"), name="swagger-ui"
    ),
    # Cette vue permet d'enregistrer le jeton OIDC côté navigateur
    path(
        "api/docs/oauth2-redirect.html", # Attention, cette vue doit être à côté de swagger-ui
        CustomSpectacularView.as_view(),
        name="swagger-ui-oauth",
    )
]

3 – Utili­sa­tion

De retour sur la page d’ac­cueil de votre swag­ger, un bouton autho­rize est dispo­nible en haut à droite.

En cliquant dessus, la popup de connexion swag­ger s’ouvre. Faîtes-la défi­ler tout en haut, jusqu’à la section « openId­Con­nect (OAuth2, autho­ri­za­tion_code) ».

Les para­mètres client_id et client_secret sont déjà rensei­gnés ! Faîtes défi­ler la popup vers le bas jusqu’à révé­ler le bouton Autho­rize qui vous redi­ri­gera vers le SSO pour vous connec­ter.

Vous pouvez désor­mais émettre des requêtes authen­ti­fiés avec OpenID Connect depuis votre docu­men­ta­tion d’API swag­ger.