APIs der SAML-Tokenbibliothek

Die Anwendungsprogrammierschnittstellen (APIs) der SAML-Tokenbibliothek stellen Methoden bereit, mit denen SAML-Token erstellt, ausgewertet, analysiert und extrahiert werden können.

Übersicht

Die Bibliotheksimplementierung für SAML Version 1.1 und SAML Version 2.0 stellt drei Typen von Subjektbestätigungen bereit: "holder-of-key (HoK)", "bearer" und "sender-vouches". Mit den APIs der SAML-Tokenbibliothek können Sie die Attribute eines SAML-HoK- oder -Bearer-Tokens erstellen, auswerten und extrahieren. Die SAML-Tokenweitergabe aus den SOAP-Nachricht der Web-Services wird ebenfalls erläutert. Mit Hilfe von Beispielcode wird die Verwendung der APIs veranschaulicht.

WebSphere Application Server mit SAML stellt Standardrichtliniensätze zur Unterstützung der Bearer- und HoK-Subjektbestätigung.

In den folgenden Abschnitt wird die Erstellung eines SAML-Tokens mit den APIs der SAML-Tokenbibliothek beschrieben:
  1. Konfiguration der Parameter für die Tokenerstellung
  2. Instanz der SAML-Token-Factory erstellen
  3. SAML-Tokenerstellung
  4. Beispielcode
Die API SAMLTokenFactory ist die primäre Programmierschnittstelle der SAML-Tokenbibliothek. SAMLTokenFactory unterstützt Erstellung, Parsing und Auswertung der SAML-1.1- und SAML-2.0-Token. Mit der API SAMLTokenFactory API können Sie die Konfigurationsobjekte ProviderConfid, RequesterConfig und ConsumerConfig erstellen und die erforderlichen SAML-Tokenmerkmale definieren. Nähere Einzelheiten finden Sie in der API-Dokumentation.
Nachdem ein SAML-Token erstellt wurde, können Sie weitere Operationen dafür ausführen, beispielsweise die folgenden:
Anmerkung: Ab WebSphere Application Server Release 8 können Sie die Klasse com.ibm.websphere.wssecurity.wssapi.token.SAMLToken in Web Services Security (WSS) Application Programming Interface (API) verwenden. Anstelle des vollständigen Paketnamens wird im Text häufig auch SAMLToken verwendet. Mithilfe von WSS API können Sie eine SAMLToken-Verarbeitung bei einem externen Sicherheitstokenservice (STS, Security Token Service) anfordern, um SAMLToken in SOAP-Anforderungsnachrichten weiterzugeben und zum Schutz von SOAP-Nachrichten einen symmetrischen oder asymmetrischen Schlüssel zu verwenden, der in SAMLToken angegeben wird.

Die SAML-Unterstützung der WSS-API ergänzt die Schnittstellen com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory und com.ibm.websphere.wssecurity.wssapi.trust.WSSTrustClient. SAMLToken, die mit der Methode com.ibm.websphere.wssecurity.wssapi.WSSFactory newSecurityToken() generiert werden, können von den Programmierschnittstellen SAMLTokenFactory und WSSTrustClient verarbeitet werden. SAMLToken, die von SAMLTokenFactory generiert oder von WSSTrustClient zurückgegeben werden, können in WSS API verwendet werden. Die Entscheidung, welche API Sie in Ihrer Anwendung verwenden, richtet sich nach den jeweiligen Anforderungen. Die SAML-Unterstützung von WSS API ist insofern eigenständig, dass sie in Bezug auf Web-Service-Clientanwendungen Funktionen bereitstellt, die denen der Schnittstellen SAMLTokenFactory und WSSTrustClient entsprechen. Die Schnittstelle SAMLTokenFactory enthält weitere Funktionen für die Validierung von SAMLToken und für die Erstellung des JAAS-Subject-Objekts, das authentifizierte SAMLToken darstellt. Diese Validierung ist hilfreich für die Web-Service-Providerseite. Wenn Sie Anwendungen entwickeln, die SAMLToken konsumieren, ist die Programmierschnittstelle SAMLTokenFactory besser für Sie geeignet.

Konfiguration der Parameter für die Tokenerstellung

Wenn Sie die Parameter für die Tokenerstellung konfigurieren, beziehen sich die Konfigurationsdaten entweder auf die Anforderungsentität, die Ausstellerentität oder die Empfangsentität. In diesem Beispiel werden die Konfigurationsdaten für die Anforderungs- und die Ausstellerentität definiert. Für jeden Typ der Subjektbestätigung, der unterstützt wird, stellt die SAML-Tokenbibliothek vorkonfigurierte Attribute für die Anforderungsentät bereit. Diese Attribute werden während der Erstellung des selbstausgestellten SAML-Tokens von der WebSphere-Laufzeitumgebung verwendet. Ein selbstausgestelltes SAML-Token ist ein Token, das lokal generiert und nicht vom Security Token Service (STS) angefordert wird. Wenn die Attribute für einen Standardparameter angepasst werden sollen, verwenden Sie den Parameter "RequesterConfig". Weitere Informationen finden Sie in der Beschreibung des Parameters "RequesterConfig" im Artikel über die API für die SAMLTokenFactory.

Definieren Sie als erstes die konfigurieren für den Requester:
// Definieren Sie die Konfigurationsdaten des Requesters (die erforderlichen
// Parameter zum Erstellen des in den Konfigurationseigenschaften angegebenen Tokens).
// In diesem Fall werden die Konfigurationsdaten verwendet, um ein
// SAML-Token zu erstellen, dass eine symmetrische "holder-of-key"-Subjektbestätigung enthält.
RequesterConfig requesterData = 
     samlFactory.newSymmetricHolderOfKeyTokenGenerateConfig();
Legen Sie als nächstes den Alias des öffentlichen Schlüssels für den Empfänger fest sowie, wahlweise, die Authentifizierungsmethode:
// Legen Sie den Alias des öffentlichen Schlüssels für den Empfänger fest
// (in diesem Beispiel wird SOAPRecipient verwendet), damit der Provider den geheimen
// Schlüssel für die Empfangsseite verschlüsseln kann.
requesterData.setKeyAliasForAppliesTo("SOAPRecipient");

// Legen Sie die verwendete Authentifizierungsmethode fest. Dieser Parameter ist
// optional. reqData.setAuthenticationMethod("Password"); 
Legen Sie anschließend die Konfigurationsattribute für den Aussteller fest:
// Legen Sie die Informationen zum Aussteller fest, indem Sie eine Standardproviderkonfiguration (ProviderConfig) instanziieren.
// Einzelheiten zu den Standardwerten und dazu, wie diese geändert werden können,
// finden Sie in den Informationen zur Klasse SAMLTokenFactory in der Java-Dokumentation.
ProviderConfig samlIssuerCfg =   
  samlFactory.newDefaultProviderConfig("WebSphereSelfIssuer");

Instanz der SAML-Token-Factory erstellen

Verwenden Sie die Klasse SAMLTokenFactory und geben Sie dabei den SAML-Tokentyp an, d. h. Version 1.1 oder Version 2.0. Legen Sie weitere Parameter für die Erstellung des SAML-Tokens fest.
Verwenden Sie die Klasse "SAMLTokenFactory" mit dem SAML-Tokentyp:
// Erstellen Sie eine Instanz einer Token-Factory basierend auf der Tokenversion,
// die verwendet werden soll. In diesem Beispiel wird die Token-Factory SAML v1.1 verwendet.
SAMLTokenFactory samlFactory = 
SAMLTokenFactory.getInstance(SAMLTokenFactory.WssSamlV11Token11);
Geben sie im Objekt "CredentialConfig" zusätzliche Parameter an, indem Sie das Subjekt des Callers (Aufrufenden) oder das "runAsSubject" verwenden:
// Rufen Sie das Caller-Subjekt oder
das "runAsSubject" ab (je nachdem, welches
// Szenario sie verwenden), und verwenden Sie das Subjekt anschließend, um ein "CredentialConfig"-Objekt
// mithilfe der SAML-Tokenbibliothek abzurufen.
// Dieser Aufruf erfordert die Java-Sicherheitsberechtigung
// "wssapi.SAMLTokenFactory.newCredentialConfig".
CredentialConfig cred = samlFactory.newCredentialConfig(runAsSubject);

SAML-Tokenerstellung

Erstellen Sie das SAML-Token mit der Token-Factory:
// SAML-Token jetzt erstellen. Für diesen Aufruf ist die
// Java-Sicherheitsbereichtigung "wssapi.SAMLTokenFactory.newSAMLToken" erforderlich.
SecurityToken samlToken = 
                samlFactory.newSAMLToken(cred, reqData, samlIssuerCfg);

SAML-Tokenauswertung

Eine Entität, die ein SAML-Token empfängt, z. B. ein Geschäftsservice, kann die API der SAML-Tokenbibliothek verwenden, um das Token vor seiner Verwendung auszuwerten. Beispielsweise muss der Service das Token auswerten, bevor er die SAML-Attribute vom Requester extrahiert. Ein vorhandenes SAML-Zusicherungsdokument kann anhand der Konfigurationsdaten vom Konsumenten ausgewertet werden.
Mit dem folgenden API-Code wird das Token ausgewertet:
ConsumerConfig consumerConfig = samlFactory.newConsumerConfig();
		XMLStructure xml =
	try  {    
	   	   SAMLToken token = samlFactory.newSAMLToken( consumerConfig, XMLStructure xml );
	   	   // Token erfolgreich ausgewertet
	} catch(WSSException e) {
	 	 // Tokenauswertung fehlgeschlagen
	}

Zuordnung der Tokenidentität zu einem Subjekt

Ein SAML-Token kann zum Erstellen eines Subjekts verwendet werden. Die Namens-ID im SAML-Token wird einem Benutzer in der Benutzerregistry zugeordnet, um den Namen des Principals für das Subjekt abzurufen.
Subject subject;
SAMLToken aSAMLToken = …;
  try  {    
        subject = samlFactory.newSubject(aSAMLToken);
  } catch(WSSException e) {
  }

Parsing der Zusicherungselemente

Die Empfänger eines SAML-Tokens können mit den SAMLToken-APIs, die in der API der SAML-Tokenbibliothek enthalten sind, Zusicherungselemente aus dem SAML-Token analysieren und extrahieren. Beispielsweise kann die Tokenerstellungszeit mit diesem Code extrahiert werden:
Date dateCreated = samlToken.getSamlCreated();
Extrahieren Sie wie folgt den Namen des Tokenausstellers und die Bestätigungsmethode:
String confirmationMethpo = samlToken.getConfirmationMethod();
String issuerName = samlToken.getSAMLIssuerName();
Wenn die extrahierte Subjektbestätigungsmethode als "holder-of-key"-Bestätigung zurückgegeben wird, können Sie die Bytes für das Schlüsselmaterial mit der folgenden API abrufen:
byte[] hokBytes = samlToken.getHolderOfKeyBytes();

Weitere Informationen zu allen SAML-APIs finden Sie in der API-Dokumentation zur "SAMLToken"-Schnittstelle.

SAML-Tokenattribute extrahieren

Extrahieren Sie mit der SAMLToken-API wie in den folgenden Codeausschnitten SAML-Attribute aus der Initialisierungsentität (Service-Requester):
// Alle Attribute abrufen
List<SAMLAttribute> allAttributes =         
             ((SAMLToken) samlToken).getSAMLAttributes();

// Über Attribute iterieren und entsprechend verarbeiten
Iterator<SAMLAttribute> iter = allAttributes.iterator();
		while (iter.hasNext()) {
    SAMLAttribute anAttribute = iter.next();

    // Attribute verarbeiten
    String attributeName = anAttribute.getName();
    String[] attributeValues = anAttribute.getStringAttributeValue();
 
}

Beispielcode

Der Beispielcode veranschaulicht die Verwendung der APIs der SAML-Tokenbibliothek für die Ausführung der zuvor beschriebenen Operationen. Eine JVM-Eigenschaft, die auf die Position der SAML-Eigenschaftendatei zeigt, wird für die Ausführung dieses Codes vorausgesetzt. Die SAML-Eigenschaftendatei, SAMLIssuerConfig.properties, muss Konfigurationsattribute zum Aussteller (Provider) des SAML-Tokens enthalten.

Die Datei "SAMLIssuerConfig.properties" befindet sich auf Zellenebene standardmäßig im folgenden Verzeichnis: Stammverzeichnis_des_Anwendungsservers/profiles/$PROFILE/config/cells/$CELLNAME/sts.

Auf Serverebene wird folgendes Standardverzeichnis verwendet: Stammverzeichnis_des_Anwendungsservers/profiles/$PROFILE/config/cells/$CELLNAME/nodes/$NODENAME/servers/$SERVERNAME.

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;

// Methoden aus der SAML-Tokenbibliothek importieren
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  {    
  // Eine Instanz der SAML-v1.1-Token-Factory abrufen
  SAMLTokenFactory samlFactory = SAMLTokenFac  
  tory.getInstance(SAMLTokenFactory.WssSamlV11Token11);

  // Standard-Requester-Daten für eine Subjektbestätigung des Typs
  // holder-of-key (geheimer Schlüssel) generieren.
  RequesterConfig requesterData =
       samlFactory.newSymmetricHolderOfKeyTokenGenerateConfig();
        
  // Legen Sie den Schlüsselalias des Empfängers so fest, dass der Aussteller den geheimen
  // Schlüssel für den Empfänger als Teil der Subjektbestätigung verschlüsseln kann.
  requesterData.setKeyAliasForAppliesTo("SOAPRecipient");
        
  // Legen Sie die verwendete Authentifizierungsmethode fest.
  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");

  // Legen Sie den Schlüsselalias des Empfängers fest, so dass die Tokeninformationen, z. B. der
  // geheime HoK, vom Aussteller verschlüsselt und vom Empfänger entschlüsselt werden können.
  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");

  // Requester-Konfigurationselemente ausgeben
  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));

  // Eine Instanz des CredentialConfig-Objekts abrufen
  CredentialConfig cred = samlFactory.newCredentialConfig();
  cred.setRequesterNameID("Alice");

  // Einige Benutzerattribute festlegen
  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);
		
  // Standardproviderkonfiguration abrufen
  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());
        
  // SAML-Token generieren
  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());

       
  // Ein Subjekt erstellen und die Namens-ID im Token einem Benutzer in der
  // Benutzerregistry zuordnen, um den Namen des Principals zu erhalten
  Subject subject = samlFactory.newSubject((SAMLToken)samlToken);

  // Attribute aus dem Token abrufen
  List<SAMLAttribute> allAttributes =         
                        ((SAMLToken)samlToken).getSAMLAttributes();

  // Durch die Attribute iterieren und entsprechend verarbeiten
  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();
  } 
 }
}

Beispielcodeausgabe

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]

Symbol, das den Typ des Artikels anzeigt. Referenzartikel



Symbol für Zeitmarke Letzte Aktualisierung: 25.05.2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=rwbs_libraryapisaml
Dateiname:rwbs_libraryapisaml.html