Red Hat DocumentationFuse ESBToggle FramesPrintFeedback

Defining an IssuedToken Policy


In general, an IssuedToken policy can appear in any context where a regular token can appear. When an sp:IssuedToken element appears in a policy, it indicates that the application must call out to the STS to obtain a token (as specified in the sp:IssuedToken element) and then use the token in the current context.

Fundamentally, an IssuedToken policy consists of two parts: one part is aimed at the client, specifying how the client must use the IssuedToken; and another part is aimed at the STS, specifying what type of token to issue and how the token should be constructed. The part that is aimed at the STS is put inside the special element, sp:RequestSecurityTokenTemplate. All of the children of this element will be copied directly into the body of the RequestSecurityToken (RST) message that is sent to the STS when the client asks the STS to issue a token, as shown in Figure 13.

Figure 13. Injecting Parameters into the Outgoing RequestSecurityToken Message

Injecting Parameters into the Outgoing RequestSecurityToken Message


A typical IssuedToken policy is defined using elements from the following schema namespaces:

Table 9. XML Namespaces used with IssuedToken

PrefixXML Namespace

Sample policy

The following example shows a minimal IssuedToken policy, where the client requests the STS to issue a SAML 2.0 token (specified by the value of the trust:TokenType element). The issued token will be included in the client's request header (indicated by setting the sp:IncludeToken attribute to AlwaysToRecipient).

    <!-- No extra policies needed in this demo. -->

In an example such as this, where the IssuedToken policy contains few settings, it is assumed that the STS is already configured with sensible default properties.


The IssuedToken element is defined with the following syntax:

    xmlns:sp="..." ... >
   <sp:Issuer>wsa:EndpointReferenceType</sp:Issuer> |
  ) ?
  <wst:Claims Dialect="..."> ... </wst:Claims> ?
  <sp:RequestSecurityTokenTemplate TrustVersion="xs:anyURI"? >
    <wst:TokenType>...</wst:TokenType> ?
    <wsp:AppliesTo>...</wsp:AppliesTo> ?
    <!-- Many other WS-Trust elements allowed here -->
  <wsp:Policy xmlns:wsp="...">
     <sp:RequireDerivedKeys ... /> |
     <sp:RequireImpliedDerivedKeys ... /> |
     <sp:RequireExplicitDerivedKeys ... />
    ) ?
    <sp:RequireExternalReference ... /> ?
    <sp:RequireInternalReference ... /> ?

XML elements

An IssuedToken policy is specified using the following XML elements:


The element containing the IssuedToken policy assertion. The IncludeToken attribute specifies whether the issued token is meant to be included in the security header of the client's request messages. The allowed values of this attribute are given in sp:IncludeToken attribute.

On the client side, the presence of this assertion signals that the client should attempt to obtain a token by contacting a remote STS.


(Optional) Contains a reference to the issuer of the token, of wsa:EndpointReferenceType type.

There is no need to specify the issuer's endpoint reference using sp:Issuer in Fuse Services Framework, because the issuer endpoint (that is, the STS address) is taken directly from the STS WSDL file instead. See Step 2.


(Optional) The name of the issuing service (that is, the STS), in the format of a URI.


(Optional) Specifies the required claims that the issued token must contain in order to satisfy the IssuedToken policy assertion.


(Required) This element contains a list of WS-Trust policy assertions to be included in the outgoing RequestSecurityToken (RST) message that is sent to the STS. In other words, this element enables you to modify the Issue query that is sent to the STS to obtain the issued token. Thie element can contain any of the WS-Trust assertions that are valid children of the sp:RequestSecurityToken element, as specified by WS-Trust.


(Optional) The type of security token to issue, specified as a URI string. Although theoretically optional, this assertion is almost always specified. Table 10 shows the list of standard token type URIs for the following token types: SAML 1.1, SAML 2.0, UsernameToken, X.509v3 single certificate, X509v1 single certificate, X.509 PKI certificate chain, X.509 PKCS7, and Kerberos.

Table 10. Token Type URIs

Token Type URI

Consult the documentation for your third-party STS to find out what token types it supports. An STS can also support custom token types not listed in the preceding table.


(Optional) This WS-PolicyAttachment assertion can be specified as an alternative to or in addition to the wst:TokenType assertion (in the latter case, it takes precedence over the wst:TokenType assertion). It is used to specify the policy scope for which this token is required. In practice, this enables you to refer to a service or group of services for which this token is issued. The STS can then be configured to specify what kind of token to issue for that service (or services).


(Optional) You can optionally include many other WS-Trust assertions in the RST template. The purpose of these assertions is to specify exactly what the content of the issued token should be and whether it is signed, encrypted, and so on. In practice, however, the details of the issued token are often configured in the STS, which makes it unnecessary to include all of these details in the RST template.

For a full list of of WS-Trust assertions that can be included in the RST template, see the OASIS WS-Trust 1.4 Specification.


(Required) This element must be included in the IssuedToken, even if it is empty.


(Optional) Only applicable when using WS-SecureConversation. The WS-SecureConversation specification enables you to establish a security context (analogous to a session), which is used for sending multiple secured messages to a given service. Normally, if you use the straightforward approach of authenticating every message sent to a particular service, the authentication adds a considerable overhead to secure communications. If you know in advance that a client will be sending multiple messages to a Web service, however, it makes sense to establish a security context between the client and the server, in order to cut the overheads of secure communication. This is the basic idea of WS-SecureConversation.

When a security context is established, the client and the server normally establish a shared secret. In order to prevent the shared secret being discovered, it is better to avoid using the shared secret directly and use it instead to generate the keys needed for encryption, signing, and so on—that is, to generate derived keys.

When the sp:RequireDerivedKeys policy assertion is included, the use of derived keys is enabled in WS-SecureConversation and both implied derived keys and explicit derived keys are allowed.


Only one of sp:RequireDerivedKeys, sp:RequireImpliedDerivedKeys, or sp:RequireExplicitDerivedKeys, can be included in sp:IssuedToken.


(Optional) When the sp:RequireImpliedDerivedKeys policy assertion is included, the use of derived keys is enabled in WS-SecureConversation, but only implied derived keys are allowed.


(Optional) When the sp:RequireExplicitDerivedKeys policy assertion is included, the use of derived keys is enabled in WS-SecureConversation, but only explicit derived keys are allowed.


(Optional) When included, requires that external references to the issued token must be enabled.


(Optional) When included, requires that internal references to the issued token must be enabled, where an internal reference uses one of the elements, wsse:Reference, wsse:KeyIdentifier, or wsse:Embedded.

Comments powered by Disqus