API de bibliothèque de jetons SAML

Les interfaces de programme d'application de bibliothèque de jetons SAML fournissent des méthodes utilisables pour la création, la validation, l'analyse et l'extraction de jetons SAML.

Généralités

L'implémentation de bibliothèque SAML version 1.1 et SAML version 2.0 contient trois types de confirmation du sujet : holder-of-key (détenteur de clé - HoK), bearer (porteur), et sender-vouches (envoyeur garant). Vous pouvez utiliser les API de bibliothèque de jetons SAML pour créer, valider et extraire les attributs d'un jeton SAML HoK ou bearer. La propagation des jetons SAML à partir des messages SOAP des services Web est également présentée. L'utilisation des API est illustrée par un exemple de code.

WebSphere Application Server avec SAML contient des ensembles de règles destinés à la prise en charge de la confirmation du sujet par les méthodes bearer et holder-of-key.

Les sections qui suivent présentent la création d'un jeton SAML à l'aide des API de bibliothèque de jetons SAML :
  1. Configuration des paramètres de création du jeton
  2. Création d'une instance de fabrique de jetons
  3. Création du jeton SAML
  4. Exemple de code
L'API SAMLTokenFactory est la principale interface de programme d'application de bibliothèque de jetons SAML. SAMLTokenFactory prend en charge la création, l'analyse et la validation des jetons SAML 1.1 et SAML 2.0. Elle sert à créer des objets de configuration ProviderConfid, RequesterConfig, et ConsumerConfig pour définir les caractéristiques du jeton SAML requis. Pour plus d'informations, reportez-vous à la documentation de l'API.
Différentes opérations peuvent être réalisées après la création d'un jeton, notamment :
Remarque : A compter de l'édition 8 de WebSphere Application Server, vous pouvez utiliser la classe com.ibm.websphere.wssecurity.wssapi.token.SAMLToken dans l'API WSS (Web Services Security). En l'absence de toute ambiguïté, nous utilisons le terme SAMLToken pour désigner cette classe plutôt que son nom de package complet. Vous pouvez utiliser l'API WSS pour demander un traitement SAMLToken depuis un STS (Security Token Service) externe, afin de propager les SAMLTokens dans les messages de demande SOAP, ainsi que pour utiliser une clé symétrique ou asymétrique identifiée par des SAMLTokens pour protéger les messages SOAP.

Le support SAML de l'API WSS complète les interfaces com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory et com.ibm.websphere.wssecurity.wssapi.trust.WSSTrustClient. Les SAMLTokens générés par un appel à la méthode com.ibm.websphere.wssecurity.wssapi.WSSFactory newSecurityToken() peuvent être traités par les interfaces de programmation SAMLTokenFactory et WSSTrustClient. Inversement, les SAMLTokens générés par SAMLTokenFactory ou renvoyés par WSSTrustClient peuvent être utilisés dans l'API WSS. Le choix de l'API à utiliser dans votre application dépend de vos besoins spécifiques. Le support SAML de l'API WSS est intégré et autonome en ce sens qu'il fournit une fonctionnalité équivalente à celle des interfaces SAMLTokenFactory et WSSTrustClient sur le plan des applications client de services Web. L'interface SAMLTokenFactory dispose de fonctions supplémentaires pour valider les SAMLTokens et créer le sujet JAAS qui représente les SAMLTokens authentifiés. Cette validation est utile du côté du fournisseur de services Web. Lorsque vous développez des applications appelées à consommer des SAMLTokens, l'interface de programmation SAMLTokenFactory est celle qui convient le mieux à vos besoins.

Configuration des paramètres de création du jeton

Lors de la configuration des paramètres de création d'un jeton, les informations de configuration concernent l'entité à l'origine de la demande, l'entité émettrice ou l'entité destinataire. Dans l'exemple qui suit, les informations de configuration sont définies pour l'entité à l'origine de la demande et l'entité émettrice. Pour chaque type de confirmation du sujet pris en charge, la bibliothèque de jetons SAML fournit des attributs pré-configurés pour l'entité à l'origine de la demande. Ces attributs sont utilisés durant la création du jeton SAML autogénéré par l'environnement d'exécution WebSphere. Un jeton SAML autogénéré est ainsi appelé parce qu'il est généré localement au lieu d'être demandé à un service de jeton de sécurité (STS). Si vous devez les personnaliser pour un paramètre par défaut, utilisez le paramètre RequesterConfig. Pour plus d'informations sur le paramètre RequesterConfig, consultez la rubrique relative à l'API SAMLTokenFactory.

Commencez par définir les informations de configuration du demandeur :
// Setup the requester's configuration information (parameters needed 
// to create the token specified as configuration properties).
// in this case we are using the configuration information to create a 
// SAML token that contains a symmetric holder of key subject              
// confirmation.
RequesterConfig requesterData = 
     samlFactory.newSymmetricHolderOfKeyTokenGenerateConfig();
Définissez ensuite l'alias de la clé publique du destinataire et facultativement, la méthode d'authentification :
// Set recipient's public key alias 
// (in this example we use SOAPRecipient), so the provider can encrypt secret 
// key for the receiving end. 
requesterData.setKeyAliasForAppliesTo("SOAPRecipient");

// Set the authentication method that took place. This is an optional     
// parameter.               
reqData.setAuthenticationMethod("Password"); 
Puis, définissez les attributs de configuration de l'émetteur :
// Set issuer information by instantiating a default ProviderConfig.
// See javadocs for the SAMLTokenFactory class on the details of the   
// default values and how to modify them.
ProviderConfig samlIssuerCfg =   
  samlFactory.newDefaultProviderConfig("WebSphereSelfIssuer");

Création d'une instance de fabrique de jetons

Utilisez la classe SAMLTokenFactory, en indiquant version 1.1 ou version 2.0 comme type de jeton SAML. Définissez les paramètres supplémentaires pour la création du jeton SAML.
Utilisez la classe SAMLTokenFactory avec le type de jeton SAML :
// Instantiate a token factory based on the version level of the token 
// to use. In this example we use the SAML v1.1 token factory. 
SAMLTokenFactory samlFactory = 
SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11);
Définissez les paramètres supplémentaires dans l'objet CredentialConfig à l'aide du sujet appelant ou de runAsSubject :
// Retrieve the caller subject or the runAsSubject (depending on your 
// scenario) then use the Subject to get a CredentialConfig object     
// using the SAML token library.
// This invocation requires the    
// wssapi.SAMLTokenFactory.newCredentialConfig" Java Security  
// permission.
CredentialConfig cred = samlFactory.newCredentialConfig(runAsSubject);

Création du jeton SAML

Créez le jeton SAML à l'aide de la fabrique de jetons :
// Now create the SAML token. This invocation requires the 
// "wssapi.SAMLTokenFactory.newSAMLToken" Java Security permission.
SecurityToken samlToken = 
                samlFactory.newSAMLToken(cred, reqData, samlIssuerCfg);

Validation du jeton SAML

Une entité qui reçoit un jeton SAML, par exemple un service métier, peut utiliser l'API de bibliothèque de jetons SAML pour valider le jeton avant de l'utiliser. Par exemple, le service doit valider le jeton avant d'en extraire les attributs SAML pour le demandeur. Le document d'une assertion SAML existante peut être validé en utilisant les données de configuration provenant du consommateur.
Le code d'API ci-dessous valide le jeton :
ConsumerConfig consumerConfig = samlFactory.newConsumerConfig();
	XMLStructure xml =
	try {
	   SAMLToken token = samlFactory.newSAMLToken( consumerConfig, XMLStructure xml );
	   // token successfully validated 
	} catch(WSSException e){
	 // token failed validation
	}

Identité d'un jeton SAML mappée à un sujet

Un jeton SAML peut servir à créer un sujet. L'identificateur de nom à l'intérieur du jeton est mappé à un utilisateur dans le registre d'utilisateurs pour obtenir le nom principal du sujet.
Subject subject;
SAMLToken aSAMLToken = …;
  try {
        subject = samlFactory.newSubject(aSAMLToken);
  } catch(WSSException e) {
  }

Analyse des éléments de l'assertion

Le destinataire d'un jeton SAML peut analyser et extraire les éléments d'assertion d'un jeton SAML en utilisant les API SAMLToken contenues dans l'API de bibliothèque de jetons SAML. Par exemple, l'heure de création du jeton peut être extraite à l'aide du code suivant :
Date dateCreated = samlToken.getSamlCreated();
Pour extraire le nom de l'émetteur du jeton et la méthode de confirmation, procédez comme suit :
String confirmationMethpo = samlToken.getConfirmationMethod();
String issuerName = samlToken.getSAMLIssuerName();
Si la méthode de confirmation du sujet extraite est holder-of-key, vous pouvez vous servir de l'API suivante pour récupérer les octets correspondant aux éléments de clé :
byte[] hokBytes = samlToken.getHolderOfKeyBytes();

Pour plus d'informations sur les API SAML, consultez la documentation des API relative à l'interface SAMLToken.

Extraction des attributs du jeton SAML

Vous pouvez extraire les attributs SAML provenant de l'entité initiatrice (demandeur de service) à l'aide de l'API SAMLToken, comme le montre le fragment de code ci-dessous.
// Get all attributes
List<SAMLAttribute> allAttributes =         
             ((SAMLToken) samlToken).getSAMLAttributes();

// Iterate over the attribute and process accordingly
Iterator<SAMLAttribute> iter = allAttributes.iterator();
while (iter.hasNext()) 
{
    SAMLAttribute anAttribute = iter.next();

    // Handle attributes
    String attributeName = anAttribute.getName();
    String[] attributeValues = anAttribute.getStringAttributeValue();
 
}

Exemple de code

L'exemple de code illustre la façon d'utiliser les API de bibliothèque de jetons SAML pour accomplir certaines des opérations décrites précédemment. La propriété de JVM qui pointe vers l'emplacement du fichier de propriétés SAML est une condition requise pour l'exécution de ce code. Le fichier de propriétés SAML SAMLIssuerConfig.properties doit contenir les attributs de configuration de l'émetteur (fournisseur) du jeton SAML.

L'emplacement par défaut du fichier SAMLIssuerConfig.properties pour le niveau cellule est : racine_serveur_app/profiles/$PROFIL/config/cells/$NOMCELLULE/sts.

Pour le niveau serveur, l'emplacement est : racine_serveur_app/profiles/$PROFIL/config/cells/$NOMCELLULE/nodes/$NOMNOEUD/servers/$NOMSERVEUR.

IssuerURI=WebSphere
TimeToLive=3600000
KeyStorePath=c:/samlsample/saml-provider.jceks
KeyStoreType=jceks
KeyStorePassword=myissuerstorepass
KeyAlias=samlissuer
KeyName=CN=SAMLIssuer, O=IBM, C=US
KeyPassword=xxxxxxxxx
TrustStorePath=c:/samlsample/saml-provider.jceks
TrustStoreType=jceks
TrustStorePassword=yyyyyyyy

package samlsample;

import java.util.List;
import java.util.Iterator;
import java.util.ArrayList;
import javax.security.auth.Subject;

// Import methods from the SAML token library
import com.ibm.wsspi.wssecurity.saml.data.SAMLAttribute;
import com.ibm.websphere.wssecurity.wssapi.token.SAMLToken;
import com.ibm.wsspi.wssecurity.saml.config.ProviderConfig;
import com.ibm.wsspi.wssecurity.saml.config.RequesterConfig;
import com.ibm.wsspi.wssecurity.saml.config.CredentialConfig;
import com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory;
import com.ibm.websphere.wssecurity.wssapi.token.SecurityToken;
import com.ibm.wsspi.wssecurity.core.token.config.RequesterConfiguration;

public class SamlAPIsample {
	
public void testSAMLTokenLibrary() throws Exception {

try {
  // Get an instance of the SAML v1.1 token factory
  SAMLTokenFactory samlFactory = SAMLTokenFac  
  tory.getInstance(SAMLTokenFactory.WssSamlV11Token11);

  // Generate default requester data for a subject confirmation of 
  // type holder-of-key (secret key).
  RequesterConfig requesterData =
       samlFactory.newSymmetricHolderOfKeyTokenGenerateConfig();
        
  // Set the recipient's key alias, so that the issuer can encrypt
  // the secret key for recipient as part of the subject confirmation. 
  requesterData.setKeyAliasForAppliesTo("SOAPRecipient");
        
  // Set the authentication method that took place. 
  requesterData.setAuthenticationMethod("Password"); 

  System.out.println("default holder of key confirmation key type is: "+
    Requester  
  Data.getRSTTProperties().get(RequesterConfiguration.RSTT.KEYTYPE));
  Requester  
  Data.getRSTTProperties().put(RequesterConfiguration.RSTT.KEYTYPE, 
      "http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey");

  requesterData.getRSTTProperties().put(
                     RequesterConfiguration.RSTT.APPLIESTO_ADDRESS,
				                                
                     "http://localhost:9080");

  requesterData.setConfirmationMethod("holder-of-key");

  // Set the recipient's key alias so that token infomation such as 
  // the secret HoK can be encrypted by the issuer and decrypted by the 
  // recipient.
  requesterData.setKeyAliasForAppliesTo("SOAPRecipient"); 
  requesterData.setAuthenticationMethod("Password");
  requesterData.getRSTTProperties().put(
  RequesterConfiguration.RSTT.ENCRYPTIONALGORITHM, 			                               
                      "http://www.w3.org/2001/04/xmlenc#aes128-cbc");
  requester  
  Data.getRSTTProperties().put(RequesterConfiguration.RSTT.TOKENTYPE,
      "http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-  
       1.1#SAMLV1.1");
		requesterData.setRequesterIPAddress("9.53.52.65");

  // Print requester configuration items
  System.out.println("authentication method for requester is: "+
	            requesterData.getAuthenticationMethod());
  System.out.println("confirmation method for requester is: "+
                    requesterData.getConfirmationMethod());
  System.out.println("key alias for requester is: "+
            requesterData.getKeyAliasForRequester());
  System.out.println("key alias for recipient as set in requester config is "+
          requesterData.getKeyAliasForAppliesTo());
  System.out.println("holder of key confirmation key type is: "+
             Requester        
  Data.getRSTTProperties().get(RequesterConfiguration.RSTT.KEYTYPE));

  // Get an instance of the Credential config object		
  CredentialConfig cred = samlFactory.newCredentialConfig();
  cred.setRequesterNameID("Alice");

  // Set some user attributes
  ArrayList<SAMLAttribute> userAttrs = new ArrayList<SAMLAttribute>();
  SAMLAttribute anAttribute = new SAMLAttribute("EmployeeInfo", 
		    new String[] {"GreenRoofing","JohnDoe", "19XY981245"},
                null, "WebSphere Namespace", null, "JohnDoeInfo " );
  userAttrs.add(anAttribute);
  cred.setSAMLAttributes(userAttrs);
		
  // Get default provider configuration
  ProviderConfig samlIssuerCfg = 
    samlFactory.newDefaultProviderConfig("WebSphereSelfIssuer");
  System.out.println("time to live from the default provider config: "+
        		  samlIssuerCfg.getTimeToLive()); 
  System.out.println("keyStore path from default provider config: "+
                    samlIssuerCfg.getKeyStoreConfig().getPath()); 
  System.out.println("keyStore type from default provider config: "+
                   samlIssuerCfg.getKeyStoreConfig().getType()); 
  System.out.println("key alias from default provider config: "+
     	             samlIssuerCfg.getKeyInformationConfig().getAlias());
        
  // Generate the SAML token
  SecurityToken samlToken = 
         samlFactory.newSAMLToken(cred, requesterData, samlIssuerCfg);
  System.out.println("token's creation Date is:  
                "+((SAMLToken)samlToken).getSamlCreated().toString());
  System.out.println("token's expiration Date is: 
               "+((SAMLToken)samlToken).getSamlExpires().toString());
  System.out.println("token's subject confirmation method is: 
                  "+((SAMLToken)samlToken).getConfirmationMethod());

       
  // Create a Subject, mapping the name identifier in the token to a user 
  // in the user registry to obtain the Principal name
  Subject subject = samlFactory.newSubject((SAMLToken)samlToken);

  // Retrieve attributes from the token
  List<SAMLAttribute> allAttributes =         
                        ((SAMLToken)samlToken).getSAMLAttributes();

  // Iterate through the attributes and process accordingly
  Iterator<SAMLAttribute> iter = allAttributes.iterator();
  while (iter.hasNext()) {
   SAMLAttribute attribute = iter.next();
   String attributeName = attribute.getName();
   String[] attributeValues = attribute.getStringAttributeValue();
   System.out.println("attribute name = "+ attributeName + 
                       "  attribute value = ["+
                       attributeValues[0]+ ", 
                       "+attributeValues[1]+ ", "+
                       attributeValues[2]+"]");
  }
  } catch(Exception e) {
     e.printStackTrace();
  } 
 }
}

Exemple de sortie de code

default holder of key confirmation key type is: http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey
authentication method for requester is: Password
confirmation method for requester is: holder-of-key
key alias for requester is: null
key alias for recipient as set in requester config is SOAPRecipient
holder of key confirmation key type is: http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey
time to live from the default provider config: 3600000
keyStore path from default provider config: C:/saml/samlsample/saml-provider.jceks
keyStore type from default provider config: jceks
key alias from default provider config: samlissuer
token's creation Date is: Mon Sep 14 15:49:00 CDT 2009
token's expiration Date is: Mon Sep 14 16:49:00 CDT 2009
token's subject confirmation method is: urn:oasis:names:tc:SAML:1.0:cm:holder-of-key
attribute name = EmployeeInfo  attribute value = [GreenRoofing, JohnDoe, 19XY981245]

Icône indiquant le type de rubrique Rubrique de référence



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=rwbs_libraryapisaml
Nom du fichier : rwbs_libraryapisaml.html