Demande de jetons SAML sender-vouches à un STS externe à l'aide des API WSS avec la protection au niveau du transport

Vous pouvez demander des jetons SAML avec la méthode de confirmation des sujets sender-vouches à un STS (Security Token Service) externe. Une fois que vous avez obtenu les jetons SAML sender-vouches, vous pouvez les envoyer dans des messages de demande de services Web à l'aide du modèle de programmation JAX-WS (Java™ API for XML-Based Web Services) et des API WSS (Web Services Security) avec protection au niveau du transport.

Avant de commencer

On considère ici que vous connaissez le modèle de programmation JAX-WS, les API WSS, les concepts de SAML, la protection du transport SSL et l'utilisation des ensembles de règles pour configurer et administrer les paramètres des services Web.

Pourquoi et quand exécuter cette tâche

Vous pouvez demander à un STS externe un jeton SAML avec la méthode de confirmation des sujets sender-vouches, puis l'envoyer dans les messages de demande de services Web à partir d'un client de services Web à l'aide d'API WSS avec protection au niveau du transport.

L'application client de services Web utilisée dans cette tâche est une version modifiée du code client contenu dans l'application modèle JaxWSServicesSamples disponible pour le téléchargement. Des exemples de code du modèle sont décrits dans la procédure et un modèle de client de services Web prêt à l'emploi est fourni.

Procédure

  1. Identifiez et obtenez le client de services Web que vous souhaitez utiliser pour appeler un fournisseur de services Web.

    Utilisez ce client pour programmer l'insertion des jetons SAML dans des messages de demande SOAP à l'aide des API WSS.

    Le client de services Web utilisé dans cette procédure est une version modifiée du code client contenu dans l'exemple d'application de services Web JaxWSServicesSamples.

    Pour obtenir le modèle de client de services Web et le modifier en ajoutant les API de Services de sécurité (WSS), afin de programmer la transmission de jetons SAML sender-vouches dans les messages de demande SOAP, procédez comme suit :

    1. Téléchargez l'exemple d'application JaxWSServicesSamples. Le modèle d'application JaxWSServicesSamples n'est pas installé par défaut.
    2. Obtenez le code client JaxWSServicesSamples.

      Pour les besoins de l'exemple, cette procédure utilise une version modifiée du client léger Echo compris dans le modèle JaxWSServicesSamples. L'exemple de fichier client fin Echo de services Web, SampleClient.java, est situé dans le répertoire src\SampleClientSei\src\com\ibm\was\wssample\sei\cli. L'exemple de fichier de classe est inclus au fichier WSSampleClientSei.jar.

      L'application d'entreprise JaxWSServicesSamples.ear et la prise en charge des fichiers d'archive Java (JAR) sont situés dans le répertoire installableApps dans l'exemple d'application JaxWSServicesSamples.

    3. Déployez le fichier JaxWSServicesSamples.ear dans le serveur d'application. Une fois le fichier JaxWSServicesSamples.ear déployé, vous êtes prêt à tester le modèle de code de client de services Web avec le modèle d'application.

    Au lieu d'utiliser le modèle de client de services web, vous pouvez choisir d'intégrer à votre propre application client de services Web les fragments de code destinés à programmer la transmission des jetons SAML dans les messages de demande SOAP à l'aide des API WSS. L'exemple pris dans cette procédure utilise un client léger de services Web JAX-WS ; il est cependant possible d'utiliser un client géré.

  2. Créez une copie de l'ensemble de règles par défaut SAML20 Bearer WSHTTPS Default ou SAML11 Bearer WSHTTPS.

    Entrez un nom pour la copie de l'ensemble de règles, par exemple SAML20 SenderVouches WSHTTPS ou SAML11 SenderVouches WSHTTPS, qui vous permette d'identifier que ce nouvel ensemble utilise la méthode de confirmation sender-vouches.

    Aucune modification supplémentaire du nouveau fichier de règles n'est nécessaire, parce que la méthode de confirmation du sujet et définie dans la configuration de la liaison, et non dans les règles.

    Le nouveau fichier contient les identificateurs de règles SAMLToken20Bearer ou SAMLToken11Bearer. Remplacez l'identificateur des règles SAMLToken20Bearer par SAMLToken20SV, ou SAMLToken11Bearer par SAMLToken11SV pour rendre le nom plus parlant. La modification de l'identificateur des règles ne change en aucune manière la mise en oeuvre des règles, mais elle peut vous aider à identifier qu'ils utilisent la méthode de confirmation sender-vouches.

    Pour afficher les paramètres de ces règles, procédez comme suit dans la console d'administration :
    1. Cliquez sur Services > Ensembles de règles > Ensembles de règles de l'application > nom_ensemble_règles.
    2. Cliquez sur la règle WS-Security dans la table des règles.
    3. Cliquez sur le lien Règle principale ou sur le lien Règle d'amorce.
    4. Cliquez sur Règles de jeton de demande dans la section Détails des règles.
  3. Associez le nouvel ensemble de règles SAML20 SenderVouches WSHTTPS ou SAML11 SenderVouches à l'application de fournisseur de services Web. Pour plus d'informations sur la façon d'associer cet ensemble de règles à l'application fournisseur de services Web, reportez-vous à la section relative à la configuration des clients et des fournisseurs pour le jeton SAML sender-vouches (envoyeur garant).
  4. Créez une copie des liaisons générales par défaut SAML Bearer Provider Sample.
    1. Attribuez-lui un nom comportant "sender-vouches", par exemple SAML sender-vouches provider binding.
    2. Dans le gestionnaire d'appel de votre consommateur de jeton SAML11 ou SAML20, remplacez la valeur de la propriété confirmationMethod par sender-vouches dans la configuration du consommateur du jeton pour la version de jeton SAML concernée. Vérifiez que les propriétés personnalisées trustStoreType, trustStorePassword et trustStorePath correspondent au fichier de clés certifiées contenant le certificat de signataire de STS. Pour plus d'informations sur la façon de modifier les liaisons sender-vouches pour répondre aux besoins de garantie, reportez-vous à la section relative à la configuration des clients et des fournisseurs pour le jeton SAML sender-vouches (envoyeur garant).
  5. Affectez la nouvelle liaison de fournisseur au modèle de fournisseur JaxWSServicesSamples. Pour plus d'informations sur la manière d'affecter les liaisons générales par défaut du modèle de fournisseur SAML sender-vouches à votre application fournisseur de services Web, reportez-vous à la section relative à la configuration des liaisons de client et fournisseur pour les jetons SAML sender-vouches.
  6. Activez l'attribut de configuration SSL du fournisseur de services Web, clientAuthentication, pour demander l'authentification du certificat client X.509.
    L'attribut clientAuthentication détermine si l'authentification client SSL est requise. Pour activer l'attribut clientAuthentication, procédez comme suit dans la console administrative :
    1. Cliquez sur Sécurité > Gestion des certificats SSL et des clé > Gérer les configurations de sécurité du noeud final > {Entrantes | Sortantes} > Configurations SSL.
    2. Cliquez sur le lien WC_defaulthost_secure dans la topologie entrante.
    3. Dans Articles liés, cliquez sur le lien Configurations SSL.
    4. Sélectionnez la ressource NodeDefaultSSLSettings.
    5. Cliquez sur le lien Paramètres de la qualité de protection (QoP).
    6. Sélectionnez Requis dans le menu pour définir l'authentification client.

    Pour en savoir plus sur la configuration de l'attribut clientAuthentication, consultez la rubrique relative à la création d'une configuration SSL (Secure Sockets Layer).

  7. Spécifiez l'utilisation de la protection des messages au niveau du transport SSL. Utilisez la propriété JVM suivante pour spécifier l'utilisation de SSL pour protéger la demande de jeton SAML avec le STS :
    -Dcom.ibm.SSL.ConfigURL=file:racine_profil\properties\ssl.client.props
    A la place, vous pouvez également définir le fichier de configuration SSL en définissant une propriété système Java dans le modèle de code client, par exemple :
    System.setProperty("com.ibm.SSL.ConfigURL", "file:racine_profil/properties/ssl.client.props");
  8. Ajoutez le fichier JAR du client léger JAX-WS au chemin d'accès aux classes. Ajoutez le fichier racine_serveur_app/runtimes/com.ibm.jaxws.thinclient_8.5.0.jar au chemin d'accès aux classes. Pour plus d'informations sur l'ajout de ce fichier JAR au chemin d'accès aux classes, consultez la rubrique relative au test des clients compatibles avec les services Web.
  9. Demandez le jeton SAML à un STS externe. Le fragment de code suivant montre comment demander le jeton SAML sender-vouches et suppose qu'un STS externe est configuré pour accepter un jeton Username et émettre un jeton SAML 1.1 à l'aide de sender-vouches après validation :
    //Demande du jeton SAML à un STS externe
    WSSFactory factory = WSSFactory.getInstance();
    String STS_URI  = "https://externalstsserverurl:port/TrustServerWST13/services/RequestSecurityToken";
    String ENDPOINT_URL = "http://localhost:9080/WSSampleSei/EchoService";
    WSSGenerationContext gencont1 = factory.newWSSGenerationContext();
    WSSConsumingContext concont1 = factory.newWSSConsumingContext(); 
    HashMap<Object, Object> cbackMap1 = new HashMap<Object, Object>();
    cbackMap1.put(SamlConstants.STS_ADDRESS, STS_URI);
    cbackMap1.put(SamlConstants.SAML_APPLIES_TO, ENDPOINT_URL);
    cbackMap1.put(SamlConstants.TRUST_CLIENT_WSTRUST_NAMESPACE, "http://docs.oasis-open.org/ws-sx/ws-trust/200512");
    cbackMap1.put(SamlConstants.TRUST_CLIENT_COLLECTION_REQUEST, "false");
    cbackMap1.put(SamlConstants.TOKEN_TYPE, WSSConstants.SAML.SAML11_VALUE_TYPE);
    cbackMap1.put(SamlConstants.CONFIRMATION_METHOD, "sender-vouches");
    
    SAMLGenerateCallbackHandler cbHandler1 = new SAMLGenerateCallbackHandler(cbackMap1);
    
    // Ajout de UNT à la demande sécurisée
    UNTGenerateCallbackHandler utCallbackHandler = new UNTGenerateCallbackHandler("testuser", "testuserpwd");
    SecurityToken ut = factory.newSecurityToken(UsernameToken.class, utCallbackHandler);
    
    gencont1.add(ut);
    
    cbHandler1.setWSSConsumingContextForTrustClient(concont1);
    cbHandler1.setWSSGenerationContextForTrustClient(gencont1);
    SecurityToken samlToken = factory.newSecurityToken(SAMLToken.class, cbHandler1, "system.wss.generate.saml");
    
    System.out.println("SAMLToken id = " + samlToken.getId());
    1. Utilisez la méthode WSSFactory newSecurityToken pour définir la façon de demander le jeton SAML à un STS externe.
      Indiquez la méthode suivante pour créer un jeton SAML :
      WSSFactory  newSecurityToken(SAMLToken.class, callbackHandler, "system.wss.generate.saml")
      La demande d'un jeton SAML requiert le droit d'accès Java wssapi.SAMLTokenFactory.newSAMLToken. Utilisez l'outil Policy Tool pour ajouter l'instruction de règle suivante au fichier de règles de sécurité Java ou au fichier du client d'application was.policy :
      permission java.security.SecurityPermission "wssapi.SAMLTokenFactory.newSAMLToken"

      Le paramètre SAMLToken.class définit le type de jeton à créer.

      L'objet callbackHandler contient les paramètres qui définissent les caractéristiques du jeton SAML que vous demandez et les autres paramètres requis pour atteindre le STS et obtenir le jeton SAML. L'objet SAMLGenerateCallbackHandler spécifie les paramètres de configuration décrits dans le tableau ci-dessous :
      Tableau 1. Propriétés de SAMLGenerateCallbackHandler. Ce tableau décrit les paramètres de configuration de l'objet SAMLGenerateCallbackHandler utilisant la méthode de confirmation du sujet sender-vouches.
      Propriété Description Obligatoire
      SamlConstants.CONFIRMATION_METHOD Définit l'utilisation de la méthode de confirmation sender-vouches. Oui
      SamlConstants.TOKEN_TYPE Indique le type de jeton.

      Lorsqu'un client de services Web est associé à des ensembles de règles, cette propriété n'est pas utilisée par l'environnement d'exécution de sécurité des Services Web.

      Spécifiez le type de valeur du jeton à l'aide de l'attribut valueType de la configuration de liaison du générateur de jetons.

      L'exemple pris dans cette procédure utilise un jeton SAML 1.1 ; il est cependant possible d'utiliser la valeur WSSConstants.SAML.SAML20_VALUE_TYPE.

      Oui
      SamlConstants.STS_ADDRESS Indique l'adresse du service de jeton de sécurité (STS).

      Pour l'exemple utilisé dans cette rubrique de tâche, la valeur de cette propriété est https afin de spécifier l'utilisation de SSL pour protéger la demande de jeton SAML.

      Vous devez définir la propriété -Dcom.ibm.SSL.ConfigURL afin d'activer l'utilisation de SSL pour protéger la demande de jeton SAML avec le STS.

      Oui
      SamlConstants.SAML_APPLIES_TO Indique l'adresse du STS cible pour laquelle vous souhaitez utiliser le jeton SAML. Non
      SamlConstants.TRUST_CLIENT_COLLECTION_REQUEST Indique si le système doit demander au STS un jeton unique imbriqué dans un élément RequestSecurityToken (RST) ou plusieurs jetons d'une collection d'éléments RST imbriqués dans un seul élément RequestSecurityTokenCollection (RSTC).

      Le comportement par défaut consiste à demander un jeton unique imbriqué dans un élément RequestSecurityToken (RST) au STS.

      Si vous spécifiez la valeur true pour cette propriété, plusieurs jetons d'une collection d'éléments RST imbriqués dans un seul élément RequestSecurityTokenCollection (RSTC) sont demandés au STS.

      Non
      SamlConstants.TRUST_CLIENT_WSTRUST_NAMESPACE Spécifie l'espace de nom WS-Trust inclus dans la demande WS-Trust.

      La valeur par défaut est WSTrust 1.3.

      Non

      Une instance WSSGenerationContext et une instance WSSConsumingContext sont également définies dans l'objet SAMLGenerateCallbackHandler. L'instance WSSGenerationContext doit contenir un objet UNTGenerateCallbackHandler avec les informations permettant de créer l'élément UsernameToken à envoyer au STS.

      Le paramètre system.wss.generate.saml définit le module de connexion JAAS (Java Authentication and Authorization Service) utilisé pour créer le jeton SAML. Vous devez spécifier une propriété JVM pour définir un fichier de configuration JAAS contenant la configuration requise pour la connexion JAAS, par exemple :
      -Djava.security.auth.login.config=racine_profil/properties/wsjaas_client.conf 
      A la place, vous pouvez également spécifier un fichier de configuration de la connexion JAAS en définissant une propriété système Java dans le modèle de code client, par exemple :
      System.setProperty("java.security.auth.login.config", "racine_profil/properties/wsjaas_client.conf ");
    2. Obtenez l'identificateur du jeton SAML créé.
      Utilisez l'instruction suivante comme une simple test pour le jeton SAML que vous avez créé :
      System.out.println("SAMLToken id = " + samlToken.getId())

Résultats

Vous avez demandé un jeton SAML avec la méthode de confirmation sender-vouches à un STS externe. Après avoir obtenu le jeton, vous l'avez envoyé avec les messages de demande de services Web à l'aide de la protection de transport utilisant les API WSS et le modèle de programmation JAX-WS.

Exemple

Le modèle de code qui suit est une application de client de services Web prête à l'emploi qui illustre la manière de demander un jeton SAML à un STS externe et de l'envoyer dans les messages de demande de services Web avec la protection au niveau transport. Ce modèle de code illustre les étapes de la procédure décrite ci-dessus.

/**
 * Le code source qui suit est un exemple de code créé par IBM Corporation.  
 * Ce code exemple vous est fourni aux seules fins de vous aider  
 * dans l'utilisation de la technologie.  Ce code est livré  en l'état sans aucune garantie 
 * d'aucune sorte.  IBM ne sera en aucun cas responsable de tout dommage résultant de l'utilisation de 
 * cet exemple ce code, même si IBM a été informé de la possibilité de tels dommages.
 */
package com.ibm.was.wssample.sei.cli;

import com.ibm.was.wssample.sei.echo.EchoService12PortProxy;
import com.ibm.was.wssample.sei.echo.EchoStringInput;

import com.ibm.websphere.wssecurity.wssapi.WSSFactory;
import com.ibm.websphere.wssecurity.wssapi.WSSGenerationContext;
import com.ibm.websphere.wssecurity.wssapi.WSSConsumingContext;
import com.ibm.websphere.wssecurity.wssapi.WSSTimestamp;
import com.ibm.websphere.wssecurity.callbackhandler.SAMLGenerateCallbackHandler;
import com.ibm.websphere.wssecurity.callbackhandler.UNTGenerateCallbackHandler;
import com.ibm.websphere.wssecurity.wssapi.token.UsernameToken;
import com.ibm.websphere.wssecurity.wssapi.token.SAMLToken;
import com.ibm.websphere.wssecurity.wssapi.token.SecurityToken;
import com.ibm.wsspi.wssecurity.core.token.config.WSSConstants;
import com.ibm.wsspi.wssecurity.saml.config.SamlConstants;

import java.util.Map;
import java.util.HashMap;

import javax.xml.ws.BindingProvider;

public class SampleSamlSVClient {
	private String urlHost = "localhost";
	private String urlPort = "9443";
	private static final String CONTEXT_BASE = "/WSSampleSei/";
	private static final String ECHO_CONTEXT12 = CONTEXT_BASE+"EchoService12";	
	private String message = "HELLO";
	private String uriString = "https://" + urlHost + ":" + urlPort;
	private String endpointURL = uriString + ECHO_CONTEXT12;
	private String input = message;

	/**
	 * main()
	 * 
	 * voir printusage() pour les arguments de ligne de commande
	 * 
	 * @param args
	 */
	public static void main(String[] args) {
		SampleSamlSVClient sample = new SampleSamlSVClient();
		sample.CallService();
	}

	/**
	 * Les paramètres CallService ont déjà été lus. Appelez les classes de proxy de service. 
	 * 
	 */
	void CallService() {
		String response = "ERROR!:";
		try {
						
         System.setProperty("com.ibm.SSL.ConfigURL", "racine_profil//properties/ssl.client.props");
         System.setProperty("java.security.auth.login.config", "racine_profil/properties/wsjaas_client.conf ");
			

//Demande du jeton SAML à un STS externe
WSSFactory factory = WSSFactory.getInstance();
String STS_URI  = "https://externalstsserverurl:port/TrustServerWST13/services/RequestSecurityToken";
String ENDPOINT_URL = "http://localhost:9080/WSSampleSei/EchoService";
WSSGenerationContext gencont1 = factory.newWSSGenerationContext();
WSSConsumingContext concont1 = factory.newWSSConsumingContext(); 
HashMap<Object, Object> cbackMap1 = new HashMap<Object, Object>();
cbackMap1.put(SamlConstants.STS_ADDRESS, STS_URI);
cbackMap1.put(SamlConstants.SAML_APPLIES_TO, ENDPOINT_URL);
cbackMap1.put(SamlConstants.TRUST_CLIENT_WSTRUST_NAMESPACE, "http://docs.oasis-open.org/ws-sx/ws-trust/200512");
cbackMap1.put(SamlConstants.TRUST_CLIENT_COLLECTION_REQUEST, "false");
cbackMap1.put(SamlConstants.TOKEN_TYPE, WSSConstants.SAML.SAML11_VALUE_TYPE);
cbackMap1.put(SamlConstants.CONFIRMATION_METHOD, "sender-vouches");

SAMLGenerateCallbackHandler cbHandler1 = new SAMLGenerateCallbackHandler(cbackMap1);

// Ajout de UNT à la demande sécurisée
UNTGenerateCallbackHandler utCallbackHandler = new UNTGenerateCallbackHandler("testuser", "testuserpwd");
SecurityToken ut = factory.newSecurityToken(UsernameToken.class, utCallbackHandler);

gencont1.add(ut);

cbHandler1.setWSSConsumingContextForTrustClient(concont1);
cbHandler1.setWSSGenerationContextForTrustClient(gencont1);
SecurityToken samlToken = factory.newSecurityToken(SAMLToken.class, cbHandler1, "system.wss.generate.saml");

System.out.println("SAMLToken id = " + samlToken.getId()); 

			
	        // Initialiser le client de services Web
			EchoService12PortProxy echo = new EchoService12PortProxy();
			echo._getDescriptor().setEndpoint(endpointURL);

			// Configurer les propriétés SOAPAction
			BindingProvider bp = (BindingProvider) (echo._getDescriptor().getProxy());
			Map<String, Object> requestContext = bp.getRequestContext();
			requestContext.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, endpointURL);
			requestContext.put(BindingProvider.SOAPACTION_USE_PROPERTY,	Boolean.TRUE);
			requestContext.put(BindingProvider.SOAPACTION_URI_PROPERTY, "echoOperation");
			
			// Initialiser WSSGenerationContext
			WSSGenerationContext gencont = factory.newWSSGenerationContext();
	        gencont.add(samlToken);		        
	        
	        
	        // Ajouter l'horodatage
	        WSSTimestamp timestamp = factory.newWSSTimestamp();
			gencont.add(timestamp);
	        
	        gencont.process(requestContext);
	        
	        // Générer l'objet d'entrée
			EchoStringInput echoParm = 
				new com.ibm.was.wssample.sei.echo.ObjectFactory().createEchoStringInput();
			echoParm.setEchoInput(input);
			System.out.println(">> CLIENT: SEI Echo to " + endpointURL);		
			
			// Préparer la consommation de l'horodatage dans le message de réponse
			WSSConsumingContext concont = factory.newWSSConsumingContext();	    	
	     	concont.add(WSSConsumingContext.TIMESTAMP); 
	     	concont.process(requestContext);
	     	
			// Appeler le service
			response = echo.echoOperation(echoParm).getEchoResponse();
						
			System.out.println(">> CLIENT: SEI Echo invocation complete.");
			System.out.println(">> CLIENT: SEI Echo response is: " + response);
		} catch (Exception e) {
			System.out.println(">> CLIENT: ERROR: SEI Echo EXCEPTION.");
			e.printStackTrace();
	    }
	}
}
Lorsque ce modèle d'application client de services Web fonctionne correctement, vous recevez des messages du type :
SAMLToken id = _6CDDF0DBF91C044D211271166233407
Retrieving document at 'file:racine_profil/.../wsdl/'.
>> CLIENT: SEI Echo to http://localhost:9443/WSSampleSei/EchoService12
>> CLIENT: SEI Echo invocation complete.
>> CLIENT: SEI Echo response is: SOAP12==>>HELLO

Icône indiquant le type de rubrique Rubrique de tâche



Icône d'horodatage Dernière mise à jour: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_configsamlsendervouches_transportlevel_requeststs
Nom du fichier : twbs_configsamlsendervouches_transportlevel_requeststs.html