Red Hat Training

A Red Hat training course is available for Red Hat Fuse

7.2. Specifying an Authentication Policy

Overview

If you want an endpoint to support authentication, associate a supporting tokens policy assertion with the relevant endpoint binding. There are several different kinds of supporting tokens policy assertions, whose elements all have names of the form *SupportingTokens (for example, SupportingTokens, SignedSupportingTokens, and so on). For a complete list, see the section called “SupportingTokens assertions”.
Associating a supporting tokens assertion with an endpoint has the following effects:
  • Messages to or from the endpoint are required to include the specified token type (where the token's direction is specified by the sp:IncludeToken attribute).
  • Depending on the particular type of supporting tokens element you use, the endpoint might be required to sign and/or encrypt the token.
The supporting tokens assertion implies that the runtime will check that these requirements are satisified. But the WS-SecurityPolicy policies do not define the mechanism for providing credentials to the runtime. You must use Spring XML configuration to specify the credentials (see Section 7.3, “Providing Client Credentials”).

Syntax

The *SupportingTokens elements (that is, all elements with the SupportingTokens suffix—see the section called “SupportingTokens assertions”) have the following syntax: 
<sp:SupportingTokensElement xmlns:sp="..." ... >
  <wsp:Policy xmlns:wsp="...">
    [Token Assertion]+
    <sp:AlgorithmSuite ... > ... </sp:AlgorithmSuite> ?
    (
      <sp:SignedParts ... > ... </sp:SignedParts> |
      <sp:SignedElements ... > ... </sp:SignedElements> |
      <sp:EncryptedParts ... > ... </sp:EncryptedParts> |
      <sp:EncryptedElements ... > ... </sp:EncryptedElements> |
    ) *
    ...
  </wsp:Policy>
  ...
</sp:SupportingTokensElement>
Where SupportingTokensElement stands for one of the supporting token elements, *SupportingTokens.Typically, if you simply want to include a token (or tokens) in the security header, you would include one or more token assertions, [Token Assertion], in the policy. In particular, this is all that is required for authentication.
If the token is of an appropriate type (for example, an X.509 certificate or a symmetric key), you could theoretically also use it to sign or encrypt specific parts of the current message using the sp:AlgorithmSuite, sp:SignedParts, sp:SignedElements, sp:EncryptedParts, and sp:EncryptedElements elements. This functionality is currently not supported by Apache CXF, however.

Sample policy

Example 7.1, “Example of a Supporting Tokens Policy” shows an example of a policy that requires a WS-Security UsernameToken token (which contains username/password credentials) to be included in the security header. In addition, because the token is specified inside an sp:SignedSupportingTokens element, the policy requires that the token is signed. This example uses a transport binding, so it is the underlying transport that is responsible for signing the message.
For example, if the underlying transport is HTTPS, the SSL/TLS protocol (configured with an appropriate algorithm suite) is responsible for signing the entire message, including the security header that contains the specified token. This is sufficient to satisfy the requirement that the supporting token is signed.

Example 7.1. Example of a Supporting Tokens Policy

<wsp:Policy wsu:Id="UserNameOverTransport_IPingService_policy">
  <wsp:ExactlyOne>
    <wsp:All>
      <sp:TransportBinding> ... </sp:TransportBinding>
      <sp:SignedSupportingTokens
          xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
        <wsp:Policy>
          <sp:UsernameToken
              sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient">
            <wsp:Policy>
              <sp:WssUsernameToken10/>
            </wsp:Policy>
          </sp:UsernameToken>
        </wsp:Policy>
      </sp:SignedSupportingTokens>
      ...
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>
Where the presence of the sp:WssUsernameToken10 sub-element indicates that the UsernameToken header should conform to version 1.0 of the WS-Security UsernameToken specification.

Token types

In principle, you can specify any of the WS-SecurityPolicy token types in a supporting tokens assertion. For SOAP-level authentication, however, only the sp:UsernameToken token type is relevant.

sp:UsernameToken

In the context of a supporting tokens assertion, this element specifies that a WS-Security UsernameToken is to be included in the security SOAP header. Essentially, a WS-Security UsernameToken is used to send username/password credentials in the WS-Security SOAP header. The sp:UsernameToken element has the following syntax: 
<sp:UsernameToken sp:IncludeToken="xs:anyURI"? xmlns:sp="..." ... >
  (
    <sp:Issuer>wsa:EndpointReferenceType</sp:Issuer> |
    <sp:IssuerName>xs:anyURI</sp:IssuerName>
  ) ?
  <wst:Claims Dialect="..."> ... </wst:Claims> ?
  <wsp:Policy xmlns:wsp="...">
    (
      <sp:NoPassword ... /> |
      <sp:HashPassword ... />
    ) ?
    (
      <sp:RequireDerivedKeys /> |
      <sp:RequireImpliedDerivedKeys ... /> |
      <sp:RequireExplicitDerivedKeys ... />
    ) ?
    (
      <sp:WssUsernameToken10 ... /> |
      <sp:WssUsernameToken11 ... />
    ) ?
    ...
  </wsp:Policy>
  ...
</sp:UsernameToken>
The sub-elements of sp:UsernameToken are all optional and are not needed for ordinary authentication. Normally, the only part of this syntax that is relevant is the sp:IncludeToken attribute.
Note
Currently, in the sp:UsernameToken syntax, only the sp:WssUsernameToken10 sub-element is supported in Apache CXF.

sp:IncludeToken attribute

The value of the sp:IncludeToken must match the WS-SecurityPolicy version from the enclosing policy. The current version is 1.2, but legacy WSDL might use version 1.1. Valid values of the sp:IncludeToken attribute are as follows:
Never
The token MUST NOT be included in any messages sent between the initiator and the recipient; rather, an external reference to the token should be used. Valid URI values are:
1.2
http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/ IncludeToken/Never
1.1
http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/ IncludeToken/Never
Once
The token MUST be included in only one message sent from the initiator to the recipient. References to the token MAY use an internal reference mechanism. Subsequent related messages sent between the recipient and the initiator may refer to the token using an external reference mechanism. Valid URI values are:
1.2
http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/ IncludeToken/Once
1.1
http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/ IncludeToken/Once
AlwaysToRecipient
The token MUST be included in all messages sent from initiator to the recipient. The token MUST NOT be included in messages sent from the recipient to the initiator. Valid URI values are:
1.2
http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/ IncludeToken/AlwaysToRecipient
1.1
http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/ IncludeToken/AlwaysToRecipient
AlwaysToInitiator
The token MUST be included in all messages sent from the recipient to the initiator. The token MUST NOT be included in messages sent from the initiator to the recipient. Valid URI values are:
1.2
http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/ IncludeToken/AlwaysToInitiator
1.1
http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/ IncludeToken/AlwaysToInitiator
Always
The token MUST be included in all messages sent between the initiator and the recipient. This is the default behavior. Valid URI values are:
1.2
http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/ IncludeToken/Always
1.1
http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/ IncludeToken/Always

SupportingTokens assertions

The following kinds of supporting tokens assertions are supported:

sp:SupportingTokens

This element requires a token (or tokens) of the specified type to be included in the wsse:Security header. No additional requirements are imposed.
Warning
This policy does not explicitly require the tokens to be signed or encrypted. It is normally essential, however, to protect tokens by signing and encryption.

sp:SignedSupportingTokens

This element requires a token (or tokens) of the specified type to be included in the wsse:Security header. In addition, this policy requires that the token is signed, in order to guarantee token integrity.
Warning
This policy does not explicitly require the tokens to be encrypted. It is normally essential, however, to protect tokens both by signing and encryption.

sp:EncryptedSupportingTokens

This element requires a token (or tokens) of the specified type to be included in the wsse:Security header. In addition, this policy requires that the token is encrypted, in order to guarantee token confidentiality.
Warning
This policy does not explicitly require the tokens to be signed. It is normally essential, however, to protect tokens both by signing and encryption.

sp:SignedEncryptedSupportingTokens

This element requires a token (or tokens) of the specified type to be included in the wsse:Security header. In addition, this policy requires that the token is both signed and encrypted, in order to guarantee token integrity and confidentiality.

sp:EndorsingSupportingTokens

An endorsing supporting token is used to sign the message signature (primary signature). This signature is known as an endorsing signature or secondary signature. Hence, by applying an endorsing supporting tokens policy, you can have a chain of signatures: the primary signature, which signs the message itself, and the secondary signature, which signs the primary signature.
Note
If you are using a transport binding (for example, HTTPS), the message signature is not actually part of the SOAP message, so it is not possible to sign the message signature in this case. If you specify this policy with a transport binding, the endorsing token signs the timestamp instead.
Warning
This policy does not explicitly require the tokens to be signed or encrypted. It is normally essential, however, to protect tokens by signing and encryption.

sp:SignedEndorsingSupportingTokens

This policy is the same as the endorsing supporting tokens policy, except that the tokens are required to be signed, in order to guarantee token integrity.
Warning
This policy does not explicitly require the tokens to be encrypted. It is normally essential, however, to protect tokens both by signing and encryption.

sp:EndorsingEncryptedSupportingTokens

This policy is the same as the endorsing supporting tokens policy, except that the tokens are required to be encrypted, in order to guarantee token confidentiality.
Warning
This policy does not explicitly require the tokens to be signed. It is normally essential, however, to protect tokens both by signing and encryption.

sp:SignedEndorsingEncryptedSupportingTokens

This policy is the same as the endorsing supporting tokens policy, except that the tokens are required to be signed and encrypted, in order to guarantee token integrity and confidentiality.