SE uses security tokens internally to represent security claims from Web service methods. The security tokens let WSE authenticate the user, validate the password, and check whether the user has sufficient rights to execute the desired Web service method. The Web services security implementation includes authentication as well as authorization. This article discusses how to use custom authentication methods in WSE using an example that authenticates incoming SOAP messages and then authorizes the consumption of a particular service using AzMan
, (Windows' Authorization Manager) with custom principals. As an example, the article uses a telecom dealer application, which lets prospective telecommunications dealers activate postpaid customers and manage their accounts.
When you configure WSE 2.0 in your Web service project, clients of that Web service will create two Web service proxy classes named according to your project, such as MyWebService1 and MyWebService1WSE. The second proxy class, derived from the WSE Microsoft.Web.Services2.WebServicesClientProtocol class, contains support for adding WSE Security tokens used to authenticate clients. Client programs must add a security tokenfor example, a Username tokento the Tokens
collection of the RequestSoapContext of the Web service instance implemented with WSE. The Username token isn't the only possible security token; there are other security tokensand you can also create a custom security token by creating a custom SecurityTokenManager class. But a security token of some type is required.
When a client application sends a Username security token, a UsernameTokenManager handles the authentication. The TokenManager authenticates the Username token (which contains a username and password) against the Windows principals stored in an Active Directory (AD) database by default. But you can authenticate a Username token against any other user database by extending the SecurityTokenManager class to handle your specific security token.
For example, suppose you need to create a custom security token manager to authenticate security tokens against the credentials of agents in a SQL Server database. The following code snippet shows how a client program might send a Username token:
public class TestWseWsClient
public static void Main(String args)
UsernameToken userTok = null;
string agentId = "AGT0001";
string authCode = "6ndBsNS";
DATPostpaid.DATWebServiceWse wse = new
userTok = new UsernameToken(agentKey,authCode,
Console.WriteLine("Returned Message: " +
The TestWseWsClient class shown above creates a UsernameToken instance, specifies the username as agentKey
, the password as authCode
, and sends the password using the SendPlainText
option. It then adds that token to the RequestSoapContext's Tokens
To make a call to a Web method named WelcomeAuthenticateAgent
() of a WSE-implemented Web service, the client sends the SOAP message containing the UsernameToken to the Web service endpoint. There, the server must determine whether the user specified in the UsernameToken can be authenticated. In this scenario, that requires some custom code to authenticate the token using a specific database.
Whenever the Client program invokes a Web service with the WSE-enabled proxy class, WSE deserializes the incoming SOAP message and then calls the VerifyToken
method for each UsernameToken it contains. The VerifyToken
method calls the AuthenticateToken
method to get the correct password for the specified user. If you do not extend UserNameTokenManager by overriding the AuthenticateToken
method then the default UserNameTokenManager.AuthenticateToken
method verifies the username and password in the SOAP message by calling the LogonUser
shows an example that overrides the default AuthenticateToken
|Figure 1. The WSE 2.0 Settings Dialog: To reach this dialog, right click on your WSE Web service project and select "WSE Settings 2.0" from the menu.|
|Figure 2. SecurityToken Manager Definition: The dialog contains the fields needed to define the token.|
Notice that the AgentAuthentication class in Listing 1
overrides the AuthenticateToken
method and makes a call to an AuthenticateAgentData
method to validate the username and password contained in the token. AuthenticateAgentData
is a data access method that runs a stored procedure to verify the agentId
values. If the agent can be authenticated, the AuthenticateToken
method returns the password which can then be compared against the password specified in the UsernameToken. If they're the same, the application processes the body of the SOAP message by transferring control to the Web method called AccountAdjustment
. Otherwise, the application rejects the SOAP message by raising a Microsoft.Web.Services2.Security.SecurityFault exception, which contains the message: "The security token could not be authenticated or authorized."
For WSE to use the custom code, you need to define the UserNameTokenManager class and the UserNameToken it should use in the WSE 2.0 property sheet. To do that, right click on your WSE Web service project and select the "WSE Settings 2.0" item. You'll see the dialog shown in Figure 1
. Switch to the Security tab and you'll see a list of Security Token Managers (the list will be empty initially).
Click on the Add button underneath the list. A dialog box will appear containing three text boxes, as shown in Figure 2
Fill in the text fields as shown in Table 1 below:
||The strong name of the class that extends UserNameTokenManager, the Web service class that authenticates using this token manager.
||WSE generates a proxy using this XSD schema.
||The type of security token used in your SecurityTokenManager class. The sample code uses a UserNameToken.