How to: Configure a Custom Security Token Service

Article
09/15/2006

After the security token service is created, it must be configured to handle incoming SOAP requests by registering your security token service as a custom HttpHandler. Requests received by the Web server to the registered URL are then routed to the security token service for processing. The security token service can then issue a security token, if it deems the security token request is valid.

To configure a custom security token service that issues security tokens

Create a virtual directory in Internet Information Services (IIS).
Create a Web.config file and place it in the virtual directory created in step 1.
Add an <add> Element for <httpHandlers> (WSE for Microsoft .NET) element in the <httpHandlers> section of the Web.config file.

The <add> element contains the type and path attributes. The path attribute specifies the Uniform Resource Identifier (URI) that SOAP message senders can request security tokens from. The type attribute specifies the type that security token requests are routed to for processing.

In the following code example, SOAP requests made to this virtual directory for the customSecurityTokenService.ashx file are sent to the custom security token service.
```
<httpHandlers>
  <add type="CustomXmlSecToken.XmlTokenServiceHandler, CustomXmlToken" 
    path="customSecurityTokenService.ashx" 
    verb="*" />
```

Add a <section> Element (WSE for Microsoft .NET) element to the <configuration> section of the Web.config 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>

Specify the security token that is used to sign responses to security token requests by adding <tokenIssuer> Element (WSE for Microsoft .NET) (2) 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 settings for the custom security token service.
2. 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 custom 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 not related to an X509SecurityToken, a class deriving from the SecurityTokenManager class must be created and configured.
  To retrieve a key for an X.509 certificate, the contents of the <serverToken> element must adhere to the format shown in the following code example with the value of the <KeyIdentifier> element set to the Base64 encoding of the key identifier for the X.509 certificate.
The following code example specifies the security token used to sign responses to security token requests.
```
<configuration>
  <microsoft.web.services2>
    <tokenIssuer>
      <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 X.509 Certificate Tool (WseCertificate2.exe).

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 custom security token service that issues custom security tokens for SOAP requests sent to the requestXmlServer.ashx file in 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>
    <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>
      <httpHandlers>
        <add type="CustomXmlSecToken.XmlTokenServiceHandler, CustomXmlToken" 
          path="requestXmlServer.ashx" 
          verb="*" />
      </httpHandlers>
    </webServices>
  </system.web>
  <microsoft.web.services2>
    <tokenIssuer>
       <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>
</configuration>

Share via

How to: Configure a Custom Security Token Service

To configure a custom security token service that issues security tokens

Example

See Also

Reference

Other Resources

Additional resources