<usernameForCertificateSecurity> Element

Article
09/13/2006

Represents a turnkey security assertion that uses an X509SecurityToken security token to protect SOAP messages. The client is authenticated using a UsernameToken security token. WS-Security 1.1 is required for this assertion.

<policies> Element
<policy> Element (Policy)

<usernameForCertificateSecurity
  clientActor
  establishSecurityContext="true|false"
  messageProtectionOrder="Signature and encryption order"
  renewExpiredSecurityContext="true|false"
  requireDerivedKeys="true|false"
  requireSignatureConfirmation="true|false"
  serviceActor
  ttlInSeconds >
  <clientToken/>
  <serviceToken/>
  <protection/>
</usernameForCertificateSecurity >

Microsoft.Web.Services3.Design.UsernameForCertificateAssertion

Attributes and Elements

Attributes

Attribute	Description
clientActor	Optional attribute. Specifies the actor attribute on the Security SOAP header for a SOAP message destined for a Web service client to which this policy assertion applies. When the SOAP message is not routed through an intermediary, such as a SOAP router, the actor attribute is an empty string (""). When the policy assertion applies to an intermediary, specify the URI for the intermediary. The default value is an empty string ("").
establishSecurityContext	Optional attribute. Specifies whether a secure conversation is established using SecurityContextToken security tokens. Possible values are true and false. true specifies that this security assertion secures the security token request and its response (the RST and RSTR) and SOAP messages exchanged between the client and the Web service are secured using SecurityContextToken security tokens. The default value is false.
messageProtectionOrder	Optional attribute. Specifies the order of operation for digital signatures and message encryption. SignBeforeEncrypt specifies that a digital signature is generated for the SOAP message before any portion of the SOAP message is encrypted, but the digital signature is not encrypted. SignBeforeEncryptAndEncryptSignature specifies that a digital signature is generated for the SOAP message before any portion of the SOAP message is encrypted, and the digital signature is encrypted.
renewExpiredSecurityContext	Optional attribute. Specifies that a new SecurityContextToken security token is automatically requested as the current one expires when a secure conversation is established. This is applicable only when the establishSecurityContext attribute for this policy assertion is true.
requireDerivedKeys	Optional attribute. Specifies whether DerivedKeyToken security tokens are used. Possible values are true and false. The default value is false.
requireSignatureConfirmation	Optional attribute. Specifies whether the Web service sends a confirmation that verifies the client's digital signature and whether the client rejects SOAP responses without a signature confirmation. This is always false.
serviceActor	Optional attribute. Specifies the actor attribute on the Security SOAP header for a SOAP message destined for a Web service to which this policy assertion applies. When the SOAP message is not routed through an intermediary, such as a SOAP router, the actor attribute is an empty string (""). When the policy assertion applies to an intermediary, specify the URI for the intermediary. The default value is an empty string (""). Note When the serviceActor attribute is set to a value other than an empty string (""), then the establishSecurityContext attribute must be set to false.
ttlInSeconds	Optional attribute. Specifies the default number of seconds that a SOAP message is valid after its creation. The default value is 5 minutes (300 seconds).

Child Elements

Element	Description
<clientToken> Element	Optional element. Specifies the security token that authenticates the client.
<protection> Element	Optional element. Specifies the SOAP message parts that are signed, encrypted, or both.
<serviceToken> Element (Policy)	Optional element. Specifies the X509SecurityToken security token that protects the SOAP messages. If the details of the X509SecurityToken security token are not specified in the policy file, the security token must be specified using code.

<clientToken> Element

Optional element. Specifies the security token that authenticates the client.

<protection> Element

Optional element. Specifies the SOAP message parts that are signed, encrypted, or both.

<serviceToken> Element (Policy)

Optional element. Specifies the X509SecurityToken security token that protects the SOAP messages.

If the details of the X509SecurityToken security token are not specified in the policy file, the security token must be specified using code.

Parent Elements

Element	Description
<policy> Element	Specifies a SOAP message requirement.

Remarks

This security assertion can have zero or more <protection> elements. Use more than one <protection> element to apply protection requirements for each operation using the requestAction attribute. Each of the <protection> elements must have a unique requestAction attribute unless the requestAction is omitted. Only one of the <protection> elements can omit the requestAction attribute, and that element defines the default protection requirements for the policy.

SOAP requests sent by the client and SOAP responses sent by the Web service are protected as specified in the following table.

SOAP message	Protection	Description
SOAP request	Digital Signature	The SOAP message parts specified in the <request> child element of the <protection> element and the client's UsernameToken security token are digitally signed using an EncryptedKeyToken security token that is created using the Web service's X509SecurityToken security token.
SOAP request	Encryption	The SOAP message parts specified in the <request> child element of the <protection> element and the client's UsernameToken security token are encrypted using an EncryptedKeyToken security token that is created using the Web service's X509SecurityToken security token.
SOAP response	Digital Signature	The SOAP message parts specified in the <response> or <fault> child elements of the <protection> element are digitally signed using the EncryptedKeyToken security token that encrypted the SOAP request.
SOAP response	Encryption	The SOAP message parts specified in the <response> or <fault> child elements of the <protection> element are encrypted using the EncryptedKeyToken security token that encrypted the SOAP request.

Example

The following code example demonstrates how to secure a SOAP message exchange using an X509SecurityToken security token for protection and a UsernameToken security token for client authentication. The code example defines a policy assertion named ClientPolicy that specifies that a X509SecurityToken security token is used to digitally sign the SOAP message, and to encrypt the <body> element of the SOAP message. The keys used to generate the digital signature and encrypt the <body> element are not the same keys, but rather are derived from the same key. In the following code example, the user name and password must be added in code.

<policies>
  <extensions>
    <extension name="usernameForCertificateSecurity" type="Microsoft.Web.Services3.Design.UsernameForCertificateAssertion, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
    <extension name="x509" type="Microsoft.Web.Services3.Design.X509TokenProvider, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
    <extension name="requireActionHeader"
               type="Microsoft.Web.Services3.Design.RequireActionHeaderAssertion, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
  </extensions>
  <policy name="ClientPolicy">
    <usernameForCertificateSecurity 
      establishSecurityContext="false" 
      renewExpiredSecurityContext="true" 
      requireSignatureConfirmation="false" 
      messageProtectionOrder="SignBeforeEncrypt" 
      requireDerivedKeys="true" >
      <serviceToken>
        <x509
          storeLocation="CurrentUser"
          storeName="AddressBook"
          findValue="CN=WSE2QuickStartServer"
          findType="FindBySubjectDistinguishedName" />
      </serviceToken>
      <protection>
        <request
          signatureOptions="IncludeAddressing, IncludeTimestamp, IncludeSoapBody"
          encryptBody="true" />
        <response 
          signatureOptions="IncludeAddressing, IncludeTimestamp, IncludeSoapBody"
          encryptBody="true" />
        <fault
          signatureOptions="IncludeAddressing, IncludeTimestamp, IncludeSoapBody"
          encryptBody="false" />
      </protection>
    </usernameForCertificateSecurity>
    <requireActionHeader />
  </policy>
</policies>

Partager via

<usernameForCertificateSecurity> Element

Attributes and Elements

Attributes

Child Elements

Parent Elements

Remarks

Example

See Also

Tasks

Reference

Concepts

Other Resources

Ressources supplémentaires