Accès sécurisé à l’interface utilisateur Swagger avec Azure Active Directory

Dans cet article, nous allons aujourd’hui vous expliquer comment sécuriser l’accès aux interfaces Swagger pour les applications ASP.NET Core avec Azure Active Directory.

La sécurité est l’un des critères les plus importants permettant de déterminer le degré de conformité de la solution. Lorsque l’on aborde la question de la sécurité dans le contexte de l’API Web ASP.NET, le premier réflexe est de vouloir ajouter un niveau d’authentification et d’autorisation lors de l’appel des points de terminaison. Mais aujourd’hui, nous allons traiter un cas de figure reposant sur un besoin personnalisé en matière de sécurité. Dans la plupart des applications d’API Web ASP.NET, nous procédons à une intégration de Swagger pour simplifier la communication avec les différents points de terminaison. Mais imaginons qu’il est prévu que notre application passe en phase de production. Dans ce cas, nous devons penser à la sécurité de l’interface utilisateur Swagger. Pour cela, nous avons à peu près deux options :

• Activer Swagger uniquement pour les environnements de déploiement
• Ajouter une contrainte d’accès pour Swagger

La première solution est la plus simple, mais elle a l’inconvénient de désactiver complètement la fonctionnalité de Swagger. C’est pourquoi nous allons nous concentrer aujourd’hui sur la seconde.

Pour cela, voici quelques conseils :

• Autorisez l’accès au moyen d’un identifiant/mot de passe statique (ou prédéfini)
• Autorisez l’accès à un nombre limité d’adresses IP
• Autorisez l’accès à partir d’un fournisseur d’authentification

Comme vous pouvez le voir, les deux premières propositions ne sont pas dynamiques, dans la mesure où l’authentification de l’accès repose sur des données statiques. En revanche, la troisième est plus élaborée et nous donne un peu plus de flexibilité pour gérer les personnes pouvant utiliser Swagger dans un environnement de production. C’est cette option que nous allons appliquer avec Azure Active Directory en suivant trois étapes principales :

1. Configurer l’inscription d’une application dans Azure
2. Inscrire un composant d’authentification dans l’application
3. Ajouter un middleware pour gérer l’accès à l’interface utilisateur Swagger

C’est parti !

Prérequis

• Un projet d’API Web ASP.NET existant (.NET 5)
• Swagger est déjà intégré dans votre solution (Swashbuckle ou NSwag)
• Un service Azure Active Directory existant

Configurer l’inscription d’une application dans Azure

Nous pouvons considérer l’inscription d’une application dans Azure comme un représentant de notre application ASP.NET afin de déterminer si l’utilisateur en cours est authentifié ou non auprès du service Azure Active Directory. Pour configurer l’inscription d’une application, procédez de la façon suivante :

• Connectez-vous au portail Azure https://portal.azure.com/
• Dans la barre de recherche supérieure, saisissez « Azure Active Directory ».
• Dans le menu situé à gauche sur la page de présentation d’Azure Active Directory, cliquez sur Inscriptions des applications

• En haut à gauche, cliquez sur Nouvelle inscription. Vous devez ensuite remplir le formulaire permettant de créer l’inscription de votre application.

• • Indiquez le nom de l’application (par exemple : auth-iu-swagger)
  • Dans la section Qui peut utiliser cette application ou accéder à cette API, cliquez sur Comptes dans cet annuaire organisationnel uniquement.
  • Dans la section URI de redirection, indiquez l’URI vers lequel sera redirigée votre application une fois l’authentification validée (cet URI est chargé de récupérer la réponse de l’authentification). Sélectionnez Web dans la liste déroulante des plateformes et indiquez l’Uri en respectant le format suivant : {URI_de_votre_application_de_base}/signin-oidc-swagger. Vous trouverez ci-après les restrictions applicables aux URI.
  • Une fois rempli, le formulaire doit ressembler à ceci. Cliquez ensuite sur Inscrire.

• Maintenant que votre application est inscrite, nous allons configurer le type de demande à envoyer à l’URI de redirection une fois l’authentification terminée.
  • Dans le menu situé à gauche sur la page de présentation de l’inscription des applications, cliquez sur Authentification.

• • Dans la section Octroi implicite et flux hybrides, sélectionnez Jetons d’ID, comme le recommande Microsoft : « Pour les applications Web ASP.NET Core et les autres applications Web qui utilisent l’authentification hybride, sélectionnez uniquement Jetons d’ID ». Lorsque vous sélectionnez cette option, la charge utile des demandes envoyées vers l’URI de redirection (configuré précédemment) contient une propriété appelée « id_token » qui sera utilisée pour vérifier si l’utilisateur est authentifié ou non auprès du service Azure Active Directory.
  • Le formulaire doit ressembler à ceci. Cliquez ensuite sur Enregistrer.

Félicitations ! Vous venez de terminer la configuration de l’inscription de votre application. Passons maintenant à l’étape suivante.

Inscrire un composant d’authentification dans l’application

Dans l’application, nous devons inscrire un composant d’authentification susceptible de communiquer avec l’inscription d’application précédemment créée et configurée. Pour cela, nous allons utiliser l’authentification Microsoft Identity Web. Il s’agit d’une couche d’abstraction pour OpenIdConnect qui propose une couche pratique d’API à surface unique associant ASP.NET Core, son middleware d’authentification, et la bibliothèque d’authentification Microsoft pour .NET.

Pour cela, nous devons :

• Ajouter une nouvelle section de configuration dans appsettings.json.

  "AzureAd": {
       "Instance": "https://login.microsoftonline.com/",
       "TenantId": "see below",
       "SwaggerUiGetwayClientId": "see below",
       "SwaggerUiGetwaySecret": "see below",
       "SwaggerOpenIdSignInCallBack": "/signin-oidc-swagger"
  }
  
  

  • Vous pouvez trouver l’ID de locataire (TenantId) sur la page de présentation de l’inscription des applications : il correspond à l’ID de l’annuaire (locataire).
  • Vous pouvez également trouver SwaggerUiGetwayClientId sur la page de présentation de l’inscription des applications : il correspond à l’ID d’application (client).

• • Pour trouver SwaggerUiGetwaySecret, vous devez accéder à la section Certificats et secrets. Cliquez sur l’onglet Clés secrètes client et créez une nouvelle clé secrète. Remplissez le formulaire, puis cliquez sur Enregistrer. Copiez la valeur de cette clé secrète (IMPORTANT : copiez bien la valeur et non l’ID de la clé secrète) et collez-la au niveau de SwaggerUiGetwaySecret.

• Installez le package NuGet Microsoft.Identity.Web dans votre application.
• Dans la méthode ConfigureServices de votre classe de démarrage, ajoutez ce bloc de code :

Comme vous pouvez le voir, nous utilisons la section de configuration que nous avons précédemment ajoutée dans appsettings.json.

Middleware pour gérer l’accès à l’interface utilisateur Swagger

Il s’agit de l’étape la plus délicate et la plus importante. Découvrons-la ensemble pas à pas.

Créez une classe de middleware appelée SwaggerOAuthMiddleware. Nous vous recommandons de procéder de la façon suivante :

Vous devez ensuite appeler ce middleware dans la méthode Configure de votre classe de démarrage en ajoutant cette ligne de code :

app.UseMiddleware<SwaggerOAuthMiddleware>(configuration);

Avant de découvrir le code de façon plus détaillée, vous devez savoir ce qui se passe exactement lorsque vous chargez la page Swagger de votre API.

• Vérifiez que vous avez bien été authentifié et que vous êtes autorisé à accéder à l’interface utilisateur Swagger.
• Si ce n’est pas le cas, vous serez redirigé vers la page de connexion Microsoft, sur laquelle vous devrez saisir vos identifiants pour obtenir un jeton.
• Une fois authentifié, vous serez redirigé vers le lien que vous avez précédemment configuré sur le portail Azure. Vous y trouverez une requête http POST qui contient les données du résultat de l’authentification (la plus importante étant id_token)
• Swagger commence alors à charger l’ensemble des ressources requises afin d’afficher la vue finale, qui vous permet de découvrir tous vos points de terminaison.

Le chargement de ces ressources s’effectue au niveau de certains points de terminaison qui commencent également par le terme « swagger ». Ces points de terminaison sont automatiquement ajoutés en tant que points de terminaison internes pour votre solution à la suite de l’intégration de Swagger.

Revenons à notre code maintenant.

Si le point de terminaison demandé n’est ni l’interface utilisateur Swagger (commençant par « /swagger ») ni le rappel d’authentification (commençant par « /signin-oidc-swagger »), il n’y a aucune vérification d’accès et le contexte continue de s’exécuter.

En revanche, si le point de terminaison demandé est un point de terminaison de l’interface utilisateur Swagger, nous devons vérifier si l’utilisateur est authentifié ou non en appelant la méthode IsValidIdToken (nous expliquerons plus tard le comportement de cette méthode) et en indiquant le jeton stocké dans le stockage des sessions (nous expliquerons également plus tard l’intérêt d’extraire un jeton du stockage des sessions lors de l’appel d’un point de terminaison de l’interface utilisateur Swagger). Si l’utilisateur est authentifié, le contexte continue de s’exécuter. S’il ne l’est pas, l’authentification est remise en question (redirection vers le composant de connexion Microsoft).

Si le point de terminaison demandé est l’URI de rappel d’authentification (redirection après authentification), nous devons vérifier si l’utilisateur a été authentifié correctement ou non pour accéder à l’interface utilisateur Swagger en validant le jeton d’ID fourni dans la charge utile de la demande POST. Pour cela, nous devons appeler la méthode GetIdTokenFromSignInCallBackRequest en utilisant la classe StreamReader pour extraire le contenu de la demande contextuelle.

Normalement, la validation du jeton d’ID n’implique pas un flux d’authentification intégral, mais pour simplifier le processus, nous pourrions nous arrêter au jeton d’ID sans demander ni valider le jeton à l’aide du jeton d’ID. En effet, le fait de disposer d’un jeton d’ID valide permettrait de générer un jeton valide.

Dès que le jeton d’ID est valide, nous devons le conserver dans le stockage des sessions pour deux raisons principales :

• La redirection vers l’URI de rappel et la validation de l’authentification sont suivies d’une série d’opérations de chargement de ressources Swagger, comme nous l’avons indiqué ci-dessus, qui s’effectuent en appelant certains points de terminaison commençant par « /swagger » de façon à ce que la première Condition If dans la classe du middleware soit remplie. Si nous n’avons aucun jeton stocké, l’utilisateur sera considéré comme non authentifié et le processus reprendre depuis le début, ce qui entraînera une boucle qui se répètera à l’infini.
• Il convient d’éviter toute latence si un utilisateur souhaite ouvrir l’interface utilisateur Swagger (chargée précédemment dans un premier onglet) dans d’autres onglets de son navigateur.

Pour activer le stockage des sessions, vous devez ajouter les services Distributed Memory Cache et Session à la collection de services. Pour cela, ajoutez ce bloc de code dans la méthode ConfigureServices de la classe de démarrage :

Comme vous pouvez le voir, la validation du jeton d’ID s’effectue au moyen de la méthode IsValidIdToken. Elle utilise JwtSecurityTokenHandler pour valider principalement les éléments suivants :

• Audience : validation de l’ID client de l’inscription de l’application dans Azure
• Émetteur : validation de l’ID du locataire (le service Azure Active Directory) dans lequel l’inscription de l’application est créée
• Clés de signature : ces clés sont obtenues au moyen de la configuration OpenId Connect depuis le point de terminaison « {instance}{IDlocataire}/v2.0/.well-known/openid-configuration »

Lancez votre application et découvrez l’interface utilisateur Swagger en toute sécurité !