Comment : créer un client fédéré

Article
09/12/2008

Dans Windows Communication Foundation (WCF), la création d'un client pour un service fédéré se compose de trois étapes principales :

Configurez une liaison wsFederationHttpBinding element ou une liaison personnalisée similaire. Pour plus d'informations sur la création d'une liaison appropriée, consultez Comment : créer une liaison WSFederationHttpBinding. Ou bien, exécutez le ServiceModel Metadata Utility Tool (Svcutil.exe) par rapport au point de terminaison de métadonnées du service fédéré pour générer un fichier de configuration pour communiquer avec le service fédéré et un ou plusieurs services d'émission de jeton de sécurité.
Définissez les propriétés du IssuedTokenClientCredential qui contrôle différents aspects de l'interaction d'un client avec un service d'émission de jeton de sécurité.
Définissez les propriétés du X509CertificateRecipientClientCredential qui permet aux certificats nécessaires de communiquer en toute sécurité avec les points de terminaison donnés, tels que les services d'émission de jeton de sécurité.

Remarque :
Un CryptographicException peut être levé lorsqu'un client utilise des informations d'identification personnalisées, la liaison WSFederationHttpBinding ou un jeton émis de façon personnalisée, et des clés asymétriques. Les clés asymétriques sont utilisées avec la liaison WSFederationHttpBinding et les jetons émis de façon personnalisée lorsque les propriétés IssuedKeyType et KeyType, respectivement, ont la valeur AsymmetricKey. L'exception CryptographicException est levée lorsque le client tente d'envoyer un message et un profil utilisateur n'existe pas pour l'identité que le client emprunte. Pour minimiser ce problème, connectez-vous à l'ordinateur client ou appelez LoadUserProfile avant d'envoyer le message.

Un CryptographicException peut être levé lorsqu'un client utilise des informations d'identification personnalisées, la liaison WSFederationHttpBinding ou un jeton émis de façon personnalisée, et des clés asymétriques. Les clés asymétriques sont utilisées avec la liaison WSFederationHttpBinding et les jetons émis de façon personnalisée lorsque les propriétés IssuedKeyType et KeyType, respectivement, ont la valeur AsymmetricKey. L'exception CryptographicException est levée lorsque le client tente d'envoyer un message et un profil utilisateur n'existe pas pour l'identité que le client emprunte. Pour minimiser ce problème, connectez-vous à l'ordinateur client ou appelez LoadUserProfile avant d'envoyer le message.

Cette rubrique fournit des informations détaillées sur ces procédures. Pour plus d'informations sur la création d'une liaison appropriée, consultez Comment : créer une liaison WSFederationHttpBinding. Pour plus d'informations sur le fonctionnement d'un service fédéré, consultez Fédération.

Pour générer et examiner la configuration d'un service fédéré

Exécutez le ServiceModel Metadata Utility Tool (Svcutil.exe) avec l'adresse de l'URL de métadonnées du service comme un paramètre de ligne de commande.
Ouvrez le fichier de configuration généré dans un éditeur approprié.
Examinez les attributs et le contenu des éléments générés <issuer> et <issuerMetadata>. Ceux-ci se trouvent à l'intérieur des éléments <security> pour le <wsFederationHttpBinding> ou les éléments de liaisons personnalisés. Vérifiez que les adresses contiennent les noms de domaine attendus ou d'autres informations d'adresse. Il est important de vérifier ces informations parce que le client authentifie auprès de ces adresses et peut divulguer des informations, telles que les paires de nom d'utilisateur/mot de passe. Si l'adresse n'est pas l'adresse attendue, cela peut entraîner la divulgation d'informations à un destinataire involontaire.

Examinez tous les éléments <issuedTokenParameters> supplémentaires à l'intérieur de l'élément <alternativeIssuedTokenParameters> commenté. Lors de l'utilisation de l'outil Svcutil.exe pour générer la configuration pou un service fédéré, si le service fédéré ou tous les services d'émission de jeton de sécurité intermédiaires ne spécifient pas une adresse d'émetteur, mais spécifie une adresse de métadonnées pour un service d'émission de jeton de sécurité qui expose plusieurs points de terminaison, le fichier de configuration résultant fait référence au premier point de terminaison. Les points de terminaison supplémentaires sont dans le fichier de configuration comme éléments <alternativeIssuedTokenParameters> commentés.

Déterminez si l'un de ces <issuedTokenParameters> est préférable à celui déjà présent dans la configuration. Par exemple, le client peut choisir de s'authentifier auprès d'un service d'émission de jeton de sécurité à l'aide d'un jeton CardSpace Windows plutôt qu'une paire de nom d'utilisateur/mot de passe.

Remarque :
Dans le cas où plusieurs services d'émission de jeton de sécurité doivent être parcourus avant de communiquer avec le service, il est possible pour un service d'émission de jeton de sécurité intermédiaire de diriger le client vers un service d'émission de jeton de sécurité incorrect. Par conséquent, vérifiez que le point de terminaison pour le service d'émission de jeton de sécurité dans le <issuedTokenParameters> est le service d'émission de jeton de sécurité attendu et pas un service d'émission de jeton de sécurité inconnu.

Dans le cas où plusieurs services d'émission de jeton de sécurité doivent être parcourus avant de communiquer avec le service, il est possible pour un service d'émission de jeton de sécurité intermédiaire de diriger le client vers un service d'émission de jeton de sécurité incorrect. Par conséquent, vérifiez que le point de terminaison pour le service d'émission de jeton de sécurité dans le <issuedTokenParameters> est le service d'émission de jeton de sécurité attendu et pas un service d'émission de jeton de sécurité inconnu.

Pour configurer un IssuedTokenClientCredential dans le code

Accédez au IssuedTokenClientCredential par le biais de la propriété IssuedToken de la classe ClientCredentials (retournée par la propriété ClientCredentials de la classe ClientBase, ou par le biais de la classe ChannelFactory ), comme s'affiché dans le code d'exemple suivant.
Si la mise en cache de jeton n'est pas requise, affectez à la propriété CacheIssuedTokens la valeur false. La propriété CacheIssuedTokens contrôle si les jetons d'un service d'émission de jeton de sécurité sont mis en cache. Si cette propriété a la valeur false, le client demande un nouveau jeton auprès du service d'émission de jeton de sécurité à chaque fois qu'il doit se ré-authentifier lui-même auprès du service fédéré, qu'un jeton précédent soit encore valide ou non. Si cette propriété a la valeur true, le client réutilise un jeton existant toutes les fois qu'il doit se ré-authentifier auprès du service fédéré (tant que le jeton n'a pas expiré). La valeur par défaut est true.
Si une limite de temps est requise sur les jetons mis en cache, affectez à la propriété MaxIssuedTokenCachingTime une valeur TimeSpan. La propriété spécifie la durée de mise en cache d'un jeton. Au terme de l'intervalle de temps spécifié, le jeton est supprimé du cache client. Par défaut, les jetons sont mis en cache indéfiniment. L'exemple suivant affecte à l'intervalle de temps la valeur de 10 minutes.
Facultatif. Affectez au IssuedTokenRenewalThresholdPercentage un pourcentage. La valeur par défaut est 60 (pourcent). La propriété spécifie un pourcentage de la période de validité du jeton. Par exemple, si le jeton émis est valide pour 10 heures et IssuedTokenRenewalThresholdPercentage a la valeur 80, le jeton est renouvelé après huit heures. L'exemple suivant affecte la valeur de 80 pourcent.

L'intervalle de renouvellement déterminé par la période de validité du jeton et la valeur IssuedTokenRenewalThresholdPercentage est substitué par la valeur MaxIssuedTokenCachingTime dans les cas où le temps de mise en cache est plus court que le temps du seuil de renouvellement. Par exemple, si le produit de IssuedTokenRenewalThresholdPercentage et la durée du jeton est huit heures, et la valeur MaxIssuedTokenCachingTime est 10 minutes, le client contacte le service d'émission de jeton de sécurité pour un jeton mis à jour toutes les 10 minutes.

Si un mode d'entropie de clé différent de CombinedEntropy est exigé sur une liaison qui n'utilise pas la sécurité de message ou la sécurité de transport avec les informations d'identification de message (par exemple, la liaison n'a pas de SecurityBindingElement), affectez à la propriété DefaultKeyEntropyMode une valeur appropriée. Le mode d'entropie détermine si les clés symétriques peuvent être contrôlées à l'aide de la propriété DefaultKeyEntropyMode. Cette valeur par défaut est CombinedEntropy, où le client et l'émetteur de jeton fournissent des données qui sont associées afin de produire la clé à part entière. D'autres valeurs sont ClientEntropy et ServerEntropy, ce qui signifie que la clé entière est spécifiée par le client ou le serveur, respectivement. L'exemple suivant définit la propriété afin d'utiliser uniquement les données de serveur pour la clé.

Remarque :
Si un SecurityBindingElement est présent dans un service d'émission de jeton de sécurité ou une liaison de service, le DefaultKeyEntropyMode défini sur IssuedTokenClientCredential est substitué par la propriété KeyEntropyMode du SecurityBindingElement.

Configurez tout comportement de point de terminaison spécifique à l'émetteur en l'ajoutant à la collection retournée par la propriété IssuerChannelBehaviors.

Pour configurer IssuedTokenClientCredential dans la configuration

Créez un élément <issuedToken> comme un enfant de l'élément <clientCredentials> dans un comportement de point de terminaison.
Si la mise en cache de jeton n'est pas requise, affectez à l'attribut cacheIssuedTokens (de l'élément <issuedToken>) la valeur false.
Si une limite de temps est requise sur les jetons mis en cache, affectez à l'attribut maxIssuedTokenCachingTime sur l'élément <issuedToken> une valeur appropriée. Par exemple :
<issuedToken maxIssuedTokenCachingTime='00:10:00' />
Si une valeur différente de la valeur par défaut est souhaitée, affectez à l'attribut issuedTokenRenewalThresholdPercentage sur l'élément <issuedToken> une valeur appropriée, par exemple :
```
<issuedToken issuedTokenRenewalThresholdPercentage = "80" />
```
Si un mode d'entropie de clé différente de CombinedEntropy est sur une liaison qui n'utilise pas la sécurité de message ou la sécurité de transport avec les informations d'identification de message (par exemple, la liaison n'a pas de SecurityBindingElement), attribuez à l'attribut defaultKeyEntropyMode sur l'élément <issuedToken> la valeur ServerEntropy ou ClientEntropy selon les besoins.
```
<issuedToken defaultKeyEntropyMode = "ServerEntropy" />
```
Facultatif. Configurez tout comportement de point de terminaison personnalisé spécifique à l'émetteur en créant un élément <issuerChannelBehaviors> comme un enfant de l'élément <issuedToken>. Pour chaque comportement, créez un élément <add> comme un enfant de l'élément <issuerChannelBehaviors>. Spécifiez l'adresse de l'émetteur du comportement en définissant l'attribut issuerAddress sur l'élément <add>. Spécifiez le comportement lui-même en définissant l'attribut behaviorConfiguration sur l'élément <add>.
```
<issuerChannelBehaviors>
<add issuerAddress="http://fabrikam.org/sts" behaviorConfiguration="FabrikamSTS" />
</issuerChannelBehaviors>
```

Pour configurer un X509CertificateRecipientClientCredential dans le code

Accédez à X509CertificateRecipientClientCredential par le biais de la propriété ServiceCertificate de la propriété ClientCredentials de la classe ClientBase ou de la propriété ChannelFactory.
Si une instance X509Certificate2 est disponible pour le certificat pour un point de terminaison donné, utilisez la méthode Add de la collection retournée par la propriété ScopedCertificates.
Si une instance X509Certificate2 est non disponible, utilisez la méthode SetScopedCertificate de la classe X509CertificateRecipientClientCredential comme indiqué dans l'exemple suivant.

Pour configurer un X509CertificateRecipientClientCredential dans la configuration

Créez un élément <scopedCertificates> en tant qu'enfant de l'élément <serviceCertifcate> lui-même enfant de l'élément <clientCredentials> dans un comportement de point de terminaison.
Créez un élément <add> en tant qu'enfant de l'élément <scopedCertificates>. Spécifiez des valeurs pour les attributs storeLocation, storeName, x509FindTypeet findValue pour faire référence au certificat approprié. Affectez à l'attribut targetUri une valeur qui fournit l'adresse du point de terminaison à laquelle le certificat est destiné, comme indiqué dans l'exemple suivant.
```
<scopedCertificates>
 <add targetUri="https://fabrikam.com/sts" 
      storeLocation="CurrentUser"
      storeName="TrustedPeople"
      x509FindType="FindBySubjectName"
      findValue="FabrikamSTS" />
</scopedCertificates>
```

Exemple

L'exemple de code suivant configure une instance de la classe IssuedTokenClientCredential dans le code.

Sécurité

Pour empêcher la divulgation d'informations possible, les clients qui exécutent l'outil Svcutil.exe pour traiter les métadonnées de points de terminaison fédérés doivent vérifier que les adresses de service d'émission de jeton de sécurité résultantes correspondent à celles qu'ils attendent. C'est particulièrement important lorsqu'un service d'émission de jeton de sécurité expose plusieurs points de terminaison, parce que l'outil Svcutil.exe génère le fichier de configuration résultant pour utiliser le premier tel point de terminaison, qui ne peut pas être celui le client doit utiliser.

LocalIssuer requis

Si les clients doivent toujours utiliser un émetteur local, prenez note des éléments suivants : la sortie par défaut de Svcutil.exe entraîne la non-émission de l'émetteur local qui n'est pas utilisé si l'antépénultième service d'émission de jeton de sécurité dans la chaîne spécifie une adresse d'émetteur ou une adresse de métadonnées d'émetteur.

Pour plus d'informations sur la définition des propriétés LocalIssuerAddress, LocalIssuerBinding, et LocalIssuerChannelBehaviors de la classe IssuedTokenClientCredential, consultez Comment : configurer un émetteur local.

Certificats à étendue

Si les certificats de service doivent être spécifiés pour communiquer avec des services d'émission de jeton de sécurité, parce que la négociation de certificat n'est pas le plus souvent utilisée, ils peuvent être spécifiés à l'aide de la propriété ScopedCertificates de la classe X509CertificateRecipientClientCredential. La méthode SetDefaultCertificate accepte un Uri et un X509Certificate2 comme paramètres. Le certificat spécifié est utilisé pour communiquer avec les points de terminaison à l'URI spécifié. Vous pouvez également utiliser la méthode SetScopedCertificate pour ajouter un certificat à la collection retournée par la propriété ScopedCertificates.

Remarque :
L'idée cliente des certificats dont l'étendue englobe un URI donné s'applique uniquement à des applications qui effectuent des appels sortants aux services qui exposent des points de terminaison à ces URI. Elle ne s'applique pas aux certificats utilisés pour signer des jetons émis, tels que ceux configurés sur le serveur dans la collection retournée par le KnownCertificates de la classe IssuedTokenServiceCredential. Pour plus d'informations, consultez Comment : configurer des informations d'identification sur un service FS (Federation Service).

L'idée cliente des certificats dont l'étendue englobe un URI donné s'applique uniquement à des applications qui effectuent des appels sortants aux services qui exposent des points de terminaison à ces URI. Elle ne s'applique pas aux certificats utilisés pour signer des jetons émis, tels que ceux configurés sur le serveur dans la collection retournée par le KnownCertificates de la classe IssuedTokenServiceCredential. Pour plus d'informations, consultez Comment : configurer des informations d'identification sur un service FS (Federation Service).

Voir aussi

Partager via