Share via

How to: Configure a Security Context Token Service

  • Article

A security context token service issues SecurityContextToken security tokens that a SOAP message sender can use to sign or encrypt SOAP message between it and a target Web service. The target Web service can host the security token service.

To configure a security context token service that issues security tokens

  1. Create a virtual directory in Internet Information Services (IIS).

  2. Create a Web.config file and place it in the virtual directory created in step 1.

  3. Install the microsoft.web.services2 confgiguration section handler by adding a <section> Element (WSE for Microsoft .NET) element to the <configuration> section of the Web.config file. This adds the microsoft.web.services2 configuration section handler for this configuration file.

    The following code example shows how to add the microsoft.web.services2 configuration section handler.

    <configuration>
   <configSections>
      <section name="microsoft.web.services2"
               type="Microsoft.Web.Services2.Configuration.WebServicesConfiguration, Microsoft.Web.Services2, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
   </configSections>
</configuration>

  4. Specify how the security token service issues security tokens by adding <tokenIssuer> Element (WSE for Microsoft .NET) (2), <autoIssueSecurityContextToken> Element, and <serverToken> Element elements to the Web.config file.

    1. Add a <tokenIssuer> Element (WSE for Microsoft .NET) (2) element to the configuration file for the application.
      The <tokenIssuer> Element (WSE for Microsoft .NET) (2) element has child elements that allow you to specify the security token service's settings.

    2. Add an <autoIssueSecurityContextToken> Element as a child element of the <tokenIssuer> Element (WSE for Microsoft .NET) (2) element.
      The enabled attribute specifies whether Web services for which the configuration file applies to automatically issue SecurityContextToken security tokens for valid security token requests. Set the enabled attribute to true to automatically issue SecurityContextToken security tokens using the SecurityContextTokenService security token service supplied by WSE.
      When you create a custom security token service that issues SecurityContextToken security tokens, set the type attribute to the security token service's type.

      Note

      When you use the <autoIssueSecurityContextToken> element, one endpoint is shared between the target Web service and the security context token service. If you must have separate endpoints for the security context token service and the target Web service, follow the steps in the How to: Configure a Custom Security Token Service topic and set the type attribute to SecurityContextTokenService.

    3. Add a <serverToken> Element element to the Web.config file specifying the security token that is used to sign Request Security Token Responses (RSTRs) from the security token service.
      The contents of the <serverToken> element depend on the type of security token used to sign the RSTR. WSE provides a built-in method to retrieve a key for an X509SecurityToken along with a method to retrieve other types of keys. To retrieve keys that are not related to an X509SecurityToken, create and configure a class derived from the SecurityTokenManager class.
      To retrieve a key for an X.509 certificate, use the X.509 Certificate Tool (WseCertificate2.exe) to specify the value of the <serverToken> element.

    The following code example enables the automatic issuing of SecurityContextToken security tokens and specifies the security token used to sign RSTRs.

    <configuration>
  <microsoft.web.services2>
    <tokenIssuer>
      <autoIssueSecurityContextToken enabled="true" /> 
      <serverToken>
        <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
          <wsse:SecurityTokenReference xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <wsse:KeyIdentifier ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509SubjectKeyIdentifier">ZPGrPnuqATeSgVjLYcmiY/GSWWY=</wsse:KeyIdentifier>
          </wsse:SecurityTokenReference>
        </KeyInfo>
      </serverToken>
    </tokenIssuer>
  </microsoft.web.services2>
</configuration>

    To encode a key identifier with Base64, use WSE Settings 2.0 Tool (WseSettingsVS2.dll and WseConfigEditor2.exe).

  5. Note   When an X.509 certificate is used to sign the RSTR, the certificate must have a private key and be accessible from the ASP.NET worker process. Typically, this means the X.509 certificate must be in the Local Machine certificate store and the ASPNET user account must be given read/write access to the key. For more information about managing X.509 certificates, see Managing X.509 Certificates.

Example

The following Web.config file configures a security token service that automatically issues SecurityContextToken security tokens for SOAP requests sent to this virtual directory.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="microsoft.web.services2" type="Microsoft.Web.Services2.Configuration.WebServicesConfiguration, Microsoft.Web.Services2, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
  </configSections>
  <microsoft.web.services2>
    <tokenIssuer>
      <autoIssueSecurityContextToken enabled="true" />       <serverToken>
        <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
          <wsse:SecurityTokenReference xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <wsse:KeyIdentifier ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509SubjectKeyIdentifier">ZPGrPnuqATeSgVjLYcmiY/GSWWY=</wsse:KeyIdentifier>
          </wsse:SecurityTokenReference>
        </KeyInfo>
      </serverToken>
    </tokenIssuer>
  </microsoft.web.services2>  
  <system.web>
        <webServices>
      <soapExtensionTypes>
        <add type="Microsoft.Web.Services2.WebServicesExtension, Microsoft.Web.Services2, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" priority="1" group="0" />
      </soapExtensionTypes>
    </webServices>
  </system.web>
</configuration>

See Also

Tasks

How to: Obtain a Security Token From a Security Context Token Service

Reference

<section> Element (WSE for Microsoft .NET)
<serverToken> Element
<autoIssueSecurityContextToken> Element

Other Resources

Issuing Security Tokens