+

Search Tips   |   Advanced Search

Overview of APIs for SAML

WebSphere Application Server support for SAML provides public APIs that we 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.

Starting with WebSphere Application Server Release 8, we can use the com.ibm.websphere.wssecurity.wssapi.token.SAMLToken class in Web Services Security (WSS) (API). When there is no concern of confusion we use the term SAMLToken instead of using its complete package name. We 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 the application depends on the 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.

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, we 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.

The SAMLAttribute and SAMLNameID System Programming Interfaces (SPIs) represent the SAML attributes and SAML user name identifiers.

Use the following SAML SPIs, we 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.

The following SAML Callback and CallbackHandler classes specify configuration parameters that we 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.

The getXML() method, in the com.ibm.websphere.wssecurity.wssapi.token.SecurityToken programming interface, returns objects which implement the XMLStructure interface. An enhancement added by WebSphere Application Server supports a custom SecurityToken implementation. Using the following two SPIs, we 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.

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.

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 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, we can retrieve and parse the RSTR element instead.

For additional information about using the APIs, including practical scenarios that illustrate how and when to apply the APIs, read about SAML usage scenarios.


Related concepts

  • SAML usage scenarios

  • SAML token library APIs
  • WS-Trust client API
  • API documentation - package: com.ibm.websphere.wssecurity.wssapi