WebSphere® Application Server Version
8.0 with SAML provides public application programming interfaces (APIs)
that you can use to build SAML token aware applications.
Use the SAMLTokenFactory API to create, validate, and authenticate
SAML tokens, and to create JAAS subjects that represent SAML tokens.
The SAMLTokenFactory implementation supports both the OASIS SAML v1.1
Token Specification and OASIS SAML v2.0 Token Specification. Use the
WSSTrustClient API to send, issue, and validate WS-Trust request messages
to the specified STS. The WSSTrustClient implementation supports
both WS-Trust v1.3 Specification and the WS-Trust v1.2 Specification,
and supports both the SOAP v1.1 namespace and the SOAP v1.2 namespace.
newfeat New feature: Starting with WebSphere Application Server Release 8,
you can use the
com.ibm.websphere.wssecurity.wssapi.token.SAMLToken class
in Web Services Security (WSS) application programming interface (API).
When there is no concern of confusion we use the term
SAMLToken instead
of using its complete package name. You can use WSS API to request
SAMLToken processing from an external Security Token Service (STS),
to propagate SAMLTokens in SOAP request messages, and to use a symmetric
or asymmetric key identified by SAMLTokens to protect SOAP messages.
The
WSS API SAML support complements the com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory and com.ibm.websphere.wssecurity.wssapi.trust.WSSTrustClient interfaces.
SAMLTokens that are generated using the com.ibm.websphere.wssecurity.wssapi.WSSFactory
newSecurityToken() method can be processed by the SAMLTokenFactory and WSSTrustClient programming
interfaces. Conversely, SAMLTokens that are generated by SAMLTokenFactory or
returned by WSSTrustClient can be used in WSS API.
Deciding which API to use in your application depends on your specific
needs. WSS API SAML support is self contained in the sense that it
provides functionality equivalent to that of the SAMLTokenFactory and WSSTrustClient interfaces
as far as web services client applications are concerned. The SAMLTokenFactory interface
has additional functions to validate SAMLTokens and to create the
JAAS Subject that represents authenticated SAMLTokens. This validation
is useful for the Web services provider side. When you develop applications
to consume SAMLTokens, the SAMLTokenFactory programming
interface is more suitable for you.
newfeat
WebSphere Application Server with SAML
provides the following APIs that implement SAML as a security token.
For information about the methods in these APIs, refer to the SAML
token library API documentation, which describes each of the APIs
and provides sample code.
The SAMLTokenFactory API is the main SAML token programming interface. Using
this API, you can create SAML tokens, insert SAML attributes, parse
and validate SAML assertions as XML representations for the SAML tokens,
and create JAAS subjects that represent user identity and attributes
as defined in SAML tokens.
- com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory
- com.ibm.websphere.wssecurity.wssapi.token.SAMLToken
The SAMLAttribute and SAMLNameID System Programming Interfaces
(SPIs) represent the SAML attributes and SAML user name identifiers.
- com.ibm.wsspi.wssecurity.saml.data.SAMLAttribute
- com.ibm.wsspi.wssecurity.saml.data.SAMLNameID
Using the following SAML SPIs, you can specify how SAML tokens
are created, and SAML assertion XML documents are validated. The ProviderConfig
objects specify configuration information for the SAML assertion issuer,
which includes issuer name, issuer signing key, and signing certificate.
The RequesterConfig objects contain configuration parameters that
define the characteristics of SAML assertions and SAML tokens as they
are created. These configuration parameters include confirmation method,
signing of SAML assertions, embedded encryption key type, and authentication
method. The ConsumerConfig objects contain configuration parameters
that define how SAML assertion XML documents are validated, including
decryption key information, encryption algorithm, timer value for
clock skew, and if digital signing is required for issuers.
- 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
The following SAML Callback and CallbackHandler classes specify
configuration parameters that you can use to define the characteristics
of SAML assertions and control the behavior of the SAML LoginModule
in the runtime environment. These parameters are stored in the Web
Services Security binding documents. The SAML token configuration
is modeled by the CustomToken extension in the Web Services Security
policy configuration.
- com.ibm.websphere.wssecurity.callbackhandler.SAMLConsumeCallback
- com.ibm.websphere.wssecurity.callbackhandler.SAMLConsumerCallbackHandler
- com.ibm.websphere.wssecurity.callbackhandler.SAMLGenerateCallback
- com.ibm.websphere.wssecurity.callbackhandler.SAMLGenerateCallbackHandler
The getXML() method, in the com.ibm.websphere.wssecurity.wssapi.token.SecurityToken
programming interface, returns objects which implement the XMLStructure
interface. An enhancement that is added by
WebSphere Application Server supports a custom
SecurityToken implementation. Using the following two SPIs, you can
deploy an Axis2 Axiom OM implementation or a DOM implementation. The
SAML token extends the GenericSecurityToken interface, which in turn
extends the SecurityToken interface. GenericSecurityToken is a new
interface added by
WebSphere Application Server
with SAML. The SAML token also implements the OMStructure interface.
- com.ibm.wsspi.wssecurity.wssapi.DOMStructure
- com.ibm.wsspi.wssecurity.wssapi.OMStructure
The WS-Trust Client API includes the WSSTrustClient class and other
auxiliary APIs and SPIs. The WSSTrustClient API sends WS-Trust SOAP
requests to a specified external security token service (STS) so that
the STS can issue or validate one or more SAML assertions, or other
type of security tokens. WSSTrustClient supports both WS-Trust Version
1.3 and WS-Trusts Version 1.2 specifications. The WSSTrustClient API
returns a SAML token when API callers request the SAML token type.
The API also uses the GenericSecurityToken interface when the API
caller requests a non-SAML token type. Read about the WS-Trust Client
API for more information and sample code. Refer to the API documentation
for a detailed discussion of the APIs and SPIs.
- com.ibm.websphere.wssecurity.wssapi.trust.WSSTrustClient
- com.ibm.websphere.wssecurity.wssapi.token.GenericSecurityToken
Use the following SPIs specify the characteristics of tokens and
their behavior in the runtime environment. The ProviderConfig objects
contain configuration parameters that specify the STS endpoint, the
Web Services Security policy set, the bindings documents used to access
the STS, and whether general bindings or application-specific bindings
are used. The ProviderConfig objects also specify whether the RequestSecurityTokenResponse
(RSTR) XML document is stored in the GenericSecurityToken objects
or SAMLToken objects. The RequesterConfig objects contain configuration
parameters that are sent in the WS-Trust requests to the specified
STS. The ConsumerConfig interface defines attributes and data for
the WS-Trust response messages, and for the RequestSecurityTokenResponse
element. This data is retrieved using the GenericSecurityToken getProperties()
method. The RequestSecurityTokenResponse XML element is stored as
a property when the ProviderConfig setIncludeRSTRProperties() has
been invoked. If a specific attribute needed by an application is
not defined by the ConsumerConfig interface, you can retrieve and
parse the RSTR element instead.
- 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
For additional information about using the APIs, including practical
scenarios that illustrate how and when to apply the APIs, read about
SAML usage scenarios.