WAS v8.5 > Secure applications > Secure web services > Secure web services > Web Services Security concepts > SAML concepts

Overview of APIs for SAML

Use the SAMLTokenFactory API to create, validate, and authenticate SAML tokens, and to create JAAS subjects that represent SAML tokens.

SAMLTokenFactory supports...

Use the WSSTrustClient API to send, issue, and validate WS-Trust request messages to the specified Security Token Service (STS).

WSSTrustClient supports...

To...

...in the Web Services Security (WSS) API we can use the class:

WSS API SAML support complements the interfaces...

SAMLTokens are generated using the method...

...can be processed by the SAMLTokenFactory and WSSTrustClient programming interfaces.

Conversely, SAMLTokens are generated by SAMLTokenFactory or returned by WSSTrustClient can be used in WSS API. WSS API SAML support 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. For developing applications, consuming SAMLTokens, the SAMLTokenFactory programming interface, is more suitable.

WAS 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.

Using 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 used 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 that is added by WAS 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 WAS 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 the STS can issue or validate one or more SAML assertions, or other type of security tokens. WSSTrustClient supports both WS-Trust v1.3 and WS-Trusts v1.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


Reference:

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


+

Search Tips   |   Advanced Search