Envoi de jetons SAML sender-vouches (envoyeur garant) à l'aide des API WSS avec la protection au niveau du transport SSL

Vous pouvez créer des jetons SAML auto-générés avec la méthode de confirmation du sujet sender-vouches (envoyeur garant), puis les envoyer dans des messages de demande de services Web dotés de la protection au niveau du transport SSL, à l'aide du modèle de programmation JAX-WS (Java™ API for XML-Based Web Services) et des API WSS (Web Services Security).

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 avez la possibilité de créer un client de services Web qui utilise les jetons SAML avec la méthode de confirmation du sujet sender-vouches (envoyeur garant) dans les messages de demande SOAP, en utilisant les interfaces de programmation de sécurité des services Web. L'emploi des interfaces de programmation dans un client de services Web pour définir l'utilisation de jetons SAML avec confirmation du sujet sender-vouches et la protection des messages au niveau du transport, constitue une solution alternative par rapport aux ensembles de règles et aux configurations de liaisons.

Il est possible de créer un jeton SAML auto-généré, puis de l'envoyer dans les messages de demande de services Web à partir d'un client de services Web. 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 section Procédure, et la section Exemple contient un modèle de client de services Web prêt à l'emploi.

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. 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. 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.
    3. Sous 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. Dans le code du client de services Web, utilisez la méthode CallService() pour définir le fichier de propriétés contenant les paramètres de configuration requis pour la création du jeton SAML auto-généré.

    La méthode CallService() spécifie les paramètres de configuration requis par l'environnement d'exécution de sécurité de services Web pour créer un SAMLToken auto-généré.

    Le fragment de code suivant illustre l'utilisation de la méthode CallService() pour spécifier les paramètres de configuration de sécurité de services Web :
    public static void main(String[] args) {
      SampleSamlSVClient sample = new SampleSamlSVClient();
      sample.CallService();
     }
    
    /**
     * Les paramètres CallService ont déjà été lus. Appeler les classes de proxy de service
     * 
     */
    void CallService() {
      String response = "ERROR!:";
      try {
        System.setProperty("java.security.auth.login.config", "racine_profil/properties/wsjaas_client.conf ");
        // Initialiser l'objet WSSFactory 
        WSSFactory factory = WSSFactory.getInstance();
    
        // Initialiser WSSGenerationContext
        WSSGenerationContext gencont = factory.newWSSGenerationContext();
        // Initialiser la configuration de l'émetteur SAML via les propriétés personnalisées
        HashMap <Object, Object> customProps = new HashMap<Object,Object>();
    
        customProps.put(SamlConstants.ISSUER_URI_PROP, "example.com");
        customProps.put(SamlConstants.TTL_PROP, "3600000");
        customProps.put(SamlConstants.KS_PATH_PROP, "keystores/saml-provider.jceks");
        customProps.put(SamlConstants.KS_TYPE_PROP, "JCEKS");
        customProps.put(SamlConstants.KS_PW_PROP, "{xor}LCswLTovPiws");
        customProps.put(SamlConstants.KEY_ALIAS_PROP, "samlissuer");
        customProps.put(SamlConstants.KEY_NAME_PROP, "CN=SAMLIssuer, O=EXAMPLE");
        customProps.put(SamlConstants.KEY_PW_PROP, "{xor}NDomLz4sLA==");
        customProps.put(SamlConstants.TS_PATH_PROP, "keystores/saml-provider.jceks");
        customProps.put(SamlConstants.TS_TYPE_PROP, "JCEKS");
        customProps.put(SamlConstants.TS_PW_PROP, "{xor}LCswLTovPiws");  
        gencont.add(customProps); //Ajouter des propriétés personnalisées

    Pour plus d'informations sur la façon de définir des propriétés de configuration applicables au jeton, consultez la rubrique relative à la configuration d'un jeton SAML lors de sa création.

  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. Créez le jeton SAML auto-généré. Le fragment de code ci-dessous illustre la création du jeton SAML sender-vouches :
    // Créer SAMLToken
    HashMap<Object, Object> map = new HashMap<Object, Object>();
    map.put(SamlConstants.CONFIRMATION_METHOD, "sender-vouches");
    map.put(SamlConstants.TOKEN_TYPE, WSSConstants.SAML.SAML20_VALUE_TYPE);
    map.put(SamlConstants.SAML_NAME_IDENTIFIER, "Alice");
    map.put(SamlConstants.SIGNATURE_REQUIRED, "true");			
    SAMLGenerateCallbackHandler callbackHandler = new SAMLGenerateCallbackHandler(map);	
    SecurityToken samlToken = factory.newSecurityToken(SAMLToken.class, callbackHandler, "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 créer le jeton SAML.
      Indiquez la méthode suivante pour créer un jeton SAML :
      WSSFactory  newSecurityToken(SAMLToken.class, callbackHandler, "system.wss.generate.saml")
      La création d'un jeton SAML requiert le droit d'accès Java wssapi.SAMLTokenFactory.newSAMLToken. Utilisez PolicyTool 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 créez. Cet objet pointe vers un objet SAMLGenerateCallbackHandler qui définit 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

      Utilise la valeur de la constante WSSConstants.SAML.SAML20_VALUE_TYPE pour définir un type de jeton SAML 2.0.

      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. Dans ce scénario, définissez 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 2.0 ; il est cependant possible d'utiliser la valeur WSSConstants.SAML.SAML11_VALUE_TYPE.

      Oui
      SamlConstants.SAML_NAME_IDENTIFIER

      Définit l'identité d'un utilisateur, par exemple monnom comme valeur de NameID dans le jeton SAML.

      Si vous ne définissez pas ce paramètre lors de l'utilisation du client léger de services Web JAX-WS, la valeur de NameID ne contient aucune information utile.

      Si vous utilisez un client géré de services web, par exemple une application Java Platform Enterprise Edition (Java EE) effectuant un appel de demande de services web, l'environnement d'exécution de sécurité des services Web tente d'extraire les informations de sécurité relatives à l'utilisateur à partir du contexte de sécurité. De la même façon, si vous ne définissez pas ce paramètre pour un client géré de services Web, la valeur de NameID contient l'identificateur de nom UNAUTHENTICATED.

      Cette propriété n'est pas utilisée si votre client de services Web est associé à des ensembles de règles. Consultez la rubrique relative à l'envoi de l'identité et des attributs du jeton SAML pour en savoir plus sur ce sujet.

      Non
      SamlConstants.SIGNATURE_REQUIRED

      Définit si l'émetteur doit signer le jeton numériquement.

      La valeur true indique que l'émetteur doit signer le jeton SAML de façon numérique. Il s'agit de la valeur par défaut.

      Non
      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 créé un jeton SAML auto-généré avec la méthode de confirmation sender-vouches avec méthode de confirmation puis avez envoyé ce jeton avec des messages de demande de services Web à l'aide du modèle de programmation JAX-WS et des API WSS.

Exemple

Le modèle de code qui suit est une application de client de services Web qui illustre la façon de créer un jeton SAML auto-généré, puis de l'envoyer dans les messages de demande de services Web. 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.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 = "9081";
  private static final String CONTEXT_BASE = "/WSSampleSei/";
  private static final String ECHO_CONTEXT12 = CONTEXT_BASE+"EchoService12";	
  private String message = "HELLO";
  private String uriString = "http://" + 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("java.security.auth.login.config", "racine_profil/properties/wsjaas_client.conf ");

      // Initialiser l'objet WSSFactory
      WSSFactory factory = WSSFactory.getInstance();
      // Initialiser WSSGenerationContext
      WSSGenerationContext gencont = factory.newWSSGenerationContext();
      // Initialiser la configuration de l'émetteur SAML via les propriétés personnalisées
	    HashMap<Object, Object> customProps = new HashMap<Object,Object>();

      customProps.put(SamlConstants.ISSUER_URI_PROP, "example.com");
      customProps.put(SamlConstants.TTL_PROP, "3600000");
      customProps.put(SamlConstants.KS_PATH_PROP, "keystores/saml-provider.jceks");
      customProps.put(SamlConstants.KS_TYPE_PROP, "JCEKS");
      customProps.put(SamlConstants.KS_PW_PROP, "{xor}LCswLTovPiws");
      customProps.put(SamlConstants.KEY_ALIAS_PROP, "samlissuer");
      customProps.put(SamlConstants.KEY_NAME_PROP, "CN=SAMLIssuer, O=EXAMPLE");
      customProps.put(SamlConstants.KEY_PW_PROP, "{xor}NDomLz4sLA==");
      customProps.put(SamlConstants.TS_PATH_PROP, "keystores/saml-provider.jceks");
      customProps.put(SamlConstants.TS_TYPE_PROP, "JCEKS");
      customProps.put(SamlConstants.TS_PW_PROP, "{xor}LCswLTovPiws");  
      gencont.add(customProps); //Ajouter des propriétés personnalisées

      // Créer SAMLToken
      HashMap<Object, Object> map = new HashMap<Object, Object>();
      map.put(SamlConstants.CONFIRMATION_METHOD, "sender-vouches");
      map.put(SamlConstants.TOKEN_TYPE, WSSConstants.SAML.SAML20_VALUE_TYPE);
      map.put(SamlConstants.SAML_NAME_IDENTIFIER, "Alice");
      map.put(SamlConstants.SIGNATURE_REQUIRED, "true");			
      SAMLGenerateCallbackHandler callbackHandler = new SAMLGenerateCallbackHandler(map);
      SecurityToken samlToken = factory.newSecurityToken(SAMLToken.class, callbackHandler, "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");

      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_usingwssapi
Nom du fichier : twbs_configsamlsendervouches_transportlevel_usingwssapi.html