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
Namespaces
A typical IssuedToken policy is defined using elements from the following schema namespaces:
| Prefix | XML 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
IncludeTokenattribute 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:EndpointReferenceTypetype.There is no need to specify the issuer's endpoint reference usingsp:Issuerin 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:RequestSecurityTokenelement, 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:KeyTypeelement. 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.1http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#UsernameTokenhttp://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v1http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509PKIPathv1http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#PKCS7http://docs.oasisopen.org/wss/oasiswss-kerberos-tokenprofile-1.1#Kerberosv5APREQSHA1Consult 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/PublicKeyhttp://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKeyhttp://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:TokenTypeassertion (in the latter case, it takes precedence over thewst:TokenTypeassertion). 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:RequireDerivedKeyspolicy assertion is included, the use of derived keys is enabled in WS-SecureConversation and both implied derived keys and explicit derived keys are allowed.NoteOnly one ofsp:RequireDerivedKeys,sp:RequireImpliedDerivedKeys, orsp:RequireExplicitDerivedKeys, can be included insp:IssuedToken. sp:IssuedToken/sp:Policy/sp:RequireImpliedDerivedKeys- (Optional) When the
sp:RequireImpliedDerivedKeyspolicy 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:RequireExplicitDerivedKeyspolicy 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, orwsse:Embedded.
