.

NET StockTrader Technical Documentation Page 1

.NET StockTrader 6.1
Installation and Configuration
Reconfiguring .NET StockTrader and Configuration Service 6.1
Overview

6/1/2013
Microsoft Corporation 2013







THIS IS NOT A PRODUCT SPECIFICATION.
This document and related sample code supports Windows Server

2012, Windows Azure, Azure SQL Databases, Azure

AppFabric and the Microsoft .NET Framework 4.0 as a redistributable sample application kit.
The information contained in this document represents the current view of Microsoft Corp. on the issues disclosed as of
the date of publication. Because Microsoft must respond to changing market conditions, this document should not be
interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any
information presented. This document is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS
OR IMPLIED, IN THIS DOCUMENT.
Information in this document, including URL and other Internet Web site references, is subject to change without notice.
Unless otherwise noted, the companies, organizations, products, domain names, e-mail addresses, logos, people, places and
events depicted in examples herein are fictitious. No association with any real company, organization, product, domain name,
e-mail address, logo, person, place or event is intended or should be inferred. Complying with all applicable copyright laws is
the responsibility of the user. Microsoft grants you the right to reproduce this guide, in whole or in part.
Microsoft may have patents, patent applications, trademarks, copyrights or other intellectual property rights covering subject
matter in this document, except as expressly provided in any written license agreement from Microsoft, the furnishing of this
document does not give you any license to these patents, trademarks, copyrights or other intellectual property.
2012 Microsoft Corp. All rights reserved.
Microsoft, Windows Server, Windows Azure, SQL Azure, SQL Server, the Windows logo, Windows, Active Directory, Windows
Vista, Visual Studio, Internet Explorer, Windows Server System, Windows NT, Windows Mobile, Windows Media, Win32,
WinFX, Windows PowerShell, Hyper-V, and MSDN are trademarks of the Microsoft group of companies.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.
.NET StockTrader Configuration Page 1

Contents
Introduction to ConfigWeb ...................................................................................................................... 2
The Basic Deployment Options ................................................................................................................ 2
Remote Modes and Advanced Web Service Security ............................................................................... 4
Securing Business Services and Order Processor with Service Certificate and Custom Username
Validation ............................................................................................................................................ 4
Securing Order Processor with Service Certificate and Custom Client Certificate Validation ................. 4
Remote Modes and Interoperability ........................................................................................................ 4
Initial ConfigWeb Login and reconfiguration steps ................................................................................... 5
The Service Map View ....................................................................................................................... 38
Back to StockTrader as a User ................................................................................................................ 41
AppFabric Service Bus reconfiguration steps for async order processing ................................................ 41
AppFabric Service Bus reconfiguration steps for mobile notifications .................................................... 56
Caching ................................................................................................................................................. 59
Different HostsDifferent Configuration Repositories .......................................................................... 59
Monitoring Exception and Trace Logs .................................................................................................... 60
Azure Security Discussion and Changing the Security Configuration for WCF Endpoints ......................... 61
User Name Credentials ...................................................................................................................... 61
Where Does the User Name Come from and How is it Authenticated? .......................................... 62
How the User Name Gets Passed and Authenticated on Requests ................................................. 69
Changing Passwords so others Cannot Access Our Services ............................................................ 70
Client Certificate Credentials ............................................................................................................. 72
How the Client Certificate Gets Validated, and What Certificate is Valid as a Client Credential for the
StockTrader Business Services? ...................................................................................................... 82
Changing the StockTrader Web Application to Supply a Client Certificate to the StockTrader
Business Services. .......................................................................................................................... 84
Changing the Samples to Use Different Certificates vs. Default Install Certificates .......................... 97
New Hosts and Configuration Service Dynamic URI Management .......................................................... 97
Separation of Implementation from Schema and Contract .................................................................... 97
Why A Configuration Service and ConfigWeb? ....................................................................................... 98
Starting Point for Implementing the Configuration Service .................................................................... 99

.NET StockTrader Configuration Page 2

Introduction to ConfigWeb
This document provides the basic steps used to reconfigure the .NET StockTrader 6 using the
ConfigWeb management site. ConfigWeb is a separate Web application installed with .NET
StockTrader that can remotely attach to any service or application that implements the
Configuration Service 6.0. To access ConfigWeb, simply click on the ConfigWeb menu item within
the .NET StockTrader Web application (https://azureconfigweb6.cloudapp.net) or deploy your own
instance to Azure. The configuration system utilized by StockTrader is contained in separate base
classes and assemblies such that any developer, if desired, can implement the system in their own
applications or services to help manage distributed application configuration data, and achieve load
balancing and failover at the service operation level. A Visual Studio template and wizard is
provided, and you can read the related document Using the Configuration Service 6.0 Visual Studio
Template.
The Basic Deployment Options
When logging into ConfigWeb, you can directly specify an address to any of the core StockTrader
components that are running, including:
.NET StockTrader Web application
.NET StockTrader Business Services
.NET StockTrader Order Processor Service
These elements are initially configured on a default install to run within a single ASP.NET process,
without utilizing any remote services, although the tiers are still logically partitioned within the
host ASP.NET worker process. The relationships that can be changed look as follows (you can
explore all of these options using a single computer, as each service host is configured to utilize
separate ports):
.NET StockTrader Configuration Page 3


Additionally, the following deployment option is possible:


.NET StockTrader Configuration Page 4

Remote Modes and Advanced Web Service Security
In .NET StockTrader 6.0, two optional modes demonstrate WS-* security. Activating and using both
modes are illustrated in step-by-step procedures in a different document, see
http://msdn.microsoft.com/stocktrader for details. Neither of these modes is active by default for an
on-premise application. However, for the Azure deployment, one of these secure modes is always used.
Securing Business Services and Order Processor with Service Certificate and Custom
Username Validation
The first option demonstrates using an X.509 service certificate over a ws2007HttpBinding or
netTcpBinding with a security mode of TransportWithMessageCredentials. Client credentials are set to
Username (no certificate is required on the client; messages are encrypted within the transport layer),
and this mode demonstrates authenticating users using a custom username store, in this case directly
using the Configuration Service Users table to authenticate users connecting to the business service
layer (BSL). A base class provided within the Configuration Service does the validation, using the
standard .NET overrides (System.Security) to perform custom validation of the user name/password. By
default, this base class validates the incoming credentials against the Configuration Service Users table
(which is a convenient way to store such credentials for authentication); however this can easily be
replaced with other logic to use other credential stores such as Active Directory, custom LDAP stores,
etc.
Securing Order Processor with Service Certificate and Custom Client Certificate
Validation
The second option illustrates client credentials set to Certificate (service and client each require their
own X.509 certificate; client certificate is used for identification/authorization to the remote services).
The client certificate is validated using a custom certificate validator that checks the thumbprint of the
certificate, only allowing access to the secured endpoint for specific client certificates specified in the
validator class. The validator class, like the UserName validator, is provided as a base class with the
Configuration Service, using the standard .NET X.509 framework classes to do the validation.
Remote Modes and Interoperability
Several additional Connected Service definitions ship with the default install of .NET StockTrader 5.0 that
demonstrate interoperability with non-Microsoft platforms. Third-party elements are required for these
modes to operate:
.NET StockTrader ASP.NET Web Application and/or .NET StockTrader smart client to IBM
WebSphere 7.x Trade Business Service Layer over SOAP. This mode requires installation of IBM
WebSphere 7 with the Trade 7 sample installed. Note that the IBM WebSphere Trade 7 Java
Server Pages Web application can also be used seamlessly with the .NET middle tier services.
The Java-based Trade 7 application is included in the StockTrader download.
.NET StockTrader Configuration Page 5

Initial ConfigWeb Login and reconfiguration steps
To get started, we will use StockTrader to provide an overview of using the Configuration Service and
ConfigWeb for basic changes to the modes in which the composite application operate. Later, we will
reconfigure services for the advanced security modes.
Note that after the initial install of .NET StockTrader, the application is fully functional (operating in a no-
services mode as a standalone Web application); so you can already run the .NET StockTrader Web
application from the AzureStockTrader solution or from your Azure deployment before completing any
steps in this guide.
To deploy the application to Azure, compile and deploy the three Azure StockTrader solutions per the
AzureReadme file in the Windows Start menu. Make sure you deploy each to the correct Hosted Service
via the Windows Azure Management Console.
To reconfigure .NET StockTrader to use a remote service tier for the business service layer, log in to
ConfigWeb (https://azureconfigweb6.cloudapp.net/ or your own Azure config web deployment) by
pointing to the StockTrader Web application configuration service. You can login as username
localadmin, password admin. The drop-down selection (which can be customized) shows configuration
addresses for the StockTrader services and other samples included with the download, and the first
address listed is pre-specified to point to the .NET StockTrader Web application Configuration Service.
You can change the server name by deselecting Select from Known List, otherwise by default the server
hosting ConfigWeb will be listed.


Note
The login page for Azure ConfigWeb (as provided in your download and also as used at the link
above) has several preset logins that are selectable. These Azure addresses point to OUR
(Microsofts) hosted StockTrader application service domains. As you complete the following
sections, you will want to make sure to enter the addresses to YOUR StockTrader Hosted Services.
You can edit the Web.Config of the ConfigWebRole Visual Studio project (and/or your on-premise
ConfigWeb application), to change the default addresses that appear in this drop-down list, so they
point to your service domains for the various elements of your Azure StockTrader deployment vs. to
our hosted services. Then you will not have to enter addresses on every ConfigWeb login, or
accidently login to our services (which will only let you in as a demo administrator with no change
privileges). So, now might be a good time to do this, using the base DNS addresses of your Azure
service domains for the StockTrader Web Application, StockTrader Business Services and Order
Processor Service (the three separate Azure Hosted Services/deployments). Near the top of
Web.Config you will see the list, and you can substitute your DNS addresses for ours for each of the
three services. The ports and the client configurations will remain the same. Change the
information carefully.

.NET StockTrader Configuration Page 6


On login you will see the configuration home page, as follows:
.NET StockTrader Configuration Page 7


In the following steps, we will reconfigure the StockTrader Web application to connect to remote
Business Services, hosted in IIS. To do so, click on the Edit Configuration link for the StockTrader Web
application circled in the image above.
This will bring you to the main configuration settings for the StockTrader Web application. These are
depicted below. Settings are separated into three groupings: Basic, Detailed and Advanced.
.NET StockTrader Configuration Page 8



.NET StockTrader Configuration Page 9

Click on the Change Value link circled above for the AccessMode setting. You will next be able to update
the configuration to one of several different ways you can connect to remote Business Services. The
AccessMode setting determines which connection types to make active and utilize while users are using
the StockTrader Web application.
For now, we will change the setting to IIS-Hosted .NET 4.0 services, corresponding to a setting of Azure
BSL wsHttp security = TransportWithMessageCredential: ClientUserName, which you should select as
depicted. Note that note all modes are initially active. Also note that if you deploy the StockTrader
Business Services to Windows Azure, this is where you could link your on-premise StockTrader Web
application to cloud-hosted services on Azure.

.NET StockTrader Configuration Page 10

Click on the Update button to make the setting active. If your StockTrader Web application has been
deployed to many nodes, or is scaled out on Windows Azure, all nodes will be immediately synchronized
with the new setting.

Next, click on the menu item Configuration to return to the main ConfigWeb page:
Note
Remember that most of the endpoints shown above are not active by default, but they are loaded into the
configuration repositories so they can be activated later optionally, and the settings (AccessModes) pre-configured.
And not all endpoints can be hosted simultaneously by the same service host at the same time: for example, if the
security settings for the same protocol are different, one endpoint might have to be de-activated first before activating
the desired endpoint; and, a different Service Behavior applied to the service host hosting the endpoint. All of this can
be accomplished via ConfigWeb without programming, or redeployment, as shown later.
.NET StockTrader Configuration Page 11


You will notice that we now have Business Services (and Order Processor Service) no longer showing up
under the root StockTrader Web application, because all business services (and all connectivity to the
StockTrader application databases) are now set to be remotely activated by a separate business service
tier running in a different physical tier. However, there are no Remote Connected Services showing up
either. The .NET StockTrader Web application needs to be connected to a running instance of the
remote Business Services. To do so, you will first click on the Connected Services menu item to add an
initial connected service:
.NET StockTrader Configuration Page 12


Click on Add Service, and you will be presented with the option to provide the address of the business
service layer.
.NET StockTrader Configuration Page 13


Complete the address to the configuration service for the BSL. It should follow the format https://<my
bsl service >.cloudapp.net/config.svc. Then, select the Client_ConfigSvc_BasicHttpBInding_T_Security
client configuration name. Once complete, click Get Remote Services.
.NET StockTrader Configuration Page 14


Most of the default values will be correct. The only changes that need to be made are to check the
Apply Default UserName Client Credentials checkbox and to select azurebsloperationuser in the
combobox below. Once these updates have been made, click Add.
Now that the connected service has been added, you need to create an initial connection point. To do
so, you will click on the Connection menu item.
.NET StockTrader Configuration Page 15


Click on Add Connection, and you will be presented with a list of options of the different Business
Services you can connect to (these options are available because they have already been defined as
Connected Services in the StockTrader Web application repository):
.NET StockTrader Configuration Page 16


Select the option Azure BSL wsHttp security = TransportWithMessageCredential: ClientUserName.

Next, simply type in the address of the Azure BSL service (i.e. <your bsl service>.cloudapp.net). The
repository already stores the logical URI (path, port) information, so you just need the server name or IP
address here. Note you can always use the Azure Management Portal to find the base DNS address for
any of your Hosted Services if you forgot the address.
After clicking Add Connection, click on the Return button to go back to the Connections page:
Note
Later you can explore using ConfigWeb to change the endpoint to be the currently de-activated
endpoint using x.509 client certificates for client credentials, instead of username/password. Both are
just as secure, as long as going over https. These steps are documented later in this document.
.NET StockTrader Configuration Page 17


The active Connection Points will be highlighted in green.
You can now login to the actual StockTrader Web application at https://<your web app>.cloudapp.net/
or the StockTrader Web HTML 5 application (vs. ConfigWeb) as a registered site user, and now instead
of running business services within the same process as the ASP.NET Trade Web application (the user
interface tier), all activations are happening remotely to the separate Web application via WCF/Web
Services. Of course, you will not notice a difference as a StockTrader user in the StockTrader Web
application itself.
The next (optional) step to demonstrate further physical partitioning into distinct service layers will be
to configure the Business Services to also remotely invoke, on a third tier, order processing to occur via a
.NET StockTrader Configuration Page 18

separate service via a service-to-service interaction. To configure how orders are processed, you will be
configuring the StockTrader Business Service IIS Host, not the StockTrader Web application since the
Web application is blind to anything beyond the Business Service tier. This is where the connected
nature of the Configuration Service between service domains comes into play, using Linked Services.
Instead of logging out, you can select the Business Service tier directly, since the compositeadmin user
is also registered as an administrator of this remote service within its own repository.
Next, go back to the main page by clicking on the Configuration menu item and select the Business
Service tier as the top node within ConfigWeb, by clicking as indicated below:
.NET StockTrader Configuration Page 19


At this point, you are looking at the application from the Business Service tier down, as follows (the top
node is always on the left, with its remote services shown on the right, much like Windows folder
navigation):
.NET StockTrader Configuration Page 20


Now simply follow the same process completed for re-configuring the business services to be remotely
activated by the Web application, except this time you will be configuring the Business Service host to
remotely activate the Order Processor Service. This is done via the OrderMode and QuoteMode
configuration settings for business services. Click on the Edit link as circled above. You can now change
the required settings for business services:
.NET StockTrader Configuration Page 21


Business Services also has several different ways to connect to the Order Processor Service. For
submitting orders, we will connect via asynchronous net.tcp messages. Later, you can also activate the
Service Bus netMessagingBinding endpoint using ConfigWeb, and use it instead. You need to make sure
you have configured your Service Bus subscription before you do this. For requesting quotes, we will
connect via synchronous net.tcp messages.
.NET StockTrader Configuration Page 22


Select OrderMode.
Choose the Azure OPS netTcp security = TransportWithMessageCredential: ClientUserName.
Click the Update button to change the configuration to this remote mode. Return to the
configuration page.
.NET StockTrader Configuration Page 23


Select QuoteMode.
Choose the Azure QS netTcp security = TransportWithMessageCredential: ClientUserName
Click the Update button to change the configuration to this remote mode.


.NET StockTrader Configuration Page 24

At this point, you are ready to add two connected services from the Business Services layer to the
running remote Order Processor Service. To do so, you will go back to the Connected Services page:

Provide the address to the OPS (it will be in the format net.tcp://<your ops
address>.cloudapp.net:11003/orders/config) and select the
Client_ConfigSvc_TcpBinding_T_Security_OPS client configuration. Then click Get Remote Services!.
.NET StockTrader Configuration Page 25


Most of the default values will be correct to establish a connection to the order service. Check the
Apply Default UserName Client Credentials checkbox and select azureopsoperationuser from the
combobox below. Once complete, click Add.
.NET StockTrader Configuration Page 26


Next, return to the Connected Services page to add the connection to the quote service. Complete the
same address to the configuration service and client configuration option and retrieve the remote
services. Again, most of the default values will be correct. Check the Apply Default UserName Client
Credentials checkbox and select azureopsoperationuser from the combobox below. Once complete,
click Add.
.NET StockTrader Configuration Page 27


Once both connected services are created, we need to establish initial connections. To do so, in
ConfigWeb you will go back to the Connections page:
.NET StockTrader Configuration Page 28


You are now at the Connections page for the Web application, but via the inter-connected nature of the
configuration services, we can directly drill-down into the .NET StockTrader Business Services IIS Host
connections from here, by clicking on the link as circled above.
Click on the Add Connection button in this page, and you will see the connection options for business
services to connect to the remote Order Processor Service. First, choose the Azure OPS netTcp security
= TransportWithMessageCredential: ClientUserName to establish the connection to the order service.
.NET StockTrader Configuration Page 29


Enter the address of the Order Processor Service. Again, you just need a DNS name here, since the
Business Service Host repository already has a Connected Service Definition to this endpoint that holds
the logical URI information (path and port).
Click the Add Connection button.
Next, perform the same operation to establish the connection to the quote service. Select Azure QS
netTcp security = TransportWithMessageCredential: ClientUserName and provide the same address.
Then click the Add Connection button.
You can now click on the Return button to go back to see the active connections. Note if you click on
the Connections menu tab instead, you will be positioned back at the StockTrader Web application and
will need to drill down again to see Business Services connections.
Finally, click on the Configuration menu item to go back to the main ConfigWeb home page. Initially,
you will be re-positioned with the Web Application as the top node.
.NET StockTrader Configuration Page 30


You can now select business services as the root node, by clicking where circled above. Business
services will be shown on the left, with its newly added connections to the Order Processor Service.
.NET StockTrader Configuration Page 31


You can now select order processor services as the root node, by click where circled above. The next
step is to configure a connection from the order processor back to the business service. Orders are
placed over a one-way channel; this connection is required to allow the order processor to inform the
business service layer when the orders have been processed successfully. This asynchronous design
enables reliable/disconnected messaging (e.g. Service Bus).
.NET StockTrader Configuration Page 32


First navigate to the order processor configuration by clicking the link as circled above.
.NET StockTrader Configuration Page 33


Select Change Value for the OrderResponseMode property. The default value is In-Process Activation;
now that we are running in remote mode, we need to update this to an appropriate connection.
.NET StockTrader Configuration Page 34


Select Azure ORS netTcp security = TransportWithMessageCredential: ClientUserName. You can also
use Service Bus here if you have completed the required configuration steps (Azure ORS netMessaging).
Next, click Update.
Once the update is complete, click Return to Configuration Page, followed by Return to Home Page.
Using these links will keep you in the context of the Order Processor Service.
.NET StockTrader Configuration Page 35


From the home page for the Order Processor Service, click on Connected Services.
Click Add Service. Then, provide the address of the Business Service configuration service (it will be in
the format of https://<your BSL address>.cloudapp.net/config.svc). Select
Client_ConfigSvc_BasicHttpBinding_T_Security as the Client Configuration Name and then click Get
Remote Services!
.NET StockTrader Configuration Page 36


Once the services have been retrieved, select:
Remote Endpoint: Azure ORS wsHttp security = TransportWithMessageCredential:
ClientUserName
Client Contract: Trade.OrderProcessorContract.IOrderProcessorResponse.
Client Configuration:
Client_Ws2007HttpBinding_T_Security_MCredential_ClientUserName_ORS.
Apply Default UserName Client Credentials: checked
User for Default Client UserName Credentials: azurebsloperationuser.
Once complete, press Add. Once the connected service has been added, click on Return to Connected
Services List, followed by Return to Home Page.
.NET StockTrader Configuration Page 37


Next, create the initial connection by selecting Connection Points. Make sure you are still in the context
of the Order Processor Service (as can be seen in the center of the above image).
On the connection points page, click Add Connection.
.NET StockTrader Configuration Page 38


Select the ORS service as above and enter the address to the Business Service.
Click Add Connection.
The Service Map View
The Service Map will display the entire physical topology of connected services making up an
application, including all clustered servers each virtual service host is running on. You can bring up the
Service Map by clicking on the button as shown below:

.NET StockTrader Configuration Page 39


You will see the following:
.NET StockTrader Configuration Page 40


You can see the three-tiered nature of the deployment (plus Azure SQL Databases). Note you can
expand any node to view its individual endpoints. Also, hover over icons to see additional information
the Configuration Service gathers. This view gives a near-instantaneous read on the online offline status
of clustered servers and their individual service endpoints, for an entire composite application. Green
icons indicate online, red, offline. If an icon shows as red, hover over it to view the exception message.
If other clustered service nodes are started (for any tier in the application: Web; Business Services;
Order Processor Service), they will be populated in the view above as new clustered nodes for the
virtualized service. The Configuration Service is automatically providing this clustering/load balancing.
In the diagram above, only one server node shows for each tier, since each tier is only running on one
server (the same local PC). You can use AutoRefresh to poll every few seconds for updates
automatically; and Endpoint Detail to see the actual URI information vs. the established friendly
names stored/defined in the configuration repository for each host.
When you hover over the domain/virtual host (or an individual node), you will see how many service
requests have been serviced. These are set to persist for each node on 60 second intervals, to keep
accurate over time even as nodes are added, subtracted, taken offline, restarted, etc. The 60 second
persist interval can be adjusted in ConfigWeb, its another Configuration Setting managed by the
Configuration Service.
Note by default the Configuration Service is counting all activations of the primary service class; this
count is accurate since the service is set to activate per call. Also note that visiting one StockTrader Web
.NET StockTrader Configuration Page 41

page actually involves multiple remote service calls, not just one per page. So as you click around a few
pages as a user in the StockTrader web application itself, you will see many more service requests by the
BSL service than pages you actually visited. Each individual request is being tracked. For the Web
application, we have the request tracker set to just track valid logins, not all page visits.
Back to StockTrader as a User
Now you can log into the StockTrader Web application as a user of the composite application (vs.
administrator using ConfigWeb) and try placing a buy order. This will now be processed by the remote
OPS service, asynchronously.
Later in this document there are optional steps to use the Service Bus endpoint instead for placing
orders with a durable message queue.
AppFabric Service Bus reconfiguration steps for async order
processing
AppFabric Service Bus provides durable and asynchronous cloud-based messaging components, such as
queues, topics and subscriptions. From the perspective of StockTrader and its WCF foundations, this
communication technology simply manifests itself as another one-way WCF binding (like net.msmq).
StockTrader can be reconfigured so that the Business Service layer communicates with the Order
Processor Service via Service Bus. This allows both parties to ensure that business-critical trade orders
are reliably delivered regardless of the availability of either component. To accomplish this, existing
hosted services will be deactivated (along with any connections) and new services will be created that
use the Service Bus binding. Before starting, make sure you follow the directions in the StockTrader
readme file that describe setting up your Service Bus namespace.
.NET StockTrader Configuration Page 42


To get started, login to the ConfigWeb and connect to the Business Services layer. Navigate to the
Hosted Services tab and view the endpoints associated with the TradeServiceBSLResponse service.
.NET StockTrader Configuration Page 43


Edit the configuration for the active HTTPS endpoint by clicking on the edit link.
.NET StockTrader Configuration Page 44


We need to deactivate this endpoint so we can replace it with a Service Bus-based endpoint. Scroll to
the bottom of the page and uncheck the Activate Endpoint checkbox and click Update. Then click on the
Return to Hosted Services for this Virtual Host link.
.NET StockTrader Configuration Page 45


Next, click on the Edit link for the Service Bus IOrderProcessorResponse endpoint (Azure ORS
netMessaging). This endpoint connects to a response topic that the Order Processor Service will use to
communicate trade outcomes to the business service layer.
.NET StockTrader Configuration Page 46


To activate the endpoint, first update the Virtual Path field to the absolute URI of the service bus
subscription. Assuming you are following the suggested naming scheme, just replace the ? in the URI
with your Service Bus namespace. The resulting URI should look something like:
sb://<your_namespace>.servicebus.windows.net/orderprocessorresponse/Subscriptions/bsl
Once youve updated the virtual path, check the Activate Endpoint check box and press Update.
.NET StockTrader Configuration Page 47


Next, navigate to the Connected Services tab and edit the connection to the Order Processor Service
net.tcp IOrderProcessor service.

.NET StockTrader Configuration Page 48

We need to remove this connection so we can replace it with a Service Bus-based endpoint. Scroll to the
bottom of the page and click Delete.
The same steps need to be performed on the Order Processor Service (but for different services):
Using ConfigWeb, connect to the Order Processor Service.
Navigate to the Hosted Services tab and edit the OrderProcessor service.
o Click on the Edit link for the active net.tcp IOrderProcessor endpoint.
o Scroll to the bottom of the page and uncheck the Activate Endpoint checkbox.
o Click Update and then click Return to Hosted Services for this Virtual Host.
o Click on the Edit link for the inactive netMessaging IOrderProcessor endpoint. This is the
endpoint used by the Business Service to place orders.
o Update the Virtual Path property. If youre using the suggested naming scheme, then
just replace the ? with your namespace. The resulting URI should look like
sb://<your_namespace>.servicebus.windows.net/orderprocessorrequest.
o Scroll to the bottom of the page and check the Activate Endpoint checkbox.
o Click Update.
Navigate to the Connected Services tab and edit the wsHttp IOrderProcessorResponse endpoint.
o Scroll to the bottom of the page and click Delete.
The next step is to create new connections between the Business Service and Order Processor Service.

.NET StockTrader Configuration Page 49

Using ConfigWeb, connect to the Business Service and select the Connected Services tab. Next, click on
Add Service to begin the connection process.

Enter the address to the Order Processor Service config service in the Address to Configuration Service
field, change the Client Configuration Name to Client_ConfigSvc_TcpBinding_T_Security_OPS and then
click Get Remote Services!
.NET StockTrader Configuration Page 50


Select the Azure OPS netMessaging endpoint from Available Remote Endpoints. Leave the rest of the
values as their defaults. Once complete, click Add.
.NET StockTrader Configuration Page 51


Next, we need to add a connection to this service. Click on the Connections tab and press Add
Connection.
.NET StockTrader Configuration Page 52


Enter the base DNS address of the Order Processor Service and click Add Connection.
.NET StockTrader Configuration Page 53


Finally for the Business Service we need to update its configuration to use the new connection. Click
on the Configuration tab and then click on the Edit Custom Settings link.
.NET StockTrader Configuration Page 54


Click on the Change Value link for the OrderMode setting. This value is used by the Business Service
layer to determine which connection type to use to connect to the Order Processor Service.
.NET StockTrader Configuration Page 55


From the radio buttons, select Azure OPS netMessaging and then click Update.
The same steps need to be performed on the Order Processor Service (but for different services):
Using ConfigWeb, connect to the Order Processor Service.
Navigate to the Connected Services tab and create the netMessaging endpoint.
o Click on Add Service.
o Enter the address of the Business Service configuration service in the Address field.
.NET StockTrader Configuration Page 56

o Select Client_ConfigSvc_BasicHttpBinding_T_Security for the Client Configuration
Name.
o Click Get Remote Services!
o Select Azure ORS netMessaging from the Available Remote Endpoints.
o Click Add.
Navigate to the Connections tab and create a connection to the new endpoint.
o Click Add Connection.
o Enter the Business Service DNS address into the Base DNS Address to the Remote Host
field.
o Click Add Connection.
Navigate to the Configuration tab and update the configuration to use the new connection.
o Click Edit Custom Settings.
o Click Change Value for the OrderResponseMode setting.
o From the radio buttons, select Azure ORS netMessaging.
o Click Update.
All of the necessary steps to reconfigure StockTrader to use Service Bus are now complete. Log into the
StockTrader web application to place an order and validate the configuration.
AppFabric Service Bus reconfiguration steps for mobile
notifications
StockTrader 6.0 uses the AppFabric Service Bus to communicate with rich mobile clients. Clients create a
subscription on initial startup to a Service Bus topic and regularly check their subscription while running.
This allows urgent news notifications to be pushed to running clients (using the console client).
To configure the BSL to support this functionality, it needs to be configured with the credentials for the
Service Bus namespace.
To get started, login to the ConfigWeb and connect to the Business Services layer.
.NET StockTrader Configuration Page 57


Navigate to the Configuration tab and select Edit Custom Settings for the Selected Service Domain.
.NET StockTrader Configuration Page 58


Click on the Detailed button to bring up the correct settings. We need to update the three highlighted
settings:
1. NewsNamespace: specify the Service Bus namespace you created as part of the Readme steps
to configure Service Bus.
2. NewsTopic: leave this as news (unless you have a name conflict in your environment).
.NET StockTrader Configuration Page 59

3. NewsManagementSecret: specify the issuer key for the Service Bus namespace (as recorded
during the Readme steps).
Once these three settings have been updated, the BSL is ready to issue new subscriptions to devices.
Caching
Caching is often an essential component of highly scalable and well performing web applications.
StockTrader does not include a caching tier given its origins in database performance testing; however,
in its latest release, some targeted caching has been added.
The market index query requires the system to retrieve the current price of quotes s:100 s:199. While
this is not an expensive operation for normal databases, it can be when using Federations with a large
number of members. For example, in a 64 member federation, it may take up to 64 queries to retrieve
the necessary information (if the quotes are distributed throughout the federation members). To reduce
the performance impact of this query, this service operation will check the cache before performing the
query. Additionally, a background processing thread on one of the role instances will refresh the cached
value on a periodic basis. This approach not only improves performance but also eliminates a potential
denial of service risk (where a relatively cheap HTTP call triggers a disproportionally large server
operation). Other database operations are typically limited to a single federation member and thus do
not gain as great of a benefit from caching.
To configure caching:
1. Add a caching role to the Azure project that will host the OPS (i.e. if the OPS is running in its own
Azure environment, then add the caching project to the OPS Azure project; however, if the OPS
is running in-proc in the web or BSL tier, then add the caching project role to the host Azure
project).
2. Re-deploy the updated Azure project.
3. Log into the Config Web for the OPS (either direct to the OPS if running standalone or via the
host service if running in-proc).
4. Open the Configuration page and set the CacheRefresherEnabled property to true. Azure
caching auto discovery will be used by the OPS to connect to the new cache.
Different HostsDifferent Configuration Repositories
It is very important to keep in mind that the configuration repositories are specific to the service host
hosting the services. Making changes to settings for one service host will not affect the other service
hostthey are physically distinct. When you are running business services in-process
(AccessMode=InProcess) with the Web application, and you edit the business services configuration
directly, you will be effecting the Business Service Repository only, based on the way the in-process
mode is initially configured.
.NET StockTrader Configuration Page 60

Monitoring Exception and Trace Logs
Configuration 6.0 allows any application or service to log exception and/or trace information to a
logging database. You can then use ConfigWeb to view these logs.

Please note that information is also sent to each nodes Event Log as setup in the ConfigWeb as an
application-level setting. The log is very important for understanding issues, including exceptions
your application might have. For WCF services, a Fault Behavior is automatically applied, so you do
.NET StockTrader Configuration Page 61

not actually have to write code to log exceptions, it all happens automatically. However, you can
also write to the log using the ConfigurationUtility writeConfigConsoleMessage method.
You can view rich tracing information for Configuration Service 6.0 by turning on Detailed Logging
and/or Log Node Notifications. This is a setting for each service domain in ConfigWeb. For
performance reasons, you should keep detailed logging off for production applications.
Azure Security Discussion and Changing the Security
Configuration for WCF Endpoints

User Name Credentials
On install the StockTrader Web application, Business Services and Order Processor use no security
for the on-premise installation. However, if you deploy the Azure projects, security is enabled by
default, using User Name client credentials. The on-premise elements can be reconfigured to
these same secure modes as well, optionally, via ConfigWeb. In this section we will discuss this
topic, and show how it works. Later we will walk through some steps for the Azure hosted version
to change the security from User Name credentials to Client Certificate credentials.
WCF supports a wide variety of security modes. Azure StockTrader uses https/ssl for the Web
application to protect http transmissions, since these over-the-wire transmissions include the
users personal stock data, passwords for sign on, etc. While the StockTrader Web application
authenticates the user logins via a custom Account table in the StockTrader database, the
StockTrader Businesses services and Order Processor Service do not implement their own
independent authentication (although they could be changed to authenticate every request with
custom logic). So, to lock-down these internet-exposed service endpoints, we are using WCF
security. This ensures that only the StockTrader Web application itself can access the BSL tier, and
only the BSL tier can access the OPS tier to submit orders. We are doing so with WCF security set
to TransportWithMessageCredentials. So, all communication is over https/ssl to protect the
content of the messages over-the-wire; and additionally the client must send client credentials that
the WCF infrastructure automatically examines before it allows a service operation to be invoked.
A Service Certificate (X.509) is used (and configured on the WCF services) in this configuration, both
for the Business Service tier which operates over https/ssl; and for the Order Processor which
operates over net.tcp.
By default, the client credentials are configured as User Name client credentials, which means on
each service request to the BSL, for example, from the Web application, the Web application has to
send a userid/password that WCF then authenticates on the service side. This is independent of
how the StockTrader Web application uses ASP.NET Forms authentication to authenticate
individual registered users of the application via the login page. Rather, the StockTrader Web
application uses a global username/password much like applications use a username password (in
.NET StockTrader Configuration Page 62

the ADO.NET connection string) to connect to a database.

Where Does the User Name Come from and How is it Authenticated?
The username/password the StockTrader Web application supplies on each request to the Business
Services tier is stored in the Configuration database, and can be configured via ConfigWeb. When
establishing Connected Service Definitions, checking off Supply Default Username Credentials allows
you to specify which username/password is used. You can create new user ids, or change the passwords
on the ones already loaded using the Users menu item in ConfigWeb. If you have everything working on
Azure in remote modes, you can test the security by using the Users page to change the password for
the azurebusinessserviceopsuser user (here ops means service operations: ops). If you change the
password for this user, which is defined in both the StockTrader configuration database and the
Business Service database, on either tier so they do not match, all requests will be rejected by the BSL
that come from the StockTrader Web application (until you make them match again). So you can test
this out now using ConfigWeb as follows:
Login to the StockTrader Web Application configuration service via ConfigWeb.
.NET StockTrader Configuration Page 63


Click on the CS Users button.
.NET StockTrader Configuration Page 64



Select the Edit link for the azurebsloperationuser user.
.NET StockTrader Configuration Page 65


Change the password to test. The BSL service host will still expect azurebsluser#1 as the
password. So this will break the Azure deployment by creating a security violation (on purpose!)
after changing the password above and clicking Update.

Click on the Connections menu item.
.NET StockTrader Configuration Page 66


Immediately you will notice the connection shows up as red. You can hover over it to see the
security exception message. More detailed exception information is always logged and
viewable in the Service Logs page.

Try to login as an end-user to the StockTrader Web application (make sure you are running in
remote mode as configured in the previous section). You will not be able to.
.NET StockTrader Configuration Page 67



You can repeat this test for the Business Service tier with respect to its client credentials
supplied to the Order Processor Service. If you change these so they do not match what is
expected by the OPS (which uses the same mechanism for authentication), you will be able to
log into the StockTrader Web application as a registered user, but not place trade orders.

Also if you were to change the Connected Service Definition (for either the StockTrader Web
application-to-BSL definition or the Business Service tier-to Order Processor Service) to uncheck
the checkbox Apply Default UserName Client Credentials, the StockTrader Web application will be
unable to make remote service requests to the BSL (or BSL to OPS, depending on which one you
change for the respective service domain).

.NET StockTrader Configuration Page 68


If, in ConfigWeb, you now go back to the Service Logs page (Trace and Error Logs), you will see the
following exception after the login attempt above:


.NET StockTrader Configuration Page 69

Now in ConfigWeb, change the password back to the default of azurebsluser#1. Refresh
the connections page, and try the Login for the StockTrader Web application again. All will be
well again.

Note that you could also perform this test by configuring the Business Services tier, and
changing the password for this same user id via ConfigWeb for this tier, as opposed to the client
Web application tier. The client credentials must match BSL-authenticated credentials.

How the User Name Gets Passed and Authenticated on Requests
The base client class for Configuration Service will automatically supply the client username credentials
selected when you first create the Service Definition: *but only if the client configuration name selected
includes T_Security indicating transport security is applied on the binding, see the Configuration
Service Technical Guide for details. You would never want to pass username/passwords over
unencrypted channels.
The Business Services tier has a special WCF behavior applied to the Primary Service Host, named
BSL_M_Security_UserName_Behavior. This service behavior tells the service to require
username credentials on each service request. In turn, the behavior definition, which is contained in the
Web.config file, tells WCF to use a custom username validator class to authenticate the usernames on
each request. In the behavior definition within Web.config, the configuration tells WCF the name of the
assembly, and the class to use within this assembly as follows:
<userNameAuthentication userNamePasswordValidationMode="Custom" cacheLogonTokens="true"
customUserNamePasswordValidatorType="Trade.BusinessServiceImplementation.CustomUserNameValidator,
Trade.BusinessServiceImplementation"/>
This class is the CustomUserNameValidator class in the BSLCustomCertValidator.cs file within the
BusinessServiceImplementation project (its used whether running on-premise or on Azure when
configured for this mode). If you open this class and look at this class (which also contains the custom
certificate validator logic, discussed later), you will find the following class definition:
public class CustomUserNameValidator : ConfigService.CustomValidators.CustomUserNameValidator
{
public override void Validate(string userName, string password)
{
base.Validate(userName, password);
}
}

Its very simple, because it inherits from a base class the Configuration Service 5.0 provides. This base
class uses the standard .NET framework System.Security assembly to perform the validation on the
service-side. The logic provided in the base class by Configuration Service 5 uses the Users table within
the services configuration database, looking for a valid matching user that has at least Service
Operation Rights. This method is automatically invoked on service requests as they come in from
clients. The Configuration Service can perform the validation very quickly, since it maintains an in-
.NET StockTrader Configuration Page 70

memory cache of its username/passwords from the Users table, and this is always kept synchronized
with the database as long as updates flow through the Configuration Service itself (which ConfigWeb
always uses). The base class looks like this, and is contained in the \configuration\ CustomValidators
project within the Configuration Service Visual Studio solution:

/// <summary>
/// Note how this class is tied in via a ServiceBehavior, defined in config, to override default
Windows auth validation.
/// </summary>
public abstract class CustomUserNameValidator : UserNamePasswordValidator
{
/// <summary>
/// Overrides to instead validate the username/password against the Configuration DB Users table.
/// </summary>
/// <param name="userName">User id coming in as UserName credentials from client.</param>
/// <param name="password">Password coming in as UserName credentials from client.</param>
public override void Validate(string userName, string password)
{
ServiceConfigHelper configHelper = new
ServiceConfigHelper(ServiceConfigHelper.MasterServiceSelfHost._settingsInstance);
ServiceUsers csUser = new ServiceUsers();
csUser.UserId = userName;
csUser.Password = password;
//All we need to do is make this call, which validates the user for operation rights.
if (userName.ToLower().Equals("demoadmin") || !(configHelper.setServiceRights(ref csUser,
ConfigUtility.CONFIG_SERVICE_OPERATION_RIGHTS) >= ConfigUtility.CONFIG_SERVICE_OPERATION_RIGHTS))
throw new SecurityTokenValidationException("The operation failed authentication with the
username/password provided.");

}
}

Note we have a special user demoadmin setup that lets people browse ConfigWeb for our Azure
deployment, but not change any configuration for the deployment. We explicitly disallow this user from
using this ID to invoke service operations on the BSL and OPS tiers.
By throwing a security exception if the username/password supplied by the client does not match the
required rights for the service, the service operation is automatically rejected by WCF. You could
replace this base class implementation (or use the override method in the Business Service
implementation) to do your own validation: for example against an Active Directory or other directory
service, or against your own users database. Just remember that using the Configuration Service will be
fast, since no database or network call needs to take place on validation of each service operation from
the client (which, under load, might be coming in at thousands of times per second).
Changing Passwords so others Cannot Access Our Services
Locking down your specific deployment of StockTrader is pretty straightforward. You simply need to use
the ConfigWeb Users menu to change all the passwords to the various accounts (users) defined there.
Just remember the following rules:
Linked services will break if the root login credentials for ConfigWeb do not match the service you are
trying to Select in the right hand connected services table in ConfigWeb home page. The link will
simply show Not Selectable. So, for example, if you change the localadmin password to the Web
.NET StockTrader Configuration Page 71

application, and then login to ConfigWeb when running in remote mode (AccessMode set to anything
but In-Process Activation), you will not be able to Select and configure the Business Services from that
login session. Instead, you would have to login to the Business Services tier directly as a different
ConfigWeb login, using its old localadmin password, to configure it. The localadmin password is the
same on install for all StockTrader service domains; so linked services just work; but really each service
domain should have its own unique password.
Think of the localadmin user akin to an sa user on SQL Server. It always has to be there and cannot be
deleted, as its the master administrator for that service domain. So you might want to make unique
passwords for each domain. And if you do, there is another administrator ID setup named
Compositeadmin, and this one is set up to use for linked services. If you make each service domains
localadmin password unique, but keep the same password for Compositeadmin across service
domains, then when you login to ConfigWeb as Compositeadmin, you will see and be able to select and
configure remote services; but when logging in as localadmin, you will only be able to configure the
root service you logged into.
Also, while you cannot Select remote connected services in ConfigWeb if the credentials do not match,
you should note that every service operation is authenticated by the remote service always, so even if
you could select it (you could modify the browser URL, for example, to make a request, or do so
programmatically as a web service call); you will not get anything back from the remote service, since
your request will fail authentication.
So in summary, to lock down your Azure-hosted (or on-premise) install of StockTrader and all its service
domains, simply change all the passwords for each user, keeping the following in mind:
csUser credentials must match. Whenever you see a user with cs in the username, this is either
a local Connected Service (hence cs) user for the hosted service, which it doles out to
subscribing client to subscribe to notifications; or its a non-local user that a client application is
using to subscribe to host notifications. So you should make sure that username has the same
password everywhere it appears; otherwise, like ADO.NET, if you change the password on the
service (akin to changing a login password on SQL Server); then client apps using these
credentials will fail authentication because they are using the old password (like an ADO.NET
connection string using an old passwordthe application can no longer connect).

The Service Operation user credentials also must match, as shown in the previous section,
between client and the remote service it is passing these credentials to for authentication.

For linked services to work, you must create some administrator credentials that are shared
between client and remote connected service. You are free to create other admin usernames;
but CompositeAdmin is setup for this purpose.
.NET StockTrader Configuration Page 72

Client Certificate Credentials
The StockTrader sample (both for Azure and .NET-on premise deployments) also has support for using
Client Certificate Credentials instead of the default Client User Name Credentials discussed above. In
this case, we have the configuration service repositories already loaded with the appropriate endpoint
definitions, defined using the Hosted Services pages in ConfigWeb. However, the Client Certificate
credentials endpoint is marked as non-activated by default, since we are using User Name credentials.
In this section we will show how to change the Business Service tier to require a Client (X.509) Certificate
as client credentials from the Web application. The processing logic is the same pattern as for the User
Name credentials above: a custom certificate validator class in the BSL (and the OPS) is configured via a
WCF Service Behavior in web.config (or app.config for the self-hosts). This class inherits from a base
class supplied by the Configuration Service. The base class has the .NET System.Security logic to
perform certificate authentication via the System.Security.Cryptography.X509Certificates .NET
Framework assembly.

The Business Service tier can only select one mechanism for authentication at a time over a given
network scheme (in this case https). So we will need to deactivate the endpoint using User Name
credentials first, before we activate the defined endpoint using Client Certificate credentials.

Make sure you are logged into ConfigWeb against the StockTrader Web application Azure
Hosted Service domain, as in the section above.
.NET StockTrader Configuration Page 73




From this home page, click on the Select link for the Business Services tier.

.NET StockTrader Configuration Page 74



With the Business Services service domain selected, click the Hosted Services button.

.NET StockTrader Configuration Page 75



Click the Select link for the Primary Service as shown above.



Note
Did you know you can create as many Primary Service hosts as you want with Configuration
Service for a given service domain? The StockTrader Business Services and Order Processing
Service only define one, but in custom implementations/other applications, you can create
many, if desired, to host several different business logic implementation classes each with
their own endpoints/security, etc. Service hosts can either be based on Web Services with
Ws-* bindings, or be RESTful service hosts.
.NET StockTrader Configuration Page 76



You will notice the only endpoint currently active is the one using User Name client
credentials, although several other endpoints are already defined in the configuration
repository, they are in-active.

Click on the Edit link for the only activated endpoint (with User Name credentials over
https with a ws2007HttpBinding being used).

.NET StockTrader Configuration Page 77



We will deactivate this endpoint by de-selecting the Activate Endpoint checkbox.

Click the Update button to process the change.

Click on the Return to Hosted Services for this Virtual Host link at the bottom of the page.
.NET StockTrader Configuration Page 78



Select the Edit link for the hosted service endpoint named: Azure BSL wsHttp security =
TransportWithMessageCredential: ClientCertificate.

.NET StockTrader Configuration Page 79


Check the Activate Endpoint checkbox. Click the Update button.
For the StockTrader Business Services, we are not quite done yet. Right now, the new endpoint is
activated, which requires client certificate credentials as we want. However, we need to configure
the Service Host hosting this Primary Service endpoint to use the correct Service Behavior, which
tells the application a client certificate will now be required, and what validator to use to validate
the client certificate supplied on requests.

Click on the Return to Hosted Services link at the bottom of the page above.
.NET StockTrader Configuration Page 80



Now click on the Return to Virtual Host list link as shown above.
.NET StockTrader Configuration Page 81



Now click on the Edit link as shown, for the Primary Service Host itself.
.NET StockTrader Configuration Page 82



Now, in the second dropdown (Service Behavior Configuration), select the
BSL_M_Security_ClientCert_Behavior, as shown above.

Click the Update button.
How the Client Certificate Gets Validated, and What Certificate is Valid as a Client Credential
for the StockTrader Business Services?
Like the User Name validator discussed in the previous sections, Configuration Service has a base class
that is a Custom Certificate Validator. This is tied to the ServiceBehavior in the Web.config for the
StockTraderBSL Azure project (and also the on-premise project): its in the
\configuration\CustomValidators project within the Configuration Service Visual Studio Solution.
This base class is configured to validate based on several mechanisms, including the thumbprint of the
certificate supplied by the client. We override a method in the StockTrader Business Service
.NET StockTrader Configuration Page 83

implementation that inherits from the base class to provide the list of valid certificate thumbprints we
will allow to use our BSL service operations. The class that does this is in the BSLCustomCertValidator.cs
file in the BusinessServiceImplementation project. The code looks as follows:

/// <summary>
/// The Business Services uses this custom X.509 certificate validator, that uses the base class
/// provided with Configuration Service. This class is referenced in the config file, with the
/// BSL_M_Security_Behavior behavior configuration for the host exe.
/// </summary>
public class CustomCertValidator : CustomCertificateValidator
{
/// <summary>
/// Override to provide our list of valid cert thumbprints for the service.
/// </summary>
/// <returns></returns>
protected override string[] getAllowedThumbprints()
{
List<string> thumbprints = new List<string>();

//This is the thumbprint for the Test Certificate CN=StockTraderBSLClient.Com
(StockTraderBSLClient.pfx).
//This Cert is used by the Business Service Layer to validate the StockTrader Client. When
using this binding in
//conjucntion with the service behavior 'BSL_M_Security_ClientCert_Behavior' (which also
assigns the service certificate),
//only clients presentin the EXACT client certificate will be allowed in. The thumbprint is
unique, meaning,
//no one can create another cert with this thumbprint. Hence, only an app with this exact
client-side
//cert can ever access the BSL when using this WCF message security behavior.
thumbprints.Add("EB0C8C302C4F5E22E4492006F1D16D01008E7826");

return thumbprints.ToArray();
}
}

The thumbprint is for the client certificate for the BSL that we already uploaded to the StockTrader Web
application when installing Azure StockTrader. Its the StockTraderBSLClient.Com certificate, contained
in the \certs\ StockTraderBSLClient.pfx certificate file.
If you go back to the home page of ConfigWeb, and click the Service Map button, you will see the new
endpoint is now active and online (green), and the old one using User Name is not active anymore.

.NET StockTrader Configuration Page 84



Note that the Hosted Service endpoint for the BSL is already configured with an internal client
configuration that allows the BSL nodes to check their own endpoints, in this case using the correct
client certificate which we uploaded to the Business Service domain via the Azure Management portal
when we first created the hosted service during StockTrader setup. The Service Map page works by
requesting remote services to validate their own endpoints for each node (in this case Azure role
instance) running. BUT: the StockTrader Web application is not yet configured to use a WCF endpoint
requiring a client certificate. So we next need to create a new Connected Service Definition for the
StockTrader Web application that will use this service endpoint, instead of the User Name
authenticated endpoint as installed by default.
Changing the StockTrader Web Application to Supply a Client Certificate to the StockTrader
Business Services.

.NET StockTrader Configuration Page 85

Click on the Configuration menu top-level menu item to return to the root StockTrader Web
application home page for ConfigWeb.

Click on the Connected Services button.


.NET StockTrader Configuration Page 86



Click on the Add Service button.
.NET StockTrader Configuration Page 87



We will now connect up to the BSLs Configuration service to get the new endpoint information and
create our new Connected Service definition.
Type in the address to your Azure hosted service domain for the Business Services project you
deployed.

Choose the Client_ConfigSvc_BasicHttpBinding_T_Security client configuration, and click on the
Get Remote Services! button.
.NET StockTrader Configuration Page 88



The BSL has only one active endpoint, but you need to make sure to select the correct client
configuration: Client_Ws2007Binding_T_Security_MCredential_ClientCert_BSL.

Click the Add button.

Next, click on the Connections top-level menu item.

.NET StockTrader Configuration Page 89



You will notice we still have a Connection Point defined to the old, inactive User Name endpoint. Since
the BSL is not hosting this anymore (its deactivated), it shows as red from the client connections page.
We can delete this non-active connection (it does not hurt anything to leave it be, since we will not be
using it, but to keep things clean, we will get rid of it).

Click on the Delete link, and go through the next page to delete the old connection point.

.NET StockTrader Configuration Page 90


Click on the Delete button.

Click on the Return to Connection Page link at the bottom of the page.
.NET StockTrader Configuration Page 91



Click on the Add Connection button.
.NET StockTrader Configuration Page 92


Select the newly created Connected Service Definition: Azure BSL wsHttp security =
TransportWithMessageCredential: ClientCertificate

Enter the base DNS address to YOUR Azure StockTrader Business Services Azure Hosted Service.

Click the Add Connection button.

Click the Return to Connections link.
.NET StockTrader Configuration Page 93



We can see from this page that the StockTrader Web application is seeing the endpoint as online, and
hence the client certificate is working correctly for authentication and being passed by the client to the
service. The reference to the client certificate StockTraderBSLService.Com has been already configured
in the StockTrader Webs client configuration we selected previously, and this client configuration is
contained in the StockTrader web applications Web.config (so it knows where to find the client
certificate to pass to the WCF BSL service).

However, the Web application is still configured to use the other hosted service, via its AccessMode
setting. Notice the title text for the connection is not green above (its black text), meaning the client
connection exists, but its not configured to be used by the Web app via the AccessMode setting. So
the last thing we need to do is change the AccessMode setting so the Web application uses this
endpoint/connection point(s).

.NET StockTrader Configuration Page 94

Click on the Back to Top button to get back to the home page for ConfigWeb, with the Web
application selected.


Click on the Edit Custom Setting link for the Web application.
.NET StockTrader Configuration Page 95



Click on Change Value for the AccessMode setting.

.NET StockTrader Configuration Page 96



Select the Azure BSL wsHttp security = TransportWithMessageCredential: ClientCertificate
option.

Click the Update button.

OK! At this point, we have completely changed both the service and client, so now the StockTrader Web
Application is making all service requests to the Business Services via an endpoint requiring a client-side X.509
certificate. User Name credentials are no longer being used. You can now login as an end-user to the Azure
StockTrader web application. End users will not notice a difference, but you can verify the application is
working in its new configuration.
.NET StockTrader Configuration Page 97

Changing the Samples to Use Different Certificates vs. Default Install Certificates
Now that we have seen how the X.509 certificates are used, the next logical question is how to change
them from the ones provided in the default install? After all, everyone using the default install will have
the same certificates, so anyone could access our services when running in Client Certificate mode as set
above.
To change certificates, you need:
To create or obtain your own certificate. There is a batch file for creating .pfx self-signed
certificates installed in the \certs folder with the StockTrader certificates for this purpose.

You need to upload these certificates to the correct Azure Hosted Service domain(s).

You need to modify the correct service and client behaviors in configuration to use these
certificates as opposed to the default certificates. Simply do a global search for
StockTraderBSLService.Com, for example, to find its uses in Config; but remember that
StockTraderBSLClient.Com will be found in both the Business Services .config files (app.configs
and web.config); and the StockTrader Web apps web.config.

You need to look at the method getAllowedThumbprints (see page 96) on the custom certificate
validator and change this method to use your certificate(s) thumbprints.
These rules apply to both the StockTrader Business Services, and the Order Processor, since both can be
set to use client certificates vs. Username client credentials.
New Hosts and Configuration Service Dynamic URI
Management
You have used ConfigWeb to configure a variety of endpoints to a variety of hosts. You only have to do
these steps once, even if new host nodes are started, however. When a new host now starts up, clients
with definitions will all be notified, and Configuration Service will manage the URIs and load balancing.
You can start the Order Processor program, for example, on a new server, and then in ConfigWeb the
Service Map page and the Connections page will show it; and the BSL layer will already be using the new
node for load balancing/failover.
Separation of Implementation from Schema and Contract
In the service-oriented world, a properly designed system cleanly separates implementation of services
into autonomous black boxes, to avoid ever having to share classes/code between layers. When
running with AccessMode set to any setting other than InProcess; this is the way StockTrader is
designed. However, StockTrader supports the InProcess collapsed mode to run as a standalone Web
application as well, which is also a perfectly valid configuration. Hence, the Visual Studio StockTrader
.NET StockTrader Configuration Page 98

Web Application solution does share projects and classes from Business Services to support this mode.
You should keep in mind, as noted in the source code comments, that this is a special case; and that
normally the only sharing between the StockTrader Web application projects and the Business Service
projects would be the BusinessServiceContract project, and the BusinessServiceDataContract project.
The same is true for the Business Service solution, which references Order Processor implementation
projects to support the in-process order mode (OrderMode=InProcess Activation).
The information for the service and data contract can also optionally be generated via the SVCUTIL.exe
tool that is part of the Windows 7.x SDK; for example if someone else is hosting the service outside of
your organization; or it is written in a different platform like J2EE. This tool generates both the Data
Contracts and the Service Contracts for building clients; it also generates the binding information to be
used. This can then be used as-is; or easily modified into a custom client as we did with .NET
StockTrader. We do not use a purely generated proxy because:
a) We already have a DataContract and ServiceContract designed in separate re-usable projects
that can simply be imported into other solutions.
b) We use the WCF ChannelFactory class with cached instances of channels to Business Services
(and the Order Processing Service) for performance reasons.
Why A Configuration Service and ConfigWeb?
As a composite application, .NET StockTrader can have many services running across multiple
servers. In addition, as a performance sample application, .NET StockTrader has a wealth of
different configuration settings to allow developers to test the performance of various different
technologies, protocols and deployment topologies for an application. Without a way to centrally
manage configuration data, it would be extremely difficult to ensure the composite application, as
whole, was configured as desired and to keep configuration files in sync across various servers
especially if services are deployed in geographically disperse locations. The solution implemented
in StockTrader is the configuration management service, which is a WCF Web service hosted in
each component (StockTrader Web Application, StockTrader Business Services, and StockTrader
Order Processor Service). The configuration system relies on a SQL Server (or Azure SQL Database)
based repository schema.
This service utilizes a central SQL repository/schema, and each element of StockTrader has its own
separate repository. All of the data is not stored in a single shared repository because, to a large
degree, this would degrade many of the intended benefits of service-orientation. For example, if
all elements of the application shared one central database repository, then all would need to be
deployed within one application domain, and typically on the same subnet; or a subnet with direct
connectivity to the single central database.
The configuration service takes a different approach such that each service can be deployed
anywhere. The only requirement of course is that services that directly connect to each other must
have network connectivity. But a composite application might be made up of services that connect
.NET StockTrader Configuration Page 99

several layers deep, in different geographic regions, and all elements might not require (or even be
able to achieve) direct connections to all other elements. A composite application should not be
required to be deployed on the same internal network just to surface an integrated management
and configuration experience. Hence, the configuration management service maintains the
principle that services should be autonomousand each gets its own configuration repository,
although the schemas for the repository are common.
Starting Point for Implementing the Configuration Service
If you are interested in implementing the configuration service, you should start with the new Visual
Studio 2010 template and tutorial. With 5.0, the process is very straightforward since everything is
provided in base classes. Once done, you can use all the features of the Configuration Service and
ConfigWeb for your own applications and services.