Übersicht über die APIs für SAML

Die Unterstützung von SAML durch WebSphere Application Server stellt öffentliche Anwendungsprogrammierschnittstellen (APIs) bereit, mit denen Sie Anwendungen für SAML-Token erstellen können.

Verwenden Sie die API SAMLTokenFactory, um SAML-Token zu erstellen, zu validieren und zu authentifizieren und um JAAS-Subjekte, die SAML-Token darstellen, zu erstellen. Die SAMLTokenFactory-Implementierung unterstützt die OASIS-Spezifikationen SAML v1.1 Token und SAML v2.0 Token. Verwenden Sie die WSSTrustClient-API, um WS-Trust-Anforderungsnachrichten zu senden, auszgeben und für das angegebene STS zu validieren. Die Implementierung von WSSTrustClient unterstützt die Spezifikationen WS-Trust v1.3 und WS-Trust v1.2 und außerdem die Namespaces von SOAP v1.1 und SOAP v1.2.

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.

WebSphere Application Server mit SAML stellt die folgenden APIs bereit, die SAML als Sicherheitstoken implementieren. Informationen zu den Methoden, die in diesen APIs verwendet werden, enthält die API-Dokumentation zur SAML-Tokenbibliothek. Dort finden Sie Beschreibungen der verschiedenen APIs mit entsprechendem Beispielcode.

Die API SAMLTokenFactory ist die wichtigste Programmierschnittstelle für SAML-Token. Mit dieser API können Sie SAML-Tokens erstellen, SAML-Attribute einfügen, SAML-Zusicherungen parsen und als XML-Darstellungen für die SAML-Token validieren. Außerdem können Sie JAAS-Subjekte erstellen, die Benutzeridentitäten und -attribute gemäß Definition in SAML-Tokens repräsentieren.
  • com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory
  • com.ibm.websphere.wssecurity.wssapi.token.SAMLToken
Die Systemprogrammierschnittstellen (System Programming Interfaces, SPIs) SAMLAttribute und SAMLNameID stellen die SAML-Attribute und die SAML-Benutzernamenskennungen dar.
  • com.ibm.wsspi.wssecurity.saml.data.SAMLAttribute
  • com.ibm.wsspi.wssecurity.saml.data.SAMLNameID
Mit den folgenden SAML-SPIs können Sie angeben, wie SAML-Token erstellt und XML-Dokumente für SAML-Zusicherungen validiert werden. Die ProviderConfig-Objekte geben Konfigurationsdaten für den Aussteller der SAML-Zusicherung an, die den Namen und den Signierschlüssel des Ausstellers sowie das Signaturzertifikat umfassen. Die RequesterConfig-Objekte enthalten Konfigurationsparameter, die die Kenndaten von SAML-Zusicherungen und SAML-Token bei der Erstellung definieren. Diese Konfigurationsparameter umfassen die Bestätigungsmethode, das Signieren von SAML-Zusicherungen, den Typ des integrierten Chiffrierschlüssels und die Authentifizierungsmethode. Die ConsumerConfig-Objekte enthalten Konfigurationsparameter, die definieren, wie XML-Dokumente für SAML-Zusicherung validiert werden, einschließlich Informationen zum Entschlüsselungsschlüssel, des Verschlüsselungsalgorithmus, des Zeitgeberwerts für Zeitabweichung und der Einstellung, ob eine digitale Signatur für Aussteller erforderlich ist.
  • com.ibm.wsspi.wssecurity.saml.config.ConsumerConfig
  • com.ibm.wsspi.wssecurity.saml.config.CredentialConfig
  • com.ibm.wsspi.wssecurity.saml.config.ProviderConfig
  • com.ibm.wsspi.wssecurity.saml.config.RequesterConfig
  • com.ibm.wsspi.wssecurity.saml.config.SamlConstants
  • com.ibm.wsspi.wssecurity.core.token.config.ConsumerConfiguration
  • com.ibm.wsspi.wssecurity.core.token.config.CredentialConfiguration
  • com.ibm.wsspi.wssecurity.core.token.config.ProviderConfiguration
  • com.ibm.wsspi.wssecurity.core.token.config.RequesterConfiguration
Die folgenden Callback- und CallbackHandler-Klassen für SAML geben Konfigurationsparameter an, die Sie verwenden können, um die Kenndaten von SAML-Zusicherungen zu definieren und das Verhalten des SAML-Anmeldemoduls in der Laufzeitumgebung zu steuern. Diese Parameter werden in den Bindungsdokumenten von Web Services Security gespeichert. Die Konfiguration des SAML-Tokens wird von der Erweiterung CustomToken in der Richtlinienkonfiguration von Web Services Security modelliert.
  • com.ibm.websphere.wssecurity.callbackhandler.SAMLConsumeCallback
  • com.ibm.websphere.wssecurity.callbackhandler.SAMLConsumerCallbackHandler
  • com.ibm.websphere.wssecurity.callbackhandler.SAMLGenerateCallback
  • com.ibm.websphere.wssecurity.callbackhandler.SAMLGenerateCallbackHandler
Die Methode getXML() in der Programmierschnittstelle com.ibm.websphere.wssecurity.wssapi.token.SecurityToken gibt Objekte zurück, die die Schnittstelle XMLStructure implementieren. Eine Erweiterung, die von WebSphere Application Server hinzugefügt wird, unterstützt angepasste SecurityToken-Implementierungen. Mit den folgenden zwei SPIs können Sie eine Implementierung von Axis2 Axiom OM oder eine DOM-Implementierung implementieren. Das SAML-Token erweitert die Schnittstelle GenericSecurityToken, die wiederum die Schnittstelle SecurityToken erweitert. GenericSecurityToken ist eine neue Schnittstelle, die von WebSphere Application Server bereitgestellt wird. Das SAML-Token implementiert auch die Schnittstelle ONStructure.
  • com.ibm.wsspi.wssecurity.wssapi.DOMStructure
  • com.ibm.wsspi.wssecurity.wssapi.OMStructure
Die WS-Trust-Client-API umfasst die Klasse WSSTrustClient und andere Hilfs-APIs und -SPIs. Die WSSTrustClient-API sendet WS-Trust-SOAP-Anforderungen an einen angegebenen externen Sicherheitstokenservice (STS), damit der STS eine oder mehrere SAML-Zusicherungen oder Sicherheitstoken ausgeben oder validieren kann. WSSTrustClient unterstützt die Spezifikationen WS-Trust Version 1.3 und WS-Trusts Version 1.2. Die WSSTrustClient-API gibt ein SAML-Token zurück, wenn API-Caller den SAML-Tokentyp anfordern. Die API verwendet die Schnittstelle GenericSecurityToken auch, wenn der API-Caller einen Tokentyp anfordert, der kein SAML-Tokentyp ist. Weitere diesbezügliche Informationen sowie Beispielcode finden Sie in den Abschnitten, die sich mit der WS-Trust-Client-API befassen. Die API-Dokumentation enthält eine detaillierte Beschreibung der APIs und SPIs.
  • com.ibm.websphere.wssecurity.wssapi.trust.WSSTrustClient
  • com.ibm.websphere.wssecurity.wssapi.token.GenericSecurityToken
Verwenden Sie die folgenden SPIs, um die Kenndaten von Token und ihr Verhalten in der Laufzeitumgebung anzugeben. Die ProviderConfig-Objekte enthalten Konfigurationsparameter, die verschiedene Informationen angeben: den STS-Endpunkt, den Richtliniensatz von Web Services Security, die für den Zugriff auf den STS verwendeten Bindungsdokumente. Außerdem wird angegeben, ob allgemeine Bindungen oder anwendungsspezifische Bindungen verwendet werden. Die ProviderConfig-Objekte geben auch an, ob das XML-Dokument für RequestSecurityTokenResponse in den GenericSecurityToken-Objekten oder den SAMLToken-Objekten gespeichert werden. Die RequesterConfig-Objekte enthalten Konfigurationsparameter, die in den WS-Trust-Anforderungen an den angegebenen STS gesendet werden. Die Schnittstelle ConsumerConfig definiert Attribute und Daten für die WS-Trust-Antwortnachrichten und für das Element RequestSecurityTokenResponse. Diese Daten werden mit der Methode GenericSecurityToken getProperties() abgerufen. Das XML-Element RequestSecurityTokenResponse wird als Eigenschaft gespeichert, wenn die Methode ProviderConfig setIncludeRSTRProperties() aufgerufen wird. Wenn ein bestimmtes, von einer Anwendung benötigtes Attribut nicht von der Schnittstelle ConsumerConfig definiert wird, können Sie stattdessen das RSTR-Element abrufen und parsen.
  • com.ibm.wsspi.wssecurity.trust.config.ConsumerConfig
    • com.ibm.wsspi.wssecurity.trust.config.ConsumerConfig.RSTR
  • com.ibm.wsspi.wssecurity.trust.config.ProviderConfig
  • com.ibm.wsspi.wssecurity.trust.config.RequesterConfig
  • com.ibm.wsspi.wssecurity.core.token.config.WSSConstants
    • com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.Namespace
    • com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.TokenType
    • com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.WST12
    • com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.WST13
    • com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.Algorithm
    • com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.SAML

Weitere Informationen zur Verwendung der APIs einschließlich praktischer Szenarien, die veranschaulichen, wie und wann die APIs angewendet werden sollen, finden Sie bei den SAML-Einsatzszenarien.


Symbol, das den Typ des Artikels anzeigt. Konzeptartikel



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