Establish Trusted Communication with WS-Secure Conversation

3901c08_final.qxd 6/30/04 3:18 PM Page 187 CHAPTER Establish Trusted Communication with WS-Secure Conversation THE WS-SECURE CONVERSATION specification allows Web services and clients to establish a token-based, secure conversation for the duration of a session It is analogous to the Secure Sockets Layer (SSL) protocol that provides on-demand, secure communications over the HTTP transport channel Secure conversations are well suited to participants that not inherently trust each other, either because they have no ongoing relationship, or, for example, because they have not established certificate-based public-private keys to secure their conversations In Chapters and 7, you saw how the WS-Security and WS-Policy family of specifications combine to provide a comprehensive approach to securing Web services Together these specifications provide an assortment of security options, including digital signatures, encryption algorithms, and custom authorization schemes In previous chapters, I discussed these technologies in the context of protective security, meaning that they protect messages in transit and keep unwanted eyes from discovering sensitive information This is certainly an important application of these technologies, and it needs no further explanation But for the purpose of this chapter, I need to expand the context within which to view these technologies They are no longer needed just for protective security; in a broader context, they are needed for establishing trusted communications In the discussions so far, we have made the big assumption that the client and Web service automatically trust each other By this, I mean the assumption that they both have an equivalent confidence in the integrity of the security tokens they are using to sign, encrypt, and otherwise secure their communications For example, if a client and a Web service agree to encrypt their messages using a digital X.509 certificate, then they must both trust the source of the certificate, and must be comfortable using the private and public keys that are generated from the certificate In a sense, both the client and the Web service have come to a mutual agreement that they will offload the burden of proving trust to a thirdparty (trusted!) source, which issues a digital certificate to act as the tangible record of that trust 187 3901c08_final.qxd 6/30/04 3:18 PM Page 188 Chapter Of course, the issue is more complex than this When it comes to certificates, for many of us they are a necessary requirement for trusted communication As a client, I may have all the trust in the world for a service provider, but I still need to use a digital certificate for the mechanics of signing and encrypting shared messages I happen to be comfortable with digital certificates for most communication requirements because it represents certified trust However, other client-service communications may be just as well off using a simpler UsernameToken security token, which is based on a simple username-password combination that gets hashed during transit Luckily, the WSE implementation of the WS-Security specification is flexible, and you have a choice of security token types to use for conducting trusted communication The point is that your preferred security tokens and your preferred hashing and encryption algorithms are simply a means to a bigger goal of establishing trusted communication, otherwise known in the Web services world as secure conversation There is no single correct choice of technologies that you should always use Instead, you need to be using those technologies that are appropriate for establishing a trusted, secure conversation between a given client and Web service The rules can change depending on who is doing the communicating This chapter focuses on how you establish session-oriented, trusted communications using the WS-Secure Conversation specification The great thing about the WS-Specifications is that many of the concepts complement each other and build on each other The understanding that you now have about WS-Security and WSPolicy will translate directly into the concepts behind WS-Secure Conversation By the end of this chapter, you will have a good understanding of what constitutes secure conversation, and a broader appreciation for the usefulness of the WS-Security family of specifications Overview of Secure Conversation The WS-Secure Conversation (and WS-Trust) specifications provide the means for a client and a service to establish an optimized secure communication channel for a limited duration of time Secure conversation is based on security tokens that are procured by a service token provider This process involves an initial amount of overhead, but once the channel is established, the client and service exchange a lightweight, signed security context token, which optimizes message delivery times compared with using regular security tokens The security context token enables the same signing and encryption features that you are used to with regular security tokens Secure conversation is analogous to communications over the HTTPS protocol HTTPS establishes a secure channel for the duration of a session, and ceases to be in effect once that session is over The classic example is an eCommerce 188 3901c08_final.qxd 6/30/04 3:18 PM Page 189 Establish Trusted Communication with WS-Secure Conversation transaction, in which you browse a catalog over an unsecured channel, but then you establish a secure channel for the purpose of completing a sales transaction with the vendor The communication needs to be secure because sensitive payment and order information is being exchanged, and so the client and the vendor need to establish a secured channel for as long as it takes to complete the transaction For performance reasons, the client does not need or even want to establish a continuous secure session for every interaction with the vendor HTTPS is useful for providing on-demand secure communication for exactly as long as it is needed HTTPS and WS-Secure Conversation differ in one important way: HTTPS is not typically used for client authentication, whereas secure conversation is NOTE A secure conversation has the following characteristics: • It is based on established security tokens, including UsernameTokens and X.509 certificates • It uses a dedicated service token provider to generate a signed service context token, which is a lightweight security proxy • It provides a secure communication channel for the duration of the session • It provides optimized performance for session-oriented communications with multiple round-trips (by using the security context token) The difference between secure conversation and standard secure message exchange (with WS-Security and WS-Policy) is that a standard security policy framework establishes a fixed security policy that all service clients must adhere to However, secure conversation has a more dynamic aspect The client and service can initiate a secure channel as needed, rather than based on an established policy framework Secure conversation uses security tokens that are issued for the purpose of a specific communication The service itself can act as the provider of these security tokens Alternatively, this responsibility can be offloaded to a thirdparty service token provider, which is a dedicated resource that acts as a trusted intermediary between clients and services, and the issuer of security tokens for their secure conversations Figure 8-1 provides an architecture diagram for typical secure conversation solutions 189 3901c08_final.qxd 6/30/04 3:18 PM Page 190 Chapter (1) The Client issues a signed request to the STS for a Security Context Token (2) The STS responds by issuing a Security Context Token SERVICE TOKEN PROVIDER (STS) (3) The Client issues a secured Web service request using the Security Context Token DOMAIN BOUNDARY (only applies if the STS and the Web service are deployed on separate servers) CLIENT DOMAIN BOUNDARY SERVICE (4) The Web service issues a secured response using the Security Context Token Note: The Web Service and the Service Token Provider may be accessed through the same virtual directory; or may be deployed on separate servers Note: The Client Security Context the STS prior to first request to retrieves a Token from initiating the the Web service Figure 8-1 Architecture diagram for a secure conversation solution A secure conversation is initiated by a client that requires an on-demand secure communication session with a Web service The session may be required for the duration of one request, or for several back-and-forth requests and responses between the client and Web service The workflow for establishing and conducting a secure conversation is presented in Figure 8-1, and typically follows four steps: Step 1: The client issues a signed request to the security token service provider for a security context token The client initiates the secure conversation by issuing a signed request to the security token service (STS) provider for a security context token The client may sign the request with any standard security token, including UsernameToken and X.509 certificates The sample solution will demonstrate using a UsernameToken security token 190 3901c08_final.qxd 6/30/04 3:18 PM Page 191 Establish Trusted Communication with WS-Secure Conversation Step 2: The security token service provider verifies the request and issues a security context token back to the client The STS provider verifies the integrity of the signed request It then generates a security context token and delivers it to the client In the sample solution the Web service itself also acts as the security token service You can, however, deploy the STS as a separate service The security context token is actually returned from the STS as a so-called request security token (RST) The client can then extract the security context token from the RST WSE 2.0 provides all of the support classes that you need to handle these tasks in code Steps and 4: The client and the Web service use the security context token for further communication The client and Web service use the security context token to secure back-and-forth request and response communications with each other The security context token can be used like any standard security token It inherits from the same base classes and its usage is no different from the security tokens you learned how to work with in Chapter Security context tokens may be cached in a global cache for future retrieval, for example, when the client will be issuing multiple requests over a period of time We will look at how to this later in the chapter Programming-wise, Web Services Enhancements (WSE) 2.0 makes it very easy to implement a service token provider because the WSE infrastructure will automatically issue security context tokens This feature is enabled by simply adding a configuration element to the service token provider’s configuration file The STS provider can be incorporated into the client’s target Web service, or the STS provider can be implemented as a dedicated Web service There is little difference in the code between a “hosted” service token provider (that resides in the client’s target Web service) and a dedicated service token provider (that resides on a separate domain) There are some significant configuration and deployment differences between the two models, but code-wise they are very similar The feature you know as Secure Conversation uses several WS-Specifications, including WS-Trust, WS-Secure Conversation, and WS-Security In addition, you can reduce code listings (and potential errors!) by implementing policy frameworks for the participating services and clients This chapter does not focus on when particular WS-Specifications come into play Instead, the focus is on understanding the concepts, and discussing practical code samples NOTE 191 3901c08_final.qxd 6/30/04 3:18 PM Page 192 Chapter How to Implement a Secure Conversation Solution It is time to dust off the familiar StockTrader service-oriented application and retrofit it to participate in a secure conversation I will discuss how to construct both the client and the Web service In the solution, the Web service is both a service provider and a secure token service provider This means that the Web service is responsible for supplying its clients with the security token for establishing a session-oriented secure conversation Figure 8-2 shows the Solution Explorer for a new sample solution called WSSecureConversation.sln, which you will see how to build in this section It includes three projects, which represent the following four components: The Web service provider: WSSecureConvService.csproj The Security Token Service provider: WSSecureConvService.csproj The Web service client: WSSecureConvClient.csproj Interface definition assembly: StockTraderTypes.csproj Figure 8-2 The Visual Studio NET Solution Explorer for the WSSecureConversation solution 192 3901c08_final.qxd 6/30/04 3:18 PM Page 193 Establish Trusted Communication with WS-Secure Conversation As noted earlier, the Web service hosts the security token service provider, so it is playing double duty in this project All that the Web service actually does is to provide an endpoint for clients to access the STS HTTP handler The References nodes are expanded so you can see dependencies However, the complexity is not in the project structure; rather, it lies in the nature of the communication pathways between the client and service The sample solution follows the architecture that is presented in Figure 8-1 Before I present the solution, let’s review the required implementation steps for both the Web service and the client who are participating in the secure conversation Before we look at how to build the sample solution, let’s review the conceptual steps that are required to implement the Web service, the Security Token Service provider, and the client projects How to Implement the Web Service and the Security Token Service Provider The implementation for the Web service requires the following four steps: Step 1: Configure the Web service to use WSE 2.0 Verify that the web.config file includes the standard WSE elements for the WebServicesConfiguration and WebServicesExtension classes Remember to use the WSE 2.0 Configuration Settings Editor to avoid having to manually type these entries Step 2: Configure the security token service provider in the web.config file The WSE class framework provides a ready-to-use handler for implementing the STS provider All you have to is register it correctly in the web.config file, as outlined in more detail later in this chapter The handler will automatically generate a security token for use in the secure conversation Step 3: Create a custom token manager This step is required in order to process the signature of the client request that initiates the secure conversation If the client’s signature cannot be verified, then the rest of the workflow cannot proceed Recall that this signature will later be used to sign the security context token Step 4: Implement policy verification In the Web service itself, implement code to verify policy requirements programmatically, including digital signature and encryption requirements Alternatively, you can create a policy framework file 193 3901c08_final.qxd 6/30/04 3:18 PM Page 194 Chapter How to Implement the Client The client application requires a fair amount of custom code, although it shares many similarities with what you have seen in previous chapters The biggest difference from before is that the client now implements the workflow for initiating the request to the security token service provider This code is in addition to any code that the client already implements for interfacing with the target Web service The implementation for the client requires the following six steps: Step 1: Generate a security token for signing the upcoming service token request This security token has nothing to with the security context token that you will ultimately use to secure the conversation between service and client Instead, this security token is only used by the client to generate a signed request to receive a security context token from the STS provider In turn, the STS provider will sign its response when it delivers a security context token back to the client In this example, I will show you how to use a simple UsernameToken security token to sign the initial request and response for the security context token Note that the request to the STS provider must be signed, otherwise the request will be rejected Step 2: Set a proxy reference to the security token service provider Clients communicate with standard Web services using a proxy class In the same way, they also communicate with a Security Token Service provider using a proxy class, called SecurityContextTokenServiceClient, which is a member of the Microsoft.Web.Services2.Security namespace Step 3: Issue a signed request to the provider for a security context token The request for a security context token is issued by the client via a specialized proxy class called the SecurityContextTokenServiceClient class, which is initialized with a URI reference to the security token service provider The specialized proxy class provides a method called IssueSecurityContextTokenAuthenticated for issuing the request and for receiving the response back from the STS provider Note that this method may be called synchronously or asynchronously However, you will usually call the method synchronously because no further communication is typically possible between the service and client if this method fails to return a valid security context token So you may prefer to wait for a synchronous call to return, and to thereby hold off on executing additional code until you know that you can proceed 194 3901c08_final.qxd 6/30/04 3:18 PM Page 195 Establish Trusted Communication with WS-Secure Conversation Step 4: Retrieve the security context token from the provider The IssueSecurityContextTokenAuthenticated method will return a valid SecurityContextToken object if the call is successful You are now ready to make secured Web service requests using this security context token Step 5: Add security elements to sign and encrypt upcoming Web service requests using the new security context token The security context token is no different from other security tokens that you worked with in Chapter 6, including the UsernameToken and X509SecurityToken classes You add the security context token to the SOAP request message header, just as you would any other security token If you need to make multiple service requests over an extended period of time, then you may wish to add the security context token to a global cache for future retrieval You will also then need to store the token ID for future reference because it is possible that the global cache will contain other security tokens, and you will need a way to retrieve the correct token from the cache Step 6: Proceed to call the Web service methods as usual After all this work, nothing much changes The Web service methods are called as usual, and the only difference is that the requests and responses are being secured with the security context token for the duration of the session Build a Secure Conversation Solution I will now review the detailed steps for building the Web service and the client in a secure conversation solution This section follows the outlines of the previous sections on how to implement the Web service and the client Build the Web Service and the Security Token Service Provider The Web service and STS provider are contained within the project WSSecureConvService.csproj, and are built as described in the following sections 195 3901c08_final.qxd 6/30/04 3:18 PM Page 196 Chapter Step 1: Configure the Web Service to Use WSE 2.0 This step will add registration information to the web.config file for the standard WebServicesConfiguration and WebServicesExtension classes Use the WSE 2.0 Configuration Settings Editor, or else manually add the required configuration settings Step 2: Configure the Security Token Provider The WSE 2.0 infrastructure will automatically issue security context tokens with the simple configuration entry shown in Listing 8-1 Listing 8-1 Configure the Security Token Service Provider && ➥ PolicyEnforcementSecurityTokenCache.GlobalCache.Count > 0) { sct = RetrieveSecurityContextTokenFromGlobalCache(client.SCTID); } // Request a new security context token if one was not available // from the global cache if (sct == null) { 211 3901c08_final.qxd 6/30/04 3:18 PM Page 212 Chapter // Create a security token to use as the base for the // security context token (SCT), which will be issued // later by the security token service (STS) SecurityToken token = client.GetSTSRequestSigningToken(); // Create a SecurityContextTokenServiceClient (STSClient) // that will get the SecurityContextToken string secureConvEndpoint = ➥ ConfigurationSettings.AppSettings["tokenIssuer"]; SecurityContextTokenServiceClient STSClient = ➥ new SecurityContextTokenServiceClient(new Uri( secureConvEndpoint )); // Retrieve the server certificate, to include in the signed request to // the security token service (STS) SecurityToken issuerToken = client.GetServerToken(); // Request the security context token, use the client's // signing token as the base sct = STSClient.IssueSecurityContextTokenAuthenticated( ➥ token, issuerToken); // Cache the security context token in the global cache for // future requests You must cache this token if you will be making // multiple distinct requests Otherwise, you will continue to generate // new security context tokens PolicyEnforcementSecurityTokenCache.GlobalCache.Add(sct); // Cache the security context token ID for future retrieval client.SCTID = sct.Id; } } catch {} return sct; } At the beginning of Listing 8-16, the method attempts to retrieve an existing security context token from the global cache using a method called RetrieveSecurityContextTokenFromGlobalCache Listing 8-17 provides the code listing for this method 212 3901c08_final.qxd 6/30/04 3:18 PM Page 213 Establish Trusted Communication with WS-Secure Conversation Listing 8-17 The RetrieveSecurityContextTokenFromGlobalCache Method private SecurityContextToken ➥ RetrieveSecurityContextTokenFromGlobalCache(string SCTID) { // Purpose: Retrieve a security context token from the global cache SecurityContextToken sct = null; try { // Loop through the collection of security context tokens System.Collections.IEnumerator enmTokens = ➥ PolicyEnforcementSecurityTokenCache.GlobalCache.GetEnumerator(); SecurityContextToken token; while (enmTokens.MoveNext()) { token = (SecurityContextToken)enmTokens.Current; if (token.Id == SCTID) { sct = token; break; } } } catch {} return sct; } The RetrieveSecurityContextTokenFromGlobalCache method enumerates through all available security tokens in the global cache, and looks for a match against a specific token ID If no match is found, or if tokens are no longer available in the cache, then the method simply returns null, which triggers the RequestSecurityContextToken method to generate the security context token from scratch Notice that Listing 8-16 automatically adds new security context tokens to the global cache The method is implemented in such a way as to avoid the possibility of adding duplicate security context tokens to the global cache As an exercise, you can implement the client as a Windows Forms application, rather than as a console application, and provide buttons on the form that call different methods in the StockTrader Web service For example, one button would call the RequestQuote method, while another would call the PlaceTrade method You can request the security context token in the form’s initialization code, and then store the token in the global cache You can then retrieve this 213 3901c08_final.qxd 6/30/04 3:18 PM Page 214 Chapter token every time the user clicks a button on the form to make a new request to the Web service As a final note, this chapter describes a number of code-intensive steps for implementing secure conversation In reality, several of these steps can be handled automatically for you by using policy frameworks, such as the checks for digital signatures and encryption on incoming and outgoing messages Chapter describes policy frameworks in detail Summary The WS-Secure Conversation specification provides a token-based, sessionoriented, on-demand, secure channel for communication between a Web service and client WS-Secure Conversation is analogous to the Secure Sockets Layer protocol that secures communications over HTTP WSE 2.0 provides support for implementing secure conversation in the following ways: • It provides a prebuilt assembly for the security token service provider • It provides a UsernameTokenManager class for processing a signed request from the client to initiate the secure conversation • It provides a specialized proxy class for the client to request a security context token from a provider • It provides a dedicated global cache for storing security context tokens In the next chapter, I will shift the focus to SOAP messaging, and the collection of support specifications that includes WS-Addressing and WS-Referral The discussion on WSE 2.0 support for SOAP messaging will bring you back full circle to where the book began, with the discussion on the importance of messages in service-oriented applications 214 ... 3:18 PM Page 211 Establish Trusted Communication with WS-Secure Conversation With caching it also becomes possible for a client to initiate more than one secure conversation with multiple services... NET Solution Explorer for the WSSecureConversation solution 192 3901c08_final.qxd 6/30/04 3:18 PM Page 193 Establish Trusted Communication with WS-Secure Conversation As noted earlier, the Web... ApplicationException("The request is not signed with an SCT."); } 200 3901c08_final.qxd 6/30/04 3:18 PM Page 201 Establish Trusted Communication with WS-Secure Conversation // Check if the Soap Message