Export (0) Print
Expand All

Introduction

 
Retired Content

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Introduction

patterns & practices Developer Center

Web Service Security: Scenarios, Patterns, and Implementation Guidance for Web Services Enhancements (WSE) 3.0

Microsoft Corporation

patterns & practices Developer Center
Web Service Security: Home
December 2005

DownloadDownload this guide in PDF format
CommunityWeb Service Security Community Workspace [Content link no longer available, original URL:http://go.microsoft.com/fwlink/?LinkId=57044]

Contents

Overview
Common Scenarios

Overview

To design, develop, and deploy secure Web services, architects and developers must learn new technologies and consider new threats associated with exposing functionality on potentially unsecured networks. To prepare you to meet these challenges today (both now on Microsoft® Web Services Enhancements 3.0 and in the future with Windows® Communication Foundation [WCF]), the Microsoft patterns & practices team has created Web Service Security: Scenarios, Patterns, and Implementation Guidance for Web Services Enhancements (WSE) 3.0.

Architects and developers responsible for Web service security have a considerable number of options available to them. These options are further complicated by the fact that different projects and different organizations have different security requirements.

To help you consider alternative approaches to securing your Web services, this guide provides a scenario-driven approach to demonstrate situations where different security patterns are successful. The guide also combines a series of decision matrices to assist you in applying your own criteria to use the Web service security patterns to meet the requirements of your environment.

This guidance supports the following major phases of a software development life cycle:

  • Evaluation. This phase includes four common Web service security scenarios, an analysis of their key requirements, and a summary of how the decision matrices were used to select a series of design and architecture patterns to meet each scenario's requirements.
  • Design. This phase includes the security decision matrices that you can combine with architectural and design patterns to assist you in making key design choices.
  • Implementation. This phase includes composite patterns and implementation patterns that provide in-depth implementation details, including code examples that you can customize to meet the needs of your environment. Implementation patterns are provided for isolated challenges, and where appropriate, composite patterns organize critical patterns together.
  • Deployment. This phase includes composite patterns and technical supplements that provide additional information to help you understand critical challenges in the deployment life cycle.

Key guidance topics that the Web Service Security guide discusses include:

  • Choosing between message layer security and transport layer security.
  • Choosing a client authentication technology, from basic direct authentication to more sophisticated brokered solutions, including an in-depth look at X.509 certificates, using the Kerberos version 5 protocol, and solutions involving a Security Token Service (STS).
  • Protecting confidentiality of messages.
  • Detecting tampered messages.
  • Preventing the processing of replayed messages.
  • Accessing remote resources and flowing identities across tiers.
  • Preventing exceptions from revealing sensitive implementation details.
  • Protecting Web services from malformed or malicious messages.

This guidance is designed to assist those who currently use the Microsoft Visual Studio® 2005 development system and WSE 3.0. It will also be of significant use to architects and developers who plan to provide solutions using WCF.

Navigating the Web Service Security Guide

There are many different options available to help secure your Web services, and different organizations have different criteria that drive their security decisions. This guide can of course be read from start to finish, and while this is the most comprehensive approach, you may find that you only require guidance in specific areas. In an attempt to make the guidance more productive for you, this guide uses decision matrices to help highlight key criteria that should be considered when selecting one approach over another. Figure 1 illustrates an excerpt from the authentication decision matrix that helps lead you through the process of choosing between the direct authentication and brokered authentication techniques.

Ff648381.intro_f01(en-us,PandP.10).gif

Figure 1. An excerpt from the authentication decision matrix

Decision matrices are included in the introductions to many of the chapters in this guide. They can help you select which of the following to use:

This guide also contains other tools to help you get the most out of the guidance. The Appendix to this guide includes a Problem/Solution Index, where you can map specific problems to sections in the guide. This introduction also includes scenarios that share commonalities with the majority of Web services that companies are building today. The "Common Scenarios" section introduces four different scenarios that provide examples of common Web service interactions.

If you choose to read the chapters in this guide sequentially, you will benefit by understanding the importance of the sequence. The guide is divided into two parts. Part I covers core Web service security patterns, and includes three chapters:

  • Chapter 1, Authentication Patterns, helps you make the most appropriate decision regarding authentication, because many of the following Web service decisions depend on your choices for authentication.
  • Chapter 2, Message Protection Patterns, helps you understand the different message protection capabilities to determine which ones are appropriate to meet your requirements.
  • Chapter 3, Implementing Transport and Message Layer Security, helps you decide between using message layer security and transport layer security, and provides you with the implementation patterns in WSE 3.0.

Part II of the guide covers additional Web service security patterns and guidance. This information should normally be considered after you have already reviewed Part I. Part II consists of four chapters, which discuss resource access patterns, service boundary protection patterns, service deployment patterns, and technical supplements.

Additional useful information appears in the Appendix. The Appendix contains information about Web service interoperability, the Policy Analyzer for WSE 3.0, and a white paper about using patterns as a common vocabulary for individuals involved in the Information Technology industry. A glossary of commonly used terms and the Problem/Solution Index are also included in the Appendix.

Important Concepts

There are some important concepts you should understand before reviewing the different scenarios. These include:

  • Brokered authentication. This is a type of authentication where a trusted authority is used to broker authentication services between a client and a service. You can use a broker to perform authentication.
  • Client. The client accesses the Web service. The client provides credentials for authentication during the request to the Web service.
  • Credentials. A set of claims used to prove the identity of a client. They contain an identifier for the client and a proof of the client's identity, such as a password. They may also include information, such as a signature, to indicate that the issuer certifies the claims in the credential.
  • Direct authentication. A type of authentication where the service validates credentials directly with an identity store, such as a database or directory service.
  • Impersonation. The act of assuming a different identity on a temporary basis so that a different security context or set of credentials can be used to access a resource.
  • Message layer security. Represents an approach where all the information that is related to security is encapsulated in the message. In other words, with message layer security, the credentials are passed in the message.
  • Mutual authentication. This is a form of authentication where the client authenticates the server in addition to the server that authenticates the client.
  • Security token. .A set of claims used to prove the identity of a client. They contain an identifier for the client and a proof of the client's identity such as a password. They may also include information, such as a signature, to indicate that the issuer certifies the claims in the credential. Most security tokens will also contain additional information that is specific to the authentication broker that issued the token.
  • Service. A Web service that requires authentication.
  • Transport layer security. Represents an approach where security protection is enforced by lower level network communication protocols.
  • Trusted subsystem. This is a process where a trusted business identity is used to access a resource on behalf of the client. The identity could belong to a service account or it could be the identity of an application account created specifically for access to remote resources.

For a complete list of security terms used throughout this guidance, see the Glossary in the Appendix.

Common Scenarios

To familiarize you with the guidance provided by the decision matrices, this section introduces several common scenarios that illustrate Web service solutions. It provides some requirements for each scenario, and then extracts the key points from the relevant decision matrices that were used for deciding one approach over another. This approach should help you better understand how to use the decision matrices to determine appropriate solutions for your own requirements. The scenarios also aim to show how a series of patterns can be used together to increase the security of your Web applications.

The following four scenarios provide examples of common Web service interactions:

  • Public Web service. This scenario describes the decision criteria used to choose transport layer confidentiality with HTTPS and UsernameToken support in WSE 3.0 for authentication.
  • Intranet Web service. This scenario describes the decision criteria used to choose message layer security with the Kerberos protocol for an internal banking solution. It also provides a high-level description of the Kerberos design.
  • Internet business-to-business. This scenario describes a business-to-business solution that uses message layer security with the Kerberos protocol within the organization and X.509 certificates between businesses.
  • Multiple Internet Web services. This scenario describes the decision criteria used to choose a Security Token Service (STS) for a travel agency application that is accessible from the Internet. This section also describes how both direct authentication and brokered authentication are used to implement the solution.
Note   The scenarios are just examples to illustrate different security considerations as you navigate through the Web Service Security guide. They are not meant to represent the only way to implement these types of Web service solutions. Instead, they show you how information related to authentication, message protection, and protection scope can be used to navigate through the various patterns.

Each scenario starts with a high-level description of the application followed by a Web service profile that identifies the business requirements for the application. Some of these requirements are also included as security considerations in the solution approach.

Following the high-level description is a solution approach that examines factors related to the existing security infrastructure, organization security policies, and security threats that can lead to other security considerations. Each of these security considerations is categorized into three areas that directly relate to the chapter content in the Core Web Service Security Patterns part of this guidance.

The three categories and the chapters that they relate to are:

The security consideration related to each category is then used to navigate through the appropriate decision matrices in the introduction to each chapter.

The last section in each scenario identifies patterns that were used for the candidate solution and how the solution was implemented. Additional patterns that could have been considered as part of the solution are also identified.

Public Web Service Scenario

A large clothing distributor uses Web services to provide catalog information to merchants that provide online shopping services. The merchants access the Web service from their Web applications to display current items available from the distributor.

Figure 2 illustrates how the online merchants access the Web service.

Ff648381.intro_f02(en-us,PandP.10).gif

Figure 2. A distributor Web service

The following sections provide an overview of the distributor Web service requirements.

Distributor Web Service Profile

A distributor Web service has the following requirements:

  • The merchant Web application requires direct access to the distributor's Web service.
  • Merchants accessing the Web service must be authenticated.
  • Data passed between the merchant and distributor contains some information, such as merchant account information, that must be protected.

Solution Approach

Table 1 lists security factors that were considered for the distributor Web service and how each factor maps to a specific category.

Table 1. Distributor Web Service Factors

FactorSecurity considerationCategory
Security infrastructureMerchant accounts are stored in a custom database or directory service.Authentication
Security threatsMessage data is sensitive and must be protected against unauthorized access.Message Protection

The information in Table 1 is combined with business requirements related to security, and then it is grouped by category. Each category represents one or more decision matrices. The next step is to apply the security considerations to the appropriate matrices to make security decisions. In this example, you would examine the authentication decision matrices in Chapter 1, "Authentication Patterns," and the message protection decision matrix in Chapter 2, "Message Protection Patterns."

Table 2 provides a summary of the decisions that were made after applying the security considerations from Table 1, and the related business requirements to the appropriate decision matrices.

Table 2. Summary of Security Decisions

FactorSecurity considerationSecurity decision
Authentication Merchant accounts are stored in a custom database or directory service.UsernameToken can be used with custom authentication, Windows authentication or any other directory service that provides authentication.
AuthenticationMerchants accessing the Web service must be authenticated.UsernameToken provides the ability to authenticate the merchants.
Message Protection Message data is sensitive and must be protected against unauthorized access.HTTPS protects the message data while in transit between the merchant and distributor.

Candidate Solution

This solution uses the following patterns to implement direct authentication with UsernameToken and HTTPS to provide message protection:

Figure 3 illustrates the distributor Web service security solution.

Ff648381.intro_f03(en-us,PandP.10).gif

Figure 3. The security solution for a distributor Web service

The distributor Web service security solution is implemented in the following way:

  • The distributor Web service uses a server certificate to establish secure communications with the merchant Web application using HTTPS.
  • The merchant Web application passes a UsernameToken to the distributor Web service for authentication.
  • The UsernameToken information is used to authenticate the merchant Web application.
  • The distributor Web service uses a trusted subsystem to access catalog data.

Additional patterns that could have been considered include:

Intranet Web Service Scenario

A national bank uses Web services to provide operations that are accessed by an internal banking application. Figure 4 illustrates how the banking application accesses the Web service.

Ff648381.intro_f04(en-us,PandP.10).gif

Figure 4. An intranet banking application Web service

The banking application is a Windows client that directly accesses a Web service. The Web services access a bank account database for information. The following sections provide an overview of the banking application requirements.

Banking Application Profile

The banking application has the following features:

  • The banking application is used in bank branches.
  • The user of the application is a customer service representative (CSR).
  • The CSR must be authenticated as a valid user to use the banking application.
  • Banking regulations require that the account activities that the CSR performs must be audited.

Solution Approach

Table 3 lists factors that were considered for the banking intranet scenario and how each factor maps to a specific category.

Table 3. Intranet Banking Application Factors

FactorSecurity considerationCategory
Security infrastructureActive Directory is implemented on a computer running Microsoft Windows Server 2003.Authentication
Security infrastructureCSR users are located in Active Directory.Authentication
Organization security policiesMutual authentication is required for all Web service interactions.Authentication
Organization security policiesApplications must support single sign on (SSO) capabilities.Authentication
Security treatsMessage data is sensitive and must be protected against unauthorized access.Message Protection
Security treatsThe message must not be tampered with during transit.Protection Scope

The information in Table 3 is combined with business requirements related to security, and then it is grouped by category. Each category represents one or more decision matrices. The next step is to apply the security considerations to the appropriate matrices to make security decisions. In this example, you would examine the authentication decision matrices in Chapter 1, "Authentication Patterns," the message protection decision matrix in Chapter 2, "Message Protection Patterns," and the protection scope decision matrix in Chapter 3, "Implementing Transport and Message Layer Security."

Table 4 provides a summary of the decisions that were made after applying the security considerations from Table 3 and the related business requirements to the appropriate decision matrices.

Table 4. Summary of Security Decisions

CategorySecurity considerationSecurity decision
AuthenticationCSR users are located in Active Directory on a computer running Windows Server 2003.Active Directory supports the use of the Kerberos protocol.
AuthenticationApplications must support SSO capabilities.The Kerberos protocol provides support for SSO capabilities.
AuthenticationMutual authentication is required.Because the KerberosToken contains both requestor and service information, it can be used for mutual authentication.
AuthenticationAccount activities carried out by CSR users must be audited.The Kerberos protocol also supports impersonation and delegation, which means that auditing can be performed.
Message ProtectionMessage data is sensitive and must be protected against unauthorized access.The KerberosToken can be used to encrypt a message.
Protection ScopeThe message must not be tampered with during transit.The KerberosToken can be used to sign a message, which provides data integrity and data origin authentication.

Candidate Solution

This solution uses the following patterns to implement message layer security with the Kerberos protocol:

Figure 5 illustrates the intranet banking application security solution.

Ff648381.intro_f05(en-us,PandP.10).gif

Figure 5. The security solution for the intranet banking application Web service

The intranet banking security solution is implemented in the following way:

  • The user's credentials are used to obtain a security token from the Kerberos Key Distribution Center (KDC) implemented in Active Directory.
  • The security token is used to sign and encrypt messages sent to the service.
  • The security token is used to obtain additional information about the user from Active Directory.
  • Impersonation with delegation is used to access the database.
Note   For information about impersonation and constrained delegation, see Chapter 4, Resource Access Patterns.

Additional patterns that could have been considered include:

  • Exception Shielding in Chapter 5, "Service Boundary Protection Patterns."
  • Message Validator in Chapter 5, "Service Boundary Protection Patterns."

Internet Business-to-Business Scenario

A supply chain application uses internal Web services to perform operations. The internal Web services may need to access external Web services provided by another company. Figure 6 provides a high-level view of a procurement operation.

Ff648381.intro_f06(en-us,PandP.10).gif

Figure 6. A business-to-business supply chain management application

Figure 6 illustrates an operation where the supply chain application interacts with the procurement Web service through an intranet. The procurement Web service accesses an external ordering Web service over the Internet. The following sections provide an overview of the supply chain application requirements.

Supply Chain Management Application Profile

The supply chain management application has the following features:

The manufacturing company gets parts from a business partner.

  • Parts are ordered through an internal line-of-business supply chain management application.
  • Factory floor supervisors are the users of the application.
  • The application communicates with a procurement Web service that places orders with an ordering Web service hosted by the supplier. This way, only the two Web services have to agree on the external service contract.
  • The procurement Web service is one of a few other internal Web services that the supply chain management application uses. Maintaining an SSO user experience is an important requirement.

Solution Approach

There are actually two parts in this scenario to analyze: the intranet communication between the supply chain application and the procurement Web service, and the Internet communication between the procurement Web service and the ordering Web service.

Table 5 provides a list of factors considered for the Internet business-to-business scenario and how each factor maps to a specific category.

Table 5. Internet Business-to-Business Application Factors

FactorSecurity considerationCategory
Security infrastructureActive Directory is implemented on a computer running Windows Server 2003.Authentication
Security infrastructureApplication users are located in Active Directory.Authentication
Security infrastructureThe external Web service is hosted in an unknown environment.Authentication
Organization security policiesMutual authentication is required for all Web service interactions.Authentication
Organization security policiesApplications must support SSO capabilities.Authentication
Security treatsFactory parts and associated pricing information is sensitive. As a result, the data must be protected against unauthorized access.Message Protection
Security treatsThe message must not be tampered with during transit.Protection Scope

The information in Table 5 is combined with the business requirements related to security, and then it is grouped by category. Each category represents one or more decision matrices. The next step is to apply the security considerations to the appropriate matrices to make security decisions. In this example you would examine the authentication decision matrices in Chapter 1, "Authentication Patterns," the message protection decision matrix in Chapter 2, "Message Protection Patterns," and the protection scope decision matrix in Chapter 3, "Implementing Transport and Message Layer Security."

Table 6 provides a summary of the decisions that were made after applying the security considerations from Table 5 and the related business requirements to the appropriate decision matrices.

Table 6. Summary of Security Decisions

CategorySecurity considerationSecurity decision
AuthenticationSupply chain application users are located in Active Directory on a computer running Windows Server 2003.Within the intranet, the Kerberos protocol is supported by Active Directory.
AuthenticationApplications must support SSO capabilities.The Kerberos protocol provides support for SSO capabilities within the supply chain application intranet.
AuthenticationThe external Web service is hosted in an unknown environment.Interaction between the internal and external Web services does not require the credentials of the user. As a result, an alternate form of authentication can be used, such as message layer security with X.509 certificates.
AuthenticationThe external Web service is hosted in an unknown environment.X.509 certificates represent a well-known protocol that supports interoperability with other platforms.
AuthenticationMutual authentication is required.Both message layer security with the Kerberos protocol and message layer security with X.509 certificates support mutual authentication.
Message Protection Data must be protected against unauthorized access.Message layer security with the Kerberos protocol supports both data confidentiality and data origin authentication.

Message layer security with X.509 certificates also supports data confidentiality and data origin authentication.

Protection Scope The message must not be tampered with during transit.The KerberosToken can be used to sign a message, which provides data integrity and data origin authentication.

Candidate Solution

This solution uses the following patterns to implement message layer security with the Kerberos protocol in the intranet environment, and message layer security with X.509 certificates between the procurement Web service and the ordering Web service:

Figure 7 illustrates the security solution that was developed for the supply chain management application.

Ff648381.intro_f07(en-us,PandP.10).gif

Figure 7. The security solution for the supply chain management application

The supply chain management security solution is implemented in the following way:

  • The user's credentials are used to obtain a security token from the Kerberos KDC implemented in Active Directory.
  • The security token is used to sign and encrypt messages sent to the service.

The supplier's security solution is implemented in the following way:

  • X.509 certificates are issued and imported into appropriate certificate stores.
  • X.509 certificates are used to provide mutual authentication, data confidentiality, and data origin authentication for interactions between the procurement Web service and the ordering Web service.
  • A perimeter service router is used to accept requests from the supply chain application and send them to the ordering Web service.
Note   For information about configuring X.509 certificates, see the X.509 Technical Supplement in Chapter 7, "Technical Supplements."

Additional patterns which could have been considered include:

Multiple Internet Web Services Scenario

A travel booking franchise provides a Web application that travel agents can use to search for and book travel packages. The Web application uses several Web services to perform the operations of searching for and booking packages. Figure 8 illustrates a high-level view of the configuration.

Ff648381.intro_f08(en-us,PandP.10).gif

Figure 8. An Internet-based travel booking application

The travel booking Web application is accessible from the Internet. However, only the Web application can access the Web services that the application calls. Each Web service has an independent data store. The following sections provide an overview of the travel booking application requirements.

Travel Booking Application Profile

The travel booking application has the following features:

  • Travel agents in a travel franchise help customers book tour packages.
  • Two Web services are used: a travel packages Web service, and an online booking Web service.
  • The travel packages Web service provides travel product catalog information such as tour dates, itineraries, and prices.
  • The online booking Web service allows travel agents to book tour packages on behalf of the customers.
  • Identity propagation is needed for the online booking Web service because the database needs to keep a record of each travel agent who makes a travel request. Customers can go to any travel agent in the franchise to book a tour.
  • During peak travel seasons, user activity is high. This means that performance must be considered.

Solution Approach

Table 7 lists factors considered for the Internet-based travel booking scenario and how each factor maps to a specific category.

Table 7. Internet Travel Booking Application Factors

FactorSecurity considerationCategory
Security infrastructureTravel agent user accounts are stored in a database.Authentication
Security infrastructureServers used to host the Web services are behind a firewall.Protection Scope
Security infrastructureThe travel agent franchise does not have a PKI.Authentication
Organization security policiesMutual authentication is required for all Web service interactions.Authentication
Organization security policiesApplications must support SSO capabilities.Authentication
Security treatsThe online booking service handles sensitive data that must be protected against unauthorized access.Message Protection

The information in Table 7 is combined with the business requirements related to security, and then it is grouped by category. Each category represents one or more decision matrices. The next step is to apply the security considerations to the appropriate matrices to make security decisions. In this example, you would examine the authentication decision matrices in Chapter 1, "Authentication Patterns," the message protection decision matrix in Chapter 2, "Message Protection Patterns," and the protection scope decision matrix in Chapter 3, "Implementing Transport and Message Layer Security."

Table 8 provides a summary of the decisions that were made after applying the security considerations from Table 7 and the related business requirements to the appropriate decision matrices.

Table 8. Summary of Security Decisions

CategorySecurity considerationSecurity decision
Authentication Travel agent user accounts are stored in a database.When user credentials are stored in a database, Direct authentication is used to authenticate the user. To support SSO capabilities, Direct authentication can be combined with brokered authentication using a Security Token Service (STS).
AuthenticationMutual authentication is required.The use of a shared symmetric key with STS provides mutual authentication.
AuthenticationSSO support is required.The security token issued by an STS can be used to access multiple Web services.
AuthenticationPerformance must be considered.Brokered authentication speeds up operations when multiple Web services are accessed. In other words, authentication is performed only once. Encryption with a shared symmetric key is much faster than asymmetric methods. Only one of the Web services requires encryption.
Protection Level Sensitive data must be protected against unauthorized access.The security token issued by an STS can be used to provide data confidentiality and data origin authentication.
Protection Scope Web services are behind a firewall.Message layer protocols are easier to implement when passing through firewalls because additional ports do not need to be opened.

Solutions Description

This solution uses the following patterns to implement a combination of direct authentication and brokered authentication:

Direct authentication would be used to access a Security Token Service (STS) using WSE 3.0. The security token that is returned would then be used for brokered authentication against the Web services. The security token can also be used to provide data confidentiality and data origin authentication support as needed.

Figure 9 illustrates the security solution developed for the travel booking application.

Ff648381.intro_f09(en-us,PandP.10).gif

Figure 9. The security solution for the Internet-based travel booking application

The Internet travel booking security solution is implemented in the following way:

  • The STS uses a server certificate to establish secure communications with the travel booking Web application using HTTPS.
  • The travel booking Web application passes a UsernameToken to the STS for authentication.
  • The STS returns a security token for interaction with both the travel packages Web service and the online booking Web service.
  • Encryption is not required when accessing the travel package Web service. However, the STS security token is used to sign the messages to provide authentication.
  • The STS security token is used to sign and encrypt messages sent to the online booking Web service.
  • A trusted subsystem is used to access the product catalog and customer booking database.
  • Impersonation is not required for auditing. Instead, the agent's ID is retrieved from the security token and passed to the customer booking database as part of the request.

Additional patterns that could have been considered include:

patterns & practices Developer Center

Retired Content

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Show:
© 2014 Microsoft