Skip to end of metadata
Go to start of metadata

SAML Bearer Assertion Scenario

WS-Trust deals with managing software security tokens.  A SAML assertion is a type of security token.  In the SAML Bearer scenario, the service provider automatically trusts that the incoming SOAP request came from the subject defined in the SAML token after the service verifies the tokens signature.

Implementation of this scenario has the following requirements.

  • SAML tokens with a Bearer subject confirmation method must be protected so the token can not be snooped.  In most cases, a bearer token combined with HTTPS is sufficient to prevent "a man in the middle" getting possession of the token.  This means a security policy that uses a sp:TransportBinding and sp:HttpsToken.
  • A bearer token has no encryption or signing keys associated with it, therefore a sp:IssuedToken of bearer keyType should be used with a sp:SupportingToken or a sp:SignedSupportingTokens.

Web service Provider

This section examines the web service elements for the SAML Bearer scenario.  The components are

  • Bearer web service provider's WSDL
  • SSL configuration
  • Bearer web service provider's Interface and Implementation classes.
  • Crypto properties and keystore files
  • MANIFEST.MF

Web service provider WSDL

The web service provider is a contract-first endpoint.  All the WS-trust and security policies for it are declared in WSDL, BearerService.wsdl.  For this scenario a ws-requester is required to present a SAML 2.0 Bearer token issued from a designed STS. The address of the STS is provided in the WSDL.  HTTPS, a TransportBinding and HttpsToken policy are used to protect the SOAP body of messages that pass back and forth between ws-requester and ws-provider.  A detailed explanation of the security settings are provided in the comments in the listing below.

SSL configuration

This web service is using https, therefore the JBoss server must be configured to provide SSL support in the Web subsystem.  There are 2 components to SSL configuration.

  • create a certificate keystore
  • declare an SSL connector in the Web subsystem of the JBoss server configuration file.

Follow the directions in the, "Using the pure Java implementation supplied by JSSE" section in the SSL Setup Guide.

Here is an example of an SSL connector declaration.

Web service Interface

The web service provider interface class, BearerIface, is a simple straight forward web service definition.

Web service Implementation

The web service provider implementation class, BearerImpl, is a simple POJO.  It uses the standard WebService annotation to define the service endpoint. In addition there are two Apache CXF annotations, EndpointProperties and EndpointProperty used for configuring the endpoint for the CXF runtime. These annotations come from the Apache WSS4J project, which provides a Java implementation of the primary WS-Security standards for Web Services. These annotations are programmatically adding properties to the endpoint. With plain Apache CXF, these properties are often set via the <jaxws:properties> element on the <jaxws:endpoint> element in the Spring config; these annotations allow the properties to be configured in the code.

WSS4J uses the Crypto interface to get keys and certificates for signature creation/verification, as is asserted by the WSDL for this service.  The WSS4J configuration information being provided by BearerImpl is for Crypto's Merlin implementation.  More information will be provided about this in the keystore section.

Because the web service provider automatically trusts that the incoming SOAP request came from the subject defined in the SAML token there is no need for a Crypto callbackHandler class or a signature username, unlike in prior examples, however in order to verify the message signature, the Java properties file that contains the (Merlin) crypto configuration information is still required.

Crypto properties and keystore files

WSS4J's Crypto implementation is loaded and configured via a Java properties file that contains Crypto configuration data.  The file contains implementation-specific properties such as a keystore location, password, default alias and the like.  This application is using the Merlin implementation. File serviceKeystore.properties contains this information.

File servicestore.jks, is a Java KeyStore (JKS) repository.  It contains self signed certificates for myservicekey and mystskey.  Self signed certificates are not appropriate for production use.

MANIFEST.MF

When deployed on WildFly this application requires access to the JBossWs and CXF APIs provided in module org.jboss.ws.cxf.jbossws-cxf-client.  The dependency statement directs the server to provide them at deployment.

Bearer Security Token Service

This section examines the crucial elements in providing the Security Token Service functionality for providing a SAML Bearer token.  The components that will be discussed are.

  • Security Domain
  • STS's WSDL
  • STS's implementation class
  • STSBearerCallbackHandler
  • Crypto properties and keystore files
  • MANIFEST.MF

Security Domain

The STS requires a JBoss security domain be configured.  The jboss-web.xml descriptor declares a named security domain,"JBossWS-trust-sts" to be used by this service for authentication.  This security domain requires two properties files and the addition of a security-domain declaration in the JBoss server configuration file.

For this scenario the domain needs to contain user alice, password clarinet, and role friend. See the listings below for jbossws-users.properties and jbossws-roles.properties.  In addition the following XML must be added to the JBoss security subsystem in the server configuration file.  Replace "SOME_PATH" with appropriate information.

jboss-web.xml

jbossws-users.properties

jbossws-roles.properties

STS's WSDL

STS's implementation class

The Apache CXF's STS, SecurityTokenServiceProvider, is a web service provider that is compliant with the protocols and functionality defined by the WS-Trust specification.  It has a modular architecture. Many of its components are configurable or replaceable and there are many optional features that are enabled by implementing and configuring plug-ins.  Users can customize their own STS by extending from SecurityTokenServiceProvider and overriding the default settings.  Extensive information about the CXF's STS configurable and pluggable components can be found here.

This STS implementation class, SampleSTSBearer, is a POJO that extends from SecurityTokenServiceProvider.  Note that the class is defined with a WebServiceProvider annotation and not a WebService annotation.  This annotation defines the service as a Provider-based endpoint, meaning it supports a more messaging-oriented approach to Web services.  In particular, it signals that the exchanged messages will be XML documents of some type.  SecurityTokenServiceProvider is an implementation of the javax.xml.ws.Provider interface.  In comparison the WebService annotation defines a (service endpoint interface) SEI-based endpoint which supports message exchange via SOAP envelopes.

As was done in the BearerImpl class, the WSS4J annotations EndpointProperties and EndpointProperty are providing endpoint configuration for the CXF runtime.  The first EndpointProperty statement in the listing is declaring the user's name to use for the message signature.  It is used as the alias name in the keystore to get the user's cert and private key for signature.  The next two EndpointProperty statements declares the Java properties file that contains the (Merlin) crypto configuration information.  In this case both for signing and encrypting the messages.  WSS4J reads this file and extra required information for message handling.  The last EndpointProperty statement declares the STSBearerCallbackHandler implementation class.  It is used to obtain the user's password for the certificates in the keystore file.

In this implementation we are customizing the operations of token issuance, token validation and their static properties.

StaticSTSProperties is used to set select properties for configuring resources in the STS.  You may think this is a duplication of the settings made with the WSS4J annotations.  The values are the same but the underlaying structures being set are different, thus this information must be declared in both places.

The setIssuer setting is important because it uniquely identifies the issuing STS.  The issuer string is embedded in issued tokens and, when validating tokens, the STS checks the issuer string value. Consequently, it is important to use the issuer string in a consistent way, so that the STS can recognize the tokens that it has issued.

The setEndpoints call allows the declaration of a set of allowed token recipients by address.  The addresses are specified as reg-ex patterns.

TokenIssueOperation has a modular structure.  This allows custom behaviors to be injected into the processing of messages.  In this case we are overriding the SecurityTokenServiceProvider's default behavior and performing SAML token processing.  CXF provides an implementation of a SAMLTokenProvider which we are using rather than writing our own.

Learn more about the SAMLTokenProvider here.

STSBearerCallbackHandler

STSBearerCallbackHandler is a callback handler for the WSS4J Crypto API.  It is used to obtain the password for the private key in the keystore.  This class enables CXF to retrieve the password of the user name to use for the message signature.

Crypto properties and keystore files

WSS4J's Crypto implementation is loaded and configured via a Java properties file that contains Crypto configuration data.  The file contains implementation-specific properties such as a keystore location, password, default alias and the like.  This application is using the Merlin implementation. File stsKeystore.properties contains this information.

File servicestore.jks, is a Java KeyStore (JKS) repository.  It contains self signed certificates for myservicekey and mystskey.  Self signed certificates are not appropriate for production use.

MANIFEST.MF

When deployed on WildFly, this application requires access to the JBossWS and Apache CXF APIs provided in modules org.jboss.ws.cxf.jbossws-cxf-client.  The org.jboss.ws.cxf.sts module is also needed to build the STS configuration in the SampleSTS constructor.  The dependency statement directs the server to provide them at deployment.

Web service requester

This section examines the crucial elements in calling a web service that implements endpoint security as described in the SAML Bearer scenario.  The components that will be discussed are.

  • Web service requester's implementation
  • ClientCallbackHandler
  • Crypto properties and keystore files

Web service requester Implementation

The ws-requester, the client, uses standard procedures for creating a reference to the web service.  To address the endpoint security requirements, the web service's "Request Context" is configured with the information needed in message generation.  In addition, the STSClient that communicates with the STS is configured with similar values.  Note the key strings ending with a ".it" suffix.  This suffix flags these settings as belonging to the STSClient.  The internal CXF code assigns this information to the STSClient that is auto-generated for this service call.

There is an alternate method of setting up the STSCLient.  The user may provide their own instance of the STSClient.  The CXF code will use this object and not auto-generate one.  When providing the STSClient in this way, the user must provide a org.apache.cxf.Bus for it and the configuration keys must not have the ".it" suffix.  This is used in the ActAs and OnBehalfOf examples.

ClientCallbackHandler

https://docs.jboss.org/author/display/JBWS/WS-Trust+and+STS#WS-TrustandSTS-ClientCallbackHandler

ClientCallbackHandler is a callback handler for the WSS4J Crypto API.  It is used to obtain the password for the private key in the keystore.  This class enables CXF to retrieve the password of the user name to use for the message signature.  Note that "alice" and her password have been provided here.  This information is not in the (JKS)  keystore but provided in the WildFly security domain.  It was declared in file jbossws-users.properties.

Crypto properties and keystore files

https://docs.jboss.org/author/display/JBWS/WS-Trust+and+STS#WS-TrustandSTS-RequesterCryptopropertiesandkeystorefiles

WSS4J's Crypto implementation is loaded and configured via a Java properties file that contains Crypto configuration data.  The file contains implementation-specific properties such as a keystore location, password, default alias and the like.  This application is using the Merlin implementation. File clientKeystore.properties contains this information.

File clientstore.jks, is a Java KeyStore (JKS) repository.  It contains self signed certificates for myservicekey and mystskey.  Self signed certificates are not appropriate for production use.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.