Création d'un jeton SAML holder-of-key à l'aide de l'API

Le jeton SAML holder-of-key (HoK - détenteur de clé) constitue une extension de l'interface publique du jeton de sécurité dans WebSphere Application Server, et peut servir de jeton de protection. WebSphere Application Server contient une API de bibliothèque SAML pour la création d'un jeton holder-of-key.

Pourquoi et quand exécuter cette tâche

La création d'un jeton SAML requiert trois paramètres :
  • com.ibm.wsspi.wssecurity.saml.config.RequesterConfig
  • com.ibm.wsspi.wssecurity.saml.config.ProviderConfig
  • com.ibm.wsspi.wssecurity.saml.config.CredentialConfig
Suivez la procédure ci-dessous pour créer une instance pour chacun des paramètres, puis créer un jeton SAML holder-of-key. A la place de CredentialConfig, vous pouvez utiliser javax.security.auth.Subject. Pour plus d'informations, consultez la documentation de l'API.

Procédure

  1. Créez une instance com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory avec la version SAML du jeton comme paramètre. Les versions de SAMLToken prises en charge sont http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1 et http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0. L'instance SAMLTokenFactory est un singleton et autorise donc les unités d'exécution multiples. Utilisez l'une des lignes de code suivantes pour créer l'instance, en fonction de la version du jeton.
    • Utilisez la ligne de code ci-dessous pour créer une instance com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory pour un jeton SAML version 1.1 :
      SAMLTokenFactory samlFactory = SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11);
    • Utilisez la ligne de code ci-dessous pour créer une instance com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory pour un jeton SAML version 2.0 :
      SAMLTokenFactory samlFactory = SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token20);
  2. L'instance SAMLTokenFactory est utilisée pour créer une instance RequesterConfig, qui détermine la façon dont le jeton est généré, en fonction des besoins d'authentification du demandeur. Servez-vous de l'une des lignes de code suivantes pour créer l'instance RequesterConfig, selon que le jeton doit utiliser une clé secrète (clé symétrique) ou une clé publique :
    • Utilisez la ligne de code ci-dessous pour créer une instance RequesterConfig par défaut pour le jeton SAML holder-of-key utilisant une clé secrète (clé symétrique), incluse dans l'élément SubjectConfirmation :
      RequesterConfig reqData = samlFactory. newSymmetricHolderOfKeyTokenGenerateConfig ();
      Vous devez également définir l'alias de la clé du service cible afin que le fournisseur puisse chiffre sa clé secrète :
      reqData.setKeyAliasForAppliesTo("SoapRecipient");
    • Utilisez la ligne de code ci-dessous pour créer une instance RequesterConfig par défaut pour le jeton SAML holder-of-key utilisant une clé publique, incluse dans l'élément SubjectConfirmation :
      RequesterConfig reqData = samlFactory. newAsymmetricHolderOfKeyTokenGenerateConfig ();
      Vous devez également définir l'alias de la clé du demandeur afin que le fournisseur puisse extraire sa clé secrète et l'inclure dans l'élément SubjectConfirmation :
      reqData.setKeyAliasForRequester(“SOAP Initiator”);
    L'instance RequestConfig suffit pour générer un jeton holder-of-key simple, mais des assertions supplémentaires peuvent être incluses dans le jeton SAML en personnalisant l'instance RequesterConfig. Par exemple, pour inclure des données d'authentification par mot de passe dans le jeton, faites appel à la méthode setAuthenticationMethod :
    reqData.setAuthenticationMethod(“password”);
  3. Utilisez l'API SAMLTokenFactory pour créer une instance ProviderConfig, qui décrit l'émetteur du jeton. L'instance ProviderConfig définit le nom de l'émetteur, ainsi que les caractéristiques du fichier de clés et du fichier de clés certifiées, qui identifient la clé de chiffrement et de signature SAML. L'instance ProviderConfig est créée à l'aide des valeurs d'un fichier de propriétés. Le fichier de propriétés définit la valeur par défaut de l'objet ProviderConfig. Dans un environnement client Java™, ce fichier de propriétés est défini par la propriété système JVM com.ibm.webservices.wssecurity.platform.SAMLIssuerConfigDataPath.
    Dans l'environnement d'exécution WebSphere Application Server, le nom du fichier de propriétés est SAMLIssuerConfig.properties. Le fichier peut se trouver soit dans le répertoire de configuration de niveau serveur, soit dans le répertoire de configuration de niveau cellule, dans cet ordre de priorité. Voici un exemple de chemin de niveau serveur :
    racine_serveur_app/profiles/$PROFILE/config/cells/$CELLNAME/nodes/$NODENAME/servers/$SERVERNAME/SAMLIssuerConfig.properties
    Voici un exemple de chemin de niveau cellule :
    racine_serveur_app/profiles/$PROFILE/config/cells/$CELLNAME/sts/SAMLIssuerConfig.properties

    La propriété système JVM com.ibm.webservices.wssecurity.platform.SAMLIssuerConfigDataPath est ignorée si elle est définie dans l'environnement d'exécution du serveur. Pour une description détaillée de toutes les propriétés, consultez les informations relatives à la configuration d'un jeton SAML pendant sa création.

    Utilisez la ligne de code suivante pour créer une instance ProviderConfig par défaut :

    ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig(“any issuer name”);
    Le nom de l'émetteur est facultatif. Si le nom de l'émetteur est défini, il apparaît dans l'assertion SAML. S'il ne l'est pas, un nom d'émetteur par défaut est pris dans le fichier SAMLIssuerConfig.properties.
  4. Facultatif : Lors de la création d'un jeton SAML, SAMLTokenFactory utilise soit un sujet JAAS (Java Authentication and Authorization Service), soit une instance CredentialConfig pour alimenter le nouveau jeton SAML. Pour alimenter le jeton à partir d'un sujet JAAS, générez un sujet JAAS représentant le client demandeur ou l'identité de l'unité d'exécution à l'aide de l'API com.ibm.websphere.security.auth.WSSubject getCallerSubject() ou getRunAsSubject().

    Lorsque le sujet JAAS est utilisé pour créer un jeton SAML, l'API SAMLTokenFactory recherche un objet SAMLToken dans la liste du sujet PrivateCredentials. Si l'objet SAMLToken existe, les objets NameId ou NameIdentifier sont copiés dans le nouveau jeton SAML. SAMLTokenFactory copie également les attributs SAML et la méthode AuthenticationMethod depuis le jeton SAML existant vers le nouveau jeton SAML. Le nouveau jeton SAML contient un nouveau nom d'émetteur, un nouveau certificat signataire, une méthode de confirmation, un nouvel élément KeyInfo pour la méthode de confirmation holder-of-key (HoK - détenteur de clé), et de nouvelles conditions NotBefore et NotOnAfter. Ces paramètres sont déterminés par les paramètres de configuration des objets ProviderConfig et RequesterConfig.

    Si le sujet ne contient pas d'objet SAMLToken, seul le nom principal WSPrincipal et copié à partir du sujet vers le nouveau jeton SAML. Aucun autre attribut du sujet n'est copié dans le nouveau jeton SAML. De la même façon, le nom de l'émetteur, le certificat signataire, la méthode de confirmation, l'élément KeyInfo pour la méthode holder-of-key et les conditions NotBefore et NotOnOrAfter sont déterminées par les paramètres de configuration des objets ProviderConfig et RequesterConfig.

    La méthode RunAsSubject peut aussi être utilisée sur l'unité d'exécution pour créer le jeton SAML. Lorsque vous utilisez cette méthode, ne transmettez jamais le sujet JAAS ni l'objet CredentialConfig à SAMLTokenFactory pour créer le jeton SAML. En effet, le contenu du jeton SAML existant est copié dans le nouveau jeton SAML, comme décrit ci-dessus.

    Une autre façon de créer un jeton SAML est de programmer l'alimentation des éléments SAML NameId et Attributes à partir de l'objet CredentialConfig. Utilisez cette méthode dans les circonstances suivantes :
    • Le nouveau jeton SAML doit contenir des attributs SAML personnalisés.
    • La création manuelle du jeton SAML est préférée à l'alimentation automatique du jeton SAML à partir d'un sujet JAAS à l'aide de SAMLTokenFactory.
    • Le sujet ne contient pas de jeton SAML.
    • Aucun sujet JAAS n'est disponible.

    Pour créer un objet CredentialConfig sans utiliser le sujet JAAS, utilisez cette ligne de code :

    CredentialConfig cred = samlFactory.newCredentialConfig ();
    Aucune valeur initiale n'est fournie pour l'objet CredentialConfig, et vous devez donc utiliser des méthodes d'accès set pour alimenter l'objet CredentialConfig.
    Pour alimenter les éléments SAML NameIdentifier ou NameID, utilisez la ligne de code suivante :
    cred.setRequesterNameID("any name");
    La valeur de la variable nom choisi est utilisée comme nom principal dans le jeton SAML. Le nom figure dans l'assertion en tant que NameIdentifier pour un jeton SAML version 1.1, ou NameId pour un jeton SAML version 2.0. Par exemple, si la valeur de nom choisi est Alice, l'assertion qui suit est générée dans un jeton SAML version 1.1 :
    <saml:NameIdentifier>Alice</saml:NameIdentifier>
    L'assertion qui suit est générée dans un jeton SAML version 2.0 :
    <saml2:NameID>Alice</saml2:NameID> 

    Pour inclure les attributs SAML dans la portion <AttributeStatement> d'une assertion, utilisez le code suivant :

    SAMLAttribute samlAttribute = new SAMLAttribute("email" /* Name*/, new String[] {"joe@websphere"} 
    /*Attribute Values*/, null, "IBM WebSphere namespace" /* namespace*/, "email" /* format*/, "joe" /*friendly name */);
    ArrayList<SAMLAttribute> al = new ArrayList<SAMLAttribute>();
    al.add(samlAttribute)
    sattribute = new SAMLAttribute("Membership", new String[] {"Super users", "Gold membership"}, null, null /* format*/, null, null );
    al.add(samlAttribute );
    cred.setSAMLAttributes(al);
    Cet exemple de code génère les assertions <Attribute> qui suivent :
    <saml:Attribute AttributeName="email" NameFormat="email" AttributeNamespace="IBM WebSphere namespace">
    <saml:AttributeValue>joe@websphere</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute AttributeName="Membership">
    <saml:AttributeValue>Super users</saml:AttributeValue><saml:AttributeValue>Gold membership</saml:AttributeValue>
    </saml:Attribute>
  5. Générez un jeton SAML holder-of-key à l'aide de la ligne de code suivante :
    SAMLToken samlToken = samlFactory.newSAMLToken(cred, reqData, samlIssuerCfg);
    Cette méthode requiert le droit d'accès Java wssapi.SAMLTokenFactory.newSAMLToken. Les exemples de code complets dont sont extraites les lignes des paragraphes ci-dessus figurent à la section Exemple.

Exemple

Utilisez l'exemple de code suivant pour créer un jeton holder-of-key SAML version 1.1 utilisant une clé secrète (clé symétrique) à partir du sujet.
import com.ibm.wsspi.wssecurity.saml.config.RequesterConfig;
import com.ibm.wsspi.wssecurity.saml.config.ProviderConfig;
import com.ibm.wsspi.wssecurity.saml.config.CredentialConfoig ; 
import com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory 

SAMLTokenFactory samlFactory =  SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11);

RequesterConfig reqData  =  samlFactory.newSymmetricHolderOfKeyTokenGenerateConfig();

//Map "AppliesTo" to key alias, so library knows how to encrypt the Symmetric Key
reqData.setKeyAliasForAppliesTo("SOAPRecipient"); 

ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig(IsserUri);

Subject subject =  com.ibm.websphere.security.auth.WSSubject.getRunAsSubject(); 

SAMLToken samlToken = samlFactory.newSAMLToken(subject, reqData, samlIssuerCfg);
Utilisez l'exemple de code suivant pour créer un jeton holder-of-key SAML version 2.0 utilisant une clé publique à partir du sujet :
//User expression on how SAML should be created, default provided
RequesterConfig reqData =  samlFactory.newAsymmetricHolderOfKeyTokenGenerateConfig();

//Choose a public key to be included in SAML
reqData.setKeyAliasForRequester("SOAPInitiator"); 

//Get issuer key store so can sign or encrypt assertion, issuer name
ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig("any_issuer");

//Get JAAS Subject so the factory can populate principal and attributes to SAML
Subject subject =  com.ibm.websphere.security.auth.WSSubject.getRunAsSubject(); 

SAMLToken samlToken = samlFactory.newSAMLToken(subject, reqData, samlIssuerCfg);
Utilisez l'exemple de code suivant pour créer un jeton holder-of-key SAML version 2.0 utilisant une clé secrète (clé symétrique) :
SAMLTokenFactory samlFactory =  SAMLTokenFactory.getInstance (SAMLTokenFactory.WssSamlV20Token11);

RequesterConfig reqData = samlFactory. newSymmetricHolderOfKeyTokenGenerateConfig ();
//Map "AppliesTo" to key alias so library knows how to encrypt the Symmetric Key
reqData.setKeyAliasForAppliesTo("SOAPRecipient"); 

ProviderConfig samlIssuerCfg = samlFactory.newDefaultProviderConfig(null);

CredentialConfig cred = samlFactory.newCredentialConfig ();
cred.setRequesterNameID("any_name"); 

SAMLToken samlToken =  samlFactory.newSAMLToken(subject, reqData, samlIssuerCfg);

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_createholderofkeytoken
Nom du fichier : twbs_createholderofkeytoken.html