Red Hat Training

A Red Hat training course is available for Red Hat Fuse

8.3. Defining an IssuedToken Policy

Overview

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 8.4, “Injecting Parameters into the Outgoing RequestSecurityToken Message”.

Figure 8.4. Injecting Parameters into the Outgoing RequestSecurityToken Message

Injecting Parameters into the Outgoing RequestSecurityToken Message

Namespaces

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

Table 8.1. XML Namespaces used with IssuedToken

PrefixXML Namespace
wsp:http://schemas.xmlsoap.org/ws/2004/09/policy
sp:http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702
wst:http://docs.oasis-open.org/ws-sx/ws-trust/200512

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).
<sp:IssuedToken
    sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
  <sp:RequestSecurityTokenTemplate>
    <trust:TokenType
        xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/200512"
      >urn:oasis:names:tc:SAML:2.0:assertion</trust:TokenType>
  </sp:RequestSecurityTokenTemplate>
  <wsp:Policy>
    <!-- No extra policies needed in this demo. -->
  </wsp:Policy>
</sp:IssuedToken>
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.

Syntax

The IssuedToken element is defined with the following syntax:
<sp:IssuedToken
    sp:IncludeToken="xs:anyURI"?
    xmlns:sp="..." ... >
  (
   <sp:Issuer>wsa:EndpointReferenceType</sp:Issuer> |
   <sp:IssuerName>xs:anyURI</sp:IssuerName>
  ) ?
  <sp:RequestSecurityTokenTemplate TrustVersion="xs:anyURI"? >
    <wst:TokenType>...</wst:TokenType> ?
    <wst:KeyType>...</wst:KeyType> ?
    <wsp:AppliesTo>...</wsp:AppliesTo> ?
    <wst:Claims Dialect="..."> ... </wst:Claims> ?
    <!-- Many other WS-Trust elements allowed here -->
    ...
  </sp:RequestSecurityTokenTemplate>
  <wsp:Policy xmlns:wsp="...">
    (
     <sp:RequireDerivedKeys ... /> |
     <sp:RequireImpliedDerivedKeys ... /> |
     <sp:RequireExplicitDerivedKeys ... />
    ) ?
    <sp:RequireExternalReference ... /> ?
    <sp:RequireInternalReference ... /> ?
    ...
  </wsp:Policy>
  ...
</sp:IssuedToken>

XML elements

An IssuedToken policy is specified using the following XML elements:
sp:IssuedToken
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 the section called “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.
sp:IssuedToken/sp:Issuer
(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 Apache CXF, because the issuer endpoint (that is, the STS address) is taken directly from the STS WSDL file instead.
sp:IssuedToken/sp:IssuerName
(Optional) The name of the issuing service (that is, the STS), in the format of a URI.
sp:IssuedToken/sp:RequestSecurityTokenTemplate
(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.
sp:IssuedToken/sp:RequestSecurityTokenTemplate/wst:TokenType
(Optional) The type of security token to issue, specified as a URI string. This element is usually specified together with a wst:KeyType element. Table 8.2, “Token Type URIs” 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 8.2. Token Type URIs

Token Type URI
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#UsernameToken
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v1
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509PKIPathv1
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#PKCS7
http://docs.oasisopen.org/wss/oasiswss-kerberos-tokenprofile-1.1#Kerberosv5APREQSHA1
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.
sp:IssuedToken/sp:RequestSecurityTokenTemplate/wst:KeyType
(Optional) The type of key that the client will use to establish its identity to the WS server. The key type indirectly determines the subject confirmation type as either Holder-of-Key or bearer (see Section 8.2, “Basic Scenarios”). Table 8.3, “Key Type URIs” shows the list of standard key type URIs.

Table 8.3. Key Type URIs

Key Type URI
http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey
http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey
http://docs.oasis-open.org/ws-sx/ws-trust/200512/Bearer
sp:IssuedToken/sp:RequestSecurityTokenTemplate/wsp:AppliesTo
(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).
For more details, see Enabling AppliesTo in the STS.
sp:IssuedToken/sp:RequestSecurityTokenTemplate/wst:Claims
(Optional) Specifies the required claims that the issued token must contain in order to satisfy the IssuedToken policy assertion. Claims are used to provide additional data about the token subject—for example, e-mail address, first name, surname, and so on.
For more details, see Enabling Claims in the STS.
sp:IssuedToken/sp:RequestSecurityTokenTemplate/wst:OtherElements
(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.
sp:IssuedToken/sp:Policy
(Required) This element must be included in the IssuedToken, even if it is empty.
sp:IssuedToken/sp:Policy/sp:RequireDerivedKeys
(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.
Note
Only one of sp:RequireDerivedKeys, sp:RequireImpliedDerivedKeys, or sp:RequireExplicitDerivedKeys, can be included in sp:IssuedToken.
sp:IssuedToken/sp:Policy/sp:RequireImpliedDerivedKeys
(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.
sp:IssuedToken/sp:Policy/sp:RequireExplicitDerivedKeys
(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.
sp:IssuedToken/sp:Policy/sp:RequireExternalReference
(Optional) When included, requires that external references to the issued token must be enabled.
sp:IssuedToken/sp:Policy/sp:RequireInternalReference
(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.