Red Hat Training

A Red Hat training course is available for Red Hat Fuse

8.2. Basic Scenarios

Overview

This section describes the basic scenarios supported by WS-Trust, which are closely related to some of the use cases defined in the SAML standard. It is, therefore, worth taking a moment to look at the relationship between the SAML standard and the WS-Trust standard.

SAML architecture

The SAML standard is specified in four distinct parts, as follows:
  • Assertions—specifies the format of a SAML token, which is a standardized packet of XML containing security data. SAML tokens can contain authentication data (such as username/password, X.509 certificate, and so on), authorization data (such as roles, permissions, privileges), security attributes (such as issuer identity, name and address of subject). A SAML token can also optionally be encrypted and/or signed.
  • Protocol—describes request and response messages for operations such as issuing, validating, and renewing SAML tokens.
  • Bindings—maps the abstract SAML protocol to specific network protocols.
  • Profiles—describes particular use cases for building a security system based on SAML.

WS-Trust and SAML

There are close parallels between the WS-Trust architecture and the SAML architecture. In particular, WS-Trust explicitly relies on and uses SAML assertions (that is, SAML tokens). On the other hand, WS-Trust does not use any of the protocol, bindings, or profiles components of the SAML standard.
The relationship between WS-Trust and SAML can be quite confusing, in fact, because WS-Trust does define an abstract protocol (for communicating with the STS), a binding (to the SOAP protocol), and scenarios that are remarkably similar to some of the SAML scenarios. But these aspects of WS-Trust are defined independently of the SAML standard.

Scenarios

SAML defines the following fundamental types of authentication scenario, which are also supported by WS-Trust:

Bearer scenario

In the bearer scenario, the server automatically trusts the SAML token (after verifying its signature). Thus, in the bearer scenario, any client that presents the token can make use of the claims contained in the token (roles, permissions, and so on). It follows that the client must be very careful not to expose the SAML token or to pass it to any untrusted applications. For example, the client/server connection must use encryption, to protect the SAML token from snooping.
Figure 8.2, “Bearer Scenario” shows a general outline of a typical bearer scenario.

Figure 8.2. Bearer Scenario

Bearer Scenario

Steps in the bearer scenario

The bearer scenario proceeds as follows:
  1. Before invoking an operation on the server, the client sends a RequestSecurityToken (RST) message to the Issue binding of the STS. The RST specifies a KeyType of Bearer.
    The STS generates a SAML token with subject confirmation type bearer, signs the token using its private key, and then returns the token in a RequestSecurityTokenReply (RSTR) message.
  2. The client attempts to invoke an operation on the server, with the SAML token embedded in the SOAP header of the request message, where either the SOAP header or the transport connection must be encrypted, to protect the token.
  3. The server checks the signature of the SAML token (using a local copy of the STS public key), to ensure that it has not been tampered with.

Holder-of-key scenario

The holder-of-key scenario is a refinement of the bearer scenario where, instead of accepting the SAML token when presented by any client, the server attempts to authenticate the client and checks that the client identity matches the holder-of-key identity embedded in the SAML token.
There are two variations on the Holder-of-Key scenario, depending on the value of the KeyType specified in the RST, as follows:
  • PublicKey—the client must prove to the WS server that it possesses a particular private key.
  • SymmetricKey—the client must prove to the WS server that it possesses a particular symmetric session key.
Figure 8.3, “Holder-of-Key Scenario” shows a general outline of a typical holder-of-key scenario.

Figure 8.3. Holder-of-Key Scenario

Holder-of-Key Scenario

Steps in the holder-of-key scenario

The bearer scenario proceeds as follows:
  1. Before invoking an operation on the server, the client sends a RequestSecurityToken (RST) message to the Issue binding of the STS. The STS generates a SAML token with subject confirmation type holder-of-key, embeds the client identity in the token (the holder-of-key identity), signs the token using its private key, and then returns the token in a RequestSecurityTokenReply (RSTR) message.
  2. The client attempts to invoke an operation on the server, with the SAML token embedded in the SOAP header of the request message.
  3. The server checks the signature of the SAML token (using a local copy of the STS public key), to ensure that it has not been tampered with.
  4. The server attempts to authenticate the client (for example, by requiring a client X.509 certificate or by checking WS-Security UsernameToken credentials) and checks that the client's identity matches the holder-of-key identity.