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.
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 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 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 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.// 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);
// 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
// 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.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();
String confirmationMethpo = samlToken.getConfirmationMethod();
String issuerName = samlToken.getSAMLIssuerName();
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]