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
- 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 :
- Téléchargez l'exemple d'application JaxWSServicesSamples. Le modèle d'application JaxWSServicesSamples n'est pas installé par défaut.
- 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.
- 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é.
- 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 :
- Cliquez sur .
- Cliquez sur la règle
WS-Security dans la table des règles.
- Cliquez sur le lien Règle principale ou sur le lien Règle d'amorce.
- Cliquez sur Règles de jeton de demande dans la section Détails des règles.
- 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).
- Créez une copie des liaisons générales par défaut SAML Bearer Provider Sample.
- Attribuez-lui un nom comportant "sender-vouches", par exemple SAML sender-vouches
provider binding.
- 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).
- 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.
- 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 :
- Cliquez sur .
- Cliquez sur le lien WC_defaulthost_secure.
- Sous Articles liés, cliquez sur le lien Configurations SSL.
- Sélectionnez la ressource NodeDefaultSSLSettings.
- Cliquez sur le lien Paramètres de la qualité de protection (QoP).
- 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).
- 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.
- 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.
- 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());
- 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 ");
- 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