Web Service Security Patterns - Community Technical Preview

Web Service Security

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

patterns & practices Developer Center

December 2005

Summary

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 hostile networks. To prepare you to meet these challenges (both now on Web Service Enhancements 3.0 and in the future with Windows Communication Foundation), patterns & practices has created the Web Service Security guide. This guide provides a scenario-driven approach to demonstrate where different security patterns are successful, combined with a series of decision matrices to assist you in applying your own criteria for using Web service security patterns in your environment.

Contents

Overview
Getting Started
Contents of this Guide
Community
Future Plans
Feedback and Support
Authors and Contributors
Related Titles

Overview

A considerable number of options are available to the architect and developer regarding Web service security. This guidance is designed in a modular fashion with patterns and technical supplements to help at all stages of the software development life cycle:

• Evaluation. Scenarios, matrices, and architectural patterns help you determine the right solutions for your environment.
• Design. Matrices, architectural, and design patterns assist you in making key design choices.
• Implementation. Composite patterns and implementation patterns provide in-depth implementation details, including code examples that you can customize to meet the needs of your own environment. Implementation patterns are provided for isolated challenges, and where appropriate, composite patterns organize critical patterns together.
• Deployment. Composite patterns and technical supplements provide additional information to help you understand critical challenges in the deployment life cycle.

Key topics of guidance in the Web Services Security guide 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, Kerberos version 5 protocol, and STS solutions.
• Protecting confidentiality of messages.
• Detecting tampered messages.
• Preventing the processing of replayed messages.
• Accessing remote resources and flowing identity across tiers.
• Preventing exceptions from revealing sensitive implementation details.
• Protecting Web services from malformed or malicious messages.

This guidance has been designed to assist individuals who are using Visual Studio 2005 and Web Service Enhancements (WSE) 3.0. It is also of significant use to architects and developers who plan to provide solutions using Windows Communication Foundation (WCF).

Common Scenarios

This guidance captures the most common scenarios related to securing Web services. Specifically, this guidance identifies four scenarios that share commonalities with the majority of Web services being built today. The four scenarios are:

• 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.

Figure 1 illustrates how authentication can be brokered between a service and its consumer using an STS.

Figure 1. Using a Security Token Service (STS) to obtain a security token

In addition to the scenario descriptions, this guidance provides the rationale and requirements analysis that illustrates how the solutions were chosen. This is the same approach that is recommended for production applications.

Scenario Considerations

To address common scenarios, a number of factors must be taken into account. Some of the factors considered in this guidance are:

• Data protection requirements. These include keeping messages confidential and safe from unintended tampering. Figure 2 illustrates how asymmetric encryption is performed. For more information, see the Data Confidentiality Design Pattern. For in-depth coverage of asymmetric encryption using X.509 certificates, see the X.509 PKI Technical Supplement.

  

  Figure 2. Public key data encryption and decryption

• Existing environmental infrastructure. This includes Public Key Infrastructure (PKI) and Active Directory.

• Credentials used to represent a subject. These include user names, passwords, and digital certificates.

Audience Requirements

This guidance is targeted at both developers and architects who may have varying degrees of expertise with distributed application design and application security. To get the most value from this content, you should have a basic understanding of distributed application development—specifically using Web services. Expertise in security is not required, however, in some cases the content refers you to other materials to become familiar with certain topics, such as threat modeling, which are beyond the scope of this guide.

Various roles within the development team will benefit from different sections of this guide. The architecture and design patterns provide guidance for architects who are responsible for designing secure Web services. The implementation patterns are intended for developers who are responsible for implementing secure Web services. Figure 3 illustrates a high level view of a subset of the patterns and the different types of authentication patterns that are intended for different audiences based on their role.

Figure 3. Brokered authentication patterns and references

Technical content, in addition to the patterns, is also included in this guide. Some of the technical prerequisites, such as familiarity with X.509 certificates, are included in technical supplements. Additionally, a number of the technical supplements provide information that is outside the scope of the patterns. It is not necessary to read these sections but they do provide valuable background information about specific topics.

Design Goals

Design and implementation patterns are the primary form of guidance for this content. Patterns describe a recurring problem that occurs in a particular situation and they recommend a solution. The solution is based on a set of conditions—called forces—that justify the use of the solution in the pattern. An important benefit to using patterns is that the design and architectural patterns are separated from the underlying implementation of the pattern. This means the pattern concepts are valid for existing technologies, such as WSE 3.0, and will remain relevant for future technologies, such as Windows Communication Foundation (formerly code-named "Indigo").

Patterns exist at different levels of abstraction, including:

• Architecture patterns. These patterns describe how to structure an application at the highest level.
• Design patterns. These patterns describe how to structure subsystems or components within a system.
• Implementation patterns. These patterns describe low-level implementations that are specific to a particular platform. In this guidance, the platform is the Microsoft .NET Framework and Web Services Enhancements 3.0.

For more information about a broader range of initiatives that relate to design patterns, see A Common Vocabulary for IT Professionals in the appendix.

Getting Started

To get the most from this guide, it is important to read the introduction first. It provides you with the necessary context for navigating the rest of the guide. You can navigate this guide in the following ways.

• Read it from start to finish. You will learn the most by doing this, but some of what you learn may not apply to the solutions you are building.
• Use the decision matrices. These exist in the chapter introductions and will help you refine your options to meet your security needs.
• Find a similar scenario. If your solution resembles one of the four scenarios described in the Introduction, you can start by reading the sections that apply to that scenario.

You may also be interested in the QuickStarts that are available from the community workspace. These allow you to walk through an executable version of the code described in the implementation patterns.

Contents of This Guide

This section provides links directly to chapters in this guide. If you would like to review this guide offline, or print it, you can download the PDF version of this guide by using the download links provided earlier.

Introduction

Read the Introduction first. It contains scenarios that might relate to your requirements. By reading the scenarios you will understand how requirements correlate to the patterns and other content. This section also provides an explanation of the guide as a whole.

Chapter 1: Authentication Patterns

This chapter provides architectural patterns for direct authentication and brokered authentication. It includes, three brokered authentication design patterns that illustrate authentication using the Kerberos protocol, X.509, and a Security Token Service (STS).

This chapter includes the following architectural and design patterns:

• Direct Authentication
• Brokered Authentication
• Brokered Authentication: Kerberos
• Brokered Authentication: X.509 PKI
• Brokered Authentication: Security Token Service (STS)

Chapter 2: Message Protection Patterns

This chapter provides design patterns for data confidentiality and data origin authentication.

This chapter includes the following design patterns:

• Data Confidentiality
• Data Origin Authentication

Chapter 3: Implementing Transport and Message Layer Security

This chapter builds on the first two chapters by demonstrating how you can implement the patterns described in those chapters using Microsoft technologies.

This chapter includes the following implementation patterns:

• Implementing Direct Authentication with UsernameToken in WSE 3.0
• Implementing Message Layer Security with Kerberos in WSE 3.0
• Implementing Message Layer Security with X.509 Certificates in WSE 3.0
• Implementing Message Layer Security with a Security Token Service (STS) in WSE 3.0

Chapter 4: Resource Access Patterns

This chapter contains the design pattern for trusted subsystem and information about protocol transition with constrained delegation.

This chapter includes the following design pattern:

• Trusted Subsystem

This chapter also includes the following technical supplement:

• Protocol Transition with Constrained Delegation Technical Supplement

Chapter 5: Service Boundary Protection Patterns

This chapter describes how to provide service boundary protection. It includes both design and implementation patterns that address message replay protection, message validation, and exception shielding.

This chapter includes the following design and implementation patterns:

• Message Replay Detection
• Implementing Message Replay Detection in WSE 3.0
• Message Validator
• Implementing Message Validation in WSE 3.0
• Exception Shielding
• Implementing Exception Shielding

Chapter 6: Service Deployment Patterns

This chapter includes a design pattern for a perimeter service router and an implementation pattern that shows how the perimeter service router can be implemented using Microsoft technologies.

This chapter includes the following design and implementation patterns:

• Perimeter Service Router
• Implementing Perimeter Service Router in WSE 3.0

Chapter 7: Technical Supplements

This chapter contains technical supplements for the Kerberos protocol and X.509 brokered authentication patterns.

This chapter includes the following technical supplements:

• Kerberos Technical Supplement for Windows
• X.509 Technical Supplement

Appendix

The appendix includes a problem/solution index, interoperability considerations when using WSE 3.0, information about the WSE 3.0 policy advisor, as well as a glossary.

This appendix includes the following topics:

• Problem/Solution Index
• WSE 3.0 Security: Interoperability Considerations
• Policy Advisor for WSE 3.0
• Patterns: A Common Vocabulary for Information Technology Professionals
• Glossary

Community

This set of patterns, like many patterns & practices deliverables, is associated with a community site. On this community site, you can post questions, provide feedback, or connect with other users to share ideas. Community members can also help Microsoft plan and test future patterns as well as download additional content, such as extensions and training material.

The community site offers this guide in CHM format as an alternative to the PDF format. It also offers QuickStarts that are associated with the implementation patterns in this guide. The implementation patterns contain source code, which is packaged in the form of executable QuickStarts.

Note   QuickStarts are not standalone deliverables from patterns & practices and should not be treated as such. QuickStarts are provided strictly for the purpose of illustration. They do not necessarily represent best practice guidance. QuickStarts have not undergone the same level of performance and security testing as other code-based deliverables from patterns & practices and should not be reused in the same way application blocks used.

Future Plans

Because the patterns in this guide are organized according to architecture, design, and implementation, it is not unreasonable for the implementation patterns to be rewritten in the future to use Windows Communication Foundation (WCF) in addition to WSE. There are not immediate plans to do this, but the patterns & practices team is considering it. If you would find this beneficial, please contact devfdback@microsoft.com with your requirements.

Web service security is a vast, complex topic, and this guide does not claim to provide 100% coverage of the subject. A wiki about Web service security patterns has been created for individuals who want to post new patterns or ideas for patterns that relate to Web service security.

An extension of this guide is in progress. It includes an implementation pattern and a QuickStart for a Security Token Service (STS) that issues XML Tokens based on the SAML v1.1 token format. To learn more about this project, go to the project's community workspace.

Feedback and Support

Questions? Comments? Suggestions? To provide feedback about this guidance, or to get help with any problems, go to the Web Service Security community site [Content link no longer available, original URL:https://go.microsoft.com/fwlink/?LinkId=57044]. The message board on the community site is the preferred feedback and support channel because it allows you to share your ideas, questions, and solutions with the entire community. Alternatively, you can send e-mail directly to the Microsoft patterns & practices team at devfdbck@microsoft.com, although we are unable to respond to every message.

Authors and Contributors

Thanks to the following individuals who assisted in the content development, QuickStart development, test, and documentation experience:

• Lead authors: Jason Hogg, Don Smith, Fred Chong, Microsoft Corporation; Dwayne Taylor, Lonnie Wall, RDA Corporation; and Paul Slater [Content link no longer available, original URL:http://blogs.wadeware.net/slater], Wadeware LLC.
• Contributing authors: Tom Hollander, Wojtek Kozaczynski, Microsoft Corporation.
• Test team: Larry Brader, Microsoft Corporation; Sajjad Nasir Imran, Mohanakrishan Shankar, Dhamotharan Bethanasamy, Subha Vaitheeswaran, Muralidharan C Narayanan, Venkat Narayan S., Sumit Baurai, Infosys Technologies Ltd.
• Development team: Diego Gonzalez, Pablo Cibraro, Ariel Szklarkiewicz, Lagash Systems SA.
• Pattern workshop facilitation: Ward Cunningham.
• Editors and graphic artist: Nelly Delgado, Microsoft Corporation; Sharon Smith, Linda Werner & Associates; Tina Burden McGrayne, Melissa Seymour, TinaTech Inc.; John Cobb, Wadeware LLC; Claudette Siroky, CI Design Studio.

Many thanks to the following individuals who provided invaluable feedback and assistance:

• External reviewers: Rudolph Araujo, Foundstone, Inc.; Scott Stender, Alex Stamos, Information Security Partners, LLC; Dr. Ivan Djordjevic, Security Research Centre, BT GCTO; David Mowers, Securitay, Inc.; Steve Stefanovich, RDA; Edward Bakker, LogicaCMG; Norman Headlam, Fidelity Investments; Jörg Bartholdt, Siemens AG; Anil John, Johns Hopkins University–Applied Physics Lab; Julia Lerman, The Data Farm; Keith Brown, Pluralsight; Vivek Vaid, Thoughtworks; Jason Ward; Munawar Hafiz, Patrick Delfert, University of Illinois at Urbana-Champaign; David Francis, HBOS Plc.
• Microsoft reviewers and contributors: Chris Keyser, Marc Goodner, David Trowbridge, Jonathan Wanagel, Mark Fussell, Jan Alexander, Sidd Shenoy, HongMei Ge, Tomasz Janczuk, David M. Bradley, Vijay Gajjala, Paul Leach, Hervey Wilson, Doug Walter, Martin Gudgin, Kannan C. Iyer, Heikki Ritvanen, J.D. Meier, Ron Jacobs, Doug Orange, Vittorio Bertocci, Kirk Allen Evans, Sam Keall, Vajira Weerasekera, Matt Deacon, Andy Gordon, Karthik Bhargavan, Cedric Fournet.
• Finally, thanks to Alan Ridlehoover, Blaine Wastell, Brad Wilson, Carlos Farre, Darrell Snow, Edward Jezierski, Edward Lafferty, Eugenio Pace, J.D. Meier, Ken Perilman, Michael Kropp, Mohammad Al-Sabt, Per Vonge Nielsen, Peter Provost, Rick Maguire, RoAnn Corbisier, Sanjeev Garg, Scott Densmore, Shaun Hayes, Srinath Vasireddy, Steve Elston, Vicky Titus, William Loeffler, Microsoft Corporation.

Related Titles

Integration Patterns

Enterprise Solution Patterns Using Microsoft .NET

WS-I Basic Security Profile Reference Implementation