Établissement de l'approbation d'une application de partie de confiance ASP.NET à un STS à l'aide de FedUtil

FedUtil.exe est fourni avec Windows® Identity Foundation (WIF). Il permet d'établir l'approbation d'une application de partie de confiance (RP) aux services d'émission de jeton de sécurité (STS). Il fournit les fonctions suivantes :

• Enregistrement d'un STS de production existant comme émetteur approuvé de l'application RP

• Aide au développement d'une application prenant en charge les revendications en proposant un STS local

• Modification d'une application existante pour qu'elle prenne en charge les revendications

• Mise à jour des métadonnées de fédération pour une application RP

• Planification des mises à jour automatiques des métadonnées de fédération pour une application RP

Les sections suivantes décrivent comment effectuer chacune de ces tâches à l'aide de FedUtil. Vous pouvez également effectuer ces tâches manuellement en apportant les mêmes modifications au fichier Web.config de votre application RP que FedUtil apporterait.

1. Créer un STS local

Dans cet exercice, vous créez un STS local à utiliser avec notre application de partie de confiance ASP.NET prenant en charge les revendications. Notez que pour ce faire vous devez exécuter FedUtil à partir de Visual Studio. Cette option vise à faciliter le développement d'une application ASP.NET de partie de confiance prenant en charge les revendications avec un STS de non-production. Nous verrons plus loin comment passer à l'utilisation d'un STS de production.

Dans Visual Studio, ouvrez le menu Fichier et sélectionnez Nouveau, puis Site Web. Sélectionnez Site Web ASP.NET prenant en charge les revendications.

Ensuite, cliquez avec le bouton droit sur votre projet dans l'Explorateur de solutions et sélectionnez Ajouter référence STS :

L'outil FedUtil est exécuté. La boîte de dialogue FedUtil s'affiche, en commençant par la page Bienvenue dans l'Assistant Federation Utility :

Dans cette page, vous devez remplir deux champs :

1. Emplacement de configuration de l'application : spécifiez le chemin d'accès au fichier web.config de votre service . Si vous n'exécutez pas FedUtil à partir de Visual Studio, ou que vous l'exécutez à partir du menu Outils de Visual Studio sans avoir un projet ouvert, ce champ est vide. Si vous exécutez FedUtil en cliquant avec le bouton droit sur un projet dans Visual Studio, ce champ contient déjà le chemin d'accès au fichier web.config du projet. Le fichier web.config doit déjà exister et doit être dans son état par défaut (c'est-à-dire, comme il a été généré par Visual Studio). Si vous exécutez FedUtil plusieurs fois sur le même fichier web.config, FedUtil remplace simplement le contenu qu'il ajoute au fichier web.config.

2. URI de l'application : spécifiez l'URI de votre service ASP.NET. Notez qu'il s'agit d'un fichier .svc. Si vous n'exécutez pas FedUtil à partir de Visual Studio, ou que vous l'exécutez à partir du menu Outils de Visual Studio sans avoir un projet ouvert, ce champ est vide. Si vous exécutez FedUtil en cliquant avec le bouton droit sur un projet dans Visual Studio, ce champ contient déjà deux URI pour votre projet : un qui utilise le localhost, et un qui utilise le nom de domaine complet pour votre ordinateur, le cas échéant. Cet URI est utilisé comme valeur de domaine lors de la configuration de l'application pour les revendications. Il est également utilisé comme premier URI d'audience. Si vous souhaitez spécifier des URI d'audience supplémentaires, vous devez le faire manuellement. Si l'URI n'est pas sécurisé (autrement dit, qu'il ne commence pas par « https:// »), vous recevez un avertissement lorsque vous cliquez sur Suivant.

Une fois que vous avez fourni les informations, cliquez sur Suivant. La page Service d'émission de jeton de sécurité (STS) s'affiche. Sélectionnez Créer un projet STS dans la solution actuelle :

Notez que si vous n'exécutez pas FedUtil à partir de Visual Studio, ou que vous exécutez FedUtil à partir du menu Outils de Visual Studio sans avoir un projet ouvert, l'option Créer un projet STS dans la solution actuelle n'est pas disponible.

Cliquez sur Suivant. La page Résumé s'affiche :

La page Résumé affiche les informations que vous avez entrées dans la boîte de dialogue Informations sur l'application, votre choix de créer un STS, les revendications demandées par l'application, et les modifications que FedUtil apportera à la configuration de votre application.

Cliquez sur Terminer.

Si vous observez votre fichier web.config, vous pouvez voir que FedUtil l'a modifié :

• Les paramètres d'application suivants sont ajoutés :

  <appSettings> <add key="FederationMetadataLocation" value="C:\inetpub\wwwroot\ClaimsAwareWebSite1_STS\FederationMetadata\2007-06\FederationMetadata.xml" /> </appSettings>
  

• Tous les utilisateurs se sont vus accorder l'accès aux métadonnées de fédération :

  <location path="FederationMetadata"> <system.web> <authorization> <allow users="*" /> </authorization> </system.web> </location>
  

• WSFederationAuthenticationModule et SessionAuthenticationModule sont ajoutés à l'élément <system.Web>/<httpModules> :

  <httpModules> ... <add name="WSFederationAuthenticationModule" type="Microsoft.IdentityModel.Web.WSFederationAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" /> <add name="SessionAuthenticationModule" type="Microsoft.IdentityModel.Web.SessionAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" /> </httpModules>
  

• Ils sont également ajoutés à l'élément <system.webServer>/<modules> :

  <system.webServer> ... <modules> <add name="WSFederationAuthenticationModule" type="Microsoft.IdentityModel.Web.WSFederationAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" preCondition="managedHandler" /> <add name="SessionAuthenticationModule" type="Microsoft.IdentityModel.Web.SessionAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" preCondition="managedHandler" /> </modules> ... </system.webServer>
  

• Enfin, l'élément <microsoft.identityModel>/<service> est modifié comme suit :

  <microsoft.identityModel> <service> <audienceUris> <add value="https://localhost:58496/ClaimsAwareWebSite2/" /> </audienceUris> <federatedAuthentication enabled="true"> <wsFederation passiveRedirectEnabled="true" issuer="https://localhost:58497/ClaimsAwareWebSite2_STS/" realm="https://localhost:58496/ClaimsAwareWebSite2/" requireHttps="false" /> <cookieHandler requireSsl="false" /> </federatedAuthentication> <applicationService> <claimTypeRequired> <claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" optional="true" /> <claimType type="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" optional="true" /> </claimTypeRequired> </applicationService> <issuerNameRegistry type="Microsoft.IdentityModel.Tokens.ConfigurationBasedIssuerNameRegistry, Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"> <trustedIssuers> <add thumbprint="0E2A9EB75F1AFC321790407FA4B130E0E4E223E2" name="CN=STSTestCert" /> </trustedIssuers> </issuerNameRegistry> </service> </microsoft.identityModel>
  

  • Un élément <audienceUris> est ajouté pour spécifier l'URI de l'application de partie de confiance ASP.NET prenant en charge les revendications.

  • Un élément <federatedAuthentication> est ajouté pour spécifier l'emplacement du STS pour cette application de partie de confiance ASP.NET prenant en charge les revendications. Pour cet exercice, le STS local est utilisé.

  • Un élément <applicationService>/<claimTypeRequired> est ajouté pour spécifier les revendications requises par l'application dans tous les jetons que lui envoie le STS. Pour cet exercice, le « nom » et le « rôle » de revendications par défaut sont utilisés. Notez que la partie de confiance ne dépend pas vraiment de ces exigences de type de revendication. Elles sont présentes dans le fichier de configuration pour deux raisons :

    1. Les applications de partie de confiance peuvent utiliser ces exigences de type de revendication pour vérifier si le jeton entrant contient ces revendications ou non, ce qui peut être fait dans ClaimsAuthenticationManager.

    2. Elles permettent aux parties de confiance de mettre à jour facilement les exigences de type de revendication de l'application de partie de confiance.

  • Un élément <issuerNameRegistry>/<trustedIssuers> est ajouté pour spécifier quel certificat est utilisé par le STS pour signer les jetons qu'il émet. Le STS utilise un certificat par défaut pour signer les jetons qu'il génère. Ce certificat est nommé « STSTestCert » et est ajouté automatiquement à votre magasin de certificats pour être utilisé par le STS. Le fichier de certificat est présent dans le projet STS. Le mot de passe pour le fichier est « STSTest ». Il ne doit pas être utilisé dans un exercice de production. Vous pouvez remplacer le certificat par défaut par tout autre certificat. Vérifiez que l'utilisateur de votre processus IIS a accès à la clé privée pour tout certificat de ce type. Vous pouvez également choisir de créer un type dérivé de IssuerNameRegistry pour exécuter une validation par programme des certificats des émetteurs approuvés.

De plus, si vous regardez l'Explorateur de solutions, vous voyez que FedUtil a ajouté un projet à votre solution. Ce projet est le STS local. Notez également qu'un document de métadonnées de fédération a été ajouté à la fois à l'application de partie de confiance et au STS local.

Notez que les jetons émis par ce STS local ne sont pas chiffrés.

Pour ajouter des revendications supplémentaires que le STS local doit émettre, ouvrez CustomSecurityTokenService.cs dans le projet STS sous le dossier App_Code, accédez à la méthode GetOutputClaimsIdentity et ajoutez les revendications.

2. Enregistrer un STS de production existant

Dans cet exercice, vous établissez l'approbation d'une partie de confiance ASP.NET à un STS existant.

Dans Visual Studio, ouvrez le menu Fichier et sélectionnez Nouveau, puis Site Web. Sélectionnez Site Web ASP.NET prenant en charge les revendications. Cliquez avec le bouton droit sur votre projet dans l'Explorateur de solutions et sélectionnez Ajouter référence STS. L'outil FedUtil est exécuté. Dans la page Bienvenue dans l'Assistant Federation Utility, vérifiez que l'emplacement de configuration de l'application et l'URI de l'application sont corrects et cliquez sur Suivant.

Dans la page Informations sur l'application, sélectionnez Utiliser un STS existant :

Vous devez spécifier l'emplacement du point de terminaison de métadonnées de fédération pour le STS de production. Vous pouvez cliquer sur le bouton Tester l'emplacement pour vous assurer que le document de métadonnées est accessible. Ce bouton envoie une demande au point de terminaison spécifié et affiche la réponse dans le navigateur Web par défaut. Pour cet exercice, nous utilisons un STS Active Directory® Federation Services (AD FS) 2.0. Une fois que vous avez spécifié l'emplacement du document de métadonnées de fédération, cliquez sur Suivant.

Notez que si vous spécifiez un STS qui dispose d'un certificat non approuvé par le magasin de certificats local, le message d'avertissement suivant s'affiche : « ID1025 : Une chaîne de certificats a été traitée mais s'est terminée par un certificat racine qui n'est pas approuvé par le fournisseur d'approbation ». Si vous souhaitez quand même continuer, cliquez sur Oui. Dans le cas contraire, cliquez sur Non et sélectionnez un STS différent.

Une autre page Informations sur l'application s'affiche, cette fois vous demandant de choisir Aucun chiffrement ou Activer le chiffrement :

Vérifiez auprès de votre administrateur STS que le chiffrement des jetons est pris en charge par le STS de production. Si tel est le cas, il est recommandé d'activer le chiffrement. Pour cet exercice, sélectionnez Activer le chiffrement. Vous devez à présent sélectionner le certificat que la partie de confiance souhaite que le STS utilise lors du chiffrement des jetons.

L'utilisation du certificat par défaut signifie que si le STS local a déjà créé un certificat pour le chiffrement de jetons, ce même certificat est utilisé pour le déchiffrement. Lors de l'enregistrement d'un STS de production, cette situation est rare car le STS de production n'utilise probablement pas le même certificat que celui que vous avez utilisé pour le STS local. Vous ne devez pas utiliser cette option dans une solution de production. Si vous avez déjà un certificat de service, vous pouvez utiliser le même certificat.

Si vous sélectionnez un certificat existant, FedUtil affiche le ou les certificats dans le magasin de certificats local. Le certificat doit avoir une clé privée et un nom d'objet. Assurez-vous que l'identité (par exemple, SERVICE RÉSEAU) sous laquelle l'application s'exécute a accès à la clé privée du certificat.

Pour cet exercice, vous pouvez utiliser le certificat par défaut ou en sélectionner un existant. Lorsque vous avez fini, cliquez sur Suivant.

La page Revendications proposées s'affiche :

Elle contient une liste des revendications proposées par le STS. FedUtil obtient cette liste en téléchargeant les métadonnées à partir du STS et en les analysant. Par défaut, FedUtil configure uniquement les revendications de nom et de rôle comme revendications obligatoires dans la configuration de la partie de confiance. Pour savoir comment configurer votre application de partie de confiance de sorte qu'elle exige des revendications supplémentaires, consultez la section « Comment configurer votre application pour qu'elle exige des revendications supplémentaires ». Si des revendications sont requises par votre application de partie de confiance mais ne sont pas proposées par le STS, vous devez contacter l'administrateur STS et passer les accords nécessaires.

Cliquez sur Suivant. La page Résumé s'affiche :

Si vous avez sélectionné un certificat de test, les informations d'application incluent cette remarque : « Certificat d'application sélectionné : un nouveau certificat avec le nom d'objet 'CN=DefaultApplicationCertificate' sera ajouté aux magasins de certificats Personnel et Personnes autorisées, s'il n'est pas déjà présent ». Si vous avez sélectionné un certificat existant, vous voyez l'empreinte numérique pour ce certificat.

La page Résumé affiche les informations que vous avez entrées dans la boîte de dialogue Informations sur l'application, votre choix d'utiliser un STS existant, les revendications demandées par l'application, et les modifications que FedUtil apportera à la configuration de votre application.

La page de résumé inclut également une case à cocher afin de planifier des mises à jour quotidiennes des métadonnées pour cette application. Si vous activez cette case à cocher, FedUtil planifie une tâche de mise à jour des métadonnées de l'application tous les jours à minuit. Pour plus d'informations, consultez Procédure : Effectuer la gestion des approbations à l'aide de FedUtil.

Cliquez sur Terminer.

Modifications apportées au fichier web.config de la partie de confiance :

• Les paramètres d'application suivants sont ajoutés. « STS spécifié » fait référence au STS que vous avez spécifié dans FedUtil.

  <appSettings> <add key="FederationMetadataLocation" value="<STS spécifié>" /> </appSettings>
  

• Tous les utilisateurs se sont vus accorder l'accès aux métadonnées de fédération :

  <location path="FederationMetadata"> <system.web> <authorization> <allow users="*" /> </authorization> </system.web> </location>
  

• WSFederationAuthenticationModule et SessionAuthenticationModule sont ajoutés à l'élément <system.Web>/<httpModules> :

  <httpModules> ... <add name="WSFederationAuthenticationModule" type="Microsoft.IdentityModel.Web.WSFederationAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" /> <add name="SessionAuthenticationModule" type="Microsoft.IdentityModel.Web.SessionAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" /> </httpModules>
  

• Ils sont également ajoutés à l'élément <system.webServer>/<modules> :

  <system.webServer> ... <modules> <add name="WSFederationAuthenticationModule" type="Microsoft.IdentityModel.Web.WSFederationAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" preCondition="managedHandler" /> <add name="SessionAuthenticationModule" type="Microsoft.IdentityModel.Web.SessionAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" preCondition="managedHandler" /> </modules> ... </system.webServer>
  

• Enfin, l'élément <microsoft.identityModel>/<service> est modifié comme suit. « specified SPS » fait référence au STS que vous avez spécifié dans FedUtil.

  <microsoft.identityModel> <service> <audienceUris> <add value="https://localhost:57349/ClaimsAwareWebSite2/" /> </audienceUris> <federatedAuthentication> <wsFederation passiveRedirectEnabled="true" issuer="https://<specified STS>/FederationPassive/" realm="https://localhost:57349/ClaimsAwareWebSite2/" requireHttps="false" /> <cookieHandler requireSsl="false" /> </federatedAuthentication> <serviceCertificate> <certificateReference x509FindType="FindByThumbprint" findValue="48BF03FCEDA703DE09E0F1F0CEFED60BB92B3DD8" storeLocation="LocalMachine" storeName="My" /> </serviceCertificate> <applicationService> <claimTypeRequired> <!--Following are the claims offered by STS 'http://<specified STS>/Trust'. Add or uncomment claims that you require by your application and then update the federation metadata of this application.--> <claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" optional="true" /> <claimType type="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" optional="true" /> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/claims/CommonName" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/claims/EmailAddress" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/claims/Group" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/claims/UPN" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/webpage" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/title" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/picture" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/manager" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/department" optional="true" />--> </claimTypeRequired> </applicationService> <issuerNameRegistry type="Microsoft.IdentityModel.Tokens.ConfigurationBasedIssuerNameRegistry, Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"> <trustedIssuers> <add thumbprint="5C8885A8E3D29D6BF6C9365E00B1BEA5EB284D1E" name="CN=<specified STS>, OU=US-Federated Identity, O=Microsoft Corporation, L=Redmond, S=Washington, C=US" /> </trustedIssuers> </issuerNameRegistry> </service> </microsoft.identityModel>
  

  • Un élément <audienceUris> est ajouté pour spécifier l'URI de l'application de partie de confiance ASP.NET prenant en charge les revendications.

  • Un élément <federatedAuthentication> est ajouté pour spécifier l'emplacement du STS pour cette application de partie de confiance ASP.NET prenant en charge les revendications. Il s'agit du STS que vous avez spécifié dans FedUtil.

  • Un élément <serviceCertificate> est ajouté pour spécifier l'emplacement du certificat que l'application de partie de confiance ASP.NET prenant en charge les revendications utilise pour chiffrer ses communications avec le STS. Il s'agit du certificat que vous avez spécifié dans FedUtil.

  • Un élément <applicationService>/<claimTypeRequired> est ajouté pour spécifier les revendications requises par l'application dans tous les jetons que lui envoie le STS. Par défaut, FedUtil configure votre application de partie de confiance ASP.NET prenant en charge les revendications pour n'exiger que les revendications de nom et de rôle. Pour savoir comment configurer votre application de partie de confiance de sorte qu'elle exige des revendications supplémentaires, consultez la section « Comment configurer votre application pour qu'elle exige des revendications supplémentaires ».

  • Un élément <issuerNameRegistry>/<trustedIssuers> est ajouté pour spécifier quel certificat est utilisé par le STS pour signer les jetons qu'il émet.

Notez que vous pouvez exécuter FedUtil à plusieurs reprises pour passer d'un STS local à un STS de production et vice versa. Chaque fois que vous exécutez FedUtil, il remplace simplement la configuration créée précédemment. Toutefois, vous ne pouvez pas utiliser FedUtil pour passer de l'utilisation d'un STS local ou de production à l'utilisation d'aucun STS.

De plus, notez que si vous exécutez FedUtil et créez un STS local, puis passez à un STS de production, l'élément <issuerNameRegistry> de votre fichier de configuration contient deux émetteurs approuvés. L'un est le STS local et l'autre est le STS de production. Une fois que vous êtes prêt à déployer votre application, supprimez le STS local du registre des noms d'émetteurs.

3. Mettre à jour les métadonnées de fédération

Par défaut, lorsque vous utilisez FedUtil et spécifiez un STS de production, FedUtil configure votre application de sorte qu'elle exige uniquement les revendications de nom et de rôle. Vous pouvez le constater dans l'élément <Microsoft.IdentityModel>/<service>/<applicationService>/<claimTypeRequired> dans le fichier web.config de l'application :

<claimTypeRequired><!--Voici les revendications proposées par STS '<STS spécifié>' et ajoutées le 15/04/2009 à 15:57:07. Ajoutez ou supprimez les commentaires des revendications dont vous avez besoin pour votre application, puis mettez à jour les métadonnées de fédération de cette application.--> <claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" optional="true" /> <claimType type="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" optional="true" /> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" optional="true" />--> ... </claimTypeRequired>

Par exemple, dans l'extrait de code précédent, la revendication emailaddress est commentée. Pour configurer votre application pour qu'elle exige des revendications supplémentaires, supprimez les commentaires des revendications voulues. Ensuite, dans l'Explorateur de solutions, cliquez avec le bouton droit sur le projet d'application et sélectionnez Mettre à jour les métadonnées de fédération :

FedUtil met à jour les métadonnées de fédération de votre application pour refléter les modifications apportées à la liste des revendications obligatoires. Ensuite, ouvrez le fichier FederationMetadata.xml de l'application et observez la liste mise à jour des revendications obligatoires. Elle doit maintenant inclure toutes les revendications supplémentaires dont vous avez supprimé les commentaires dans le fichier web.config de l'application. Notez que FedUtil effectue également une copie de sauvegarde du fichier web.config de l'application.

<fed:ClaimTypesRequested> <auth:ClaimType Uri="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" Optional="True" xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706" /> <auth:ClaimType Uri="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" Optional="True" xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706" /> ... </fed:ClaimTypesRequested>

Vous pouvez également ajouter des types de revendications personnalisés au fichier web.config de l'application. Vous devez ensuite demander à votre administrateur STS de mettre à jour la stratégie STS pour votre application afin que les nouveaux types de revendications soient émis.