There are several levels of security for the Connected Services Framework components. The security specific to a component—for example, authenticating the user based on their roles—is incorporated into the specific components. The overall security of the application at the interface level is managed through the Web Services Enhancements (WSE) security through the configuration of the security policy file.
Additional security is provided by the Session while routing messages. The behavior of those security checks and the passing of security credentials from the Session to the target process is configurable and driven by the setup of the manifest and the data sent to Session when creating the Session.
WSE Security Configuration
The Web Services Enhancements (WSE) policy file contains the configuration to perform two key operations:
- The authentication of the user token in incoming messages—When the policy is applied, the user name and password are validated to insure that the user is a valid Windows user. If the user is not valid, the message will be rejected by the receiving application.
- The encryption/decryption of the message body and user token—The policy will also encrypt the user token containing the name and password as well as the body of the message while it is in transit. The default encryption mechanism in the policy file is to use X509 certificates.
The configuration of security requires that certificates be created for each machine in the configuration. That certificate with the public and private keys should be loaded into the local machine certificate store. Each machine should then have the public keys of all the other machines in the configuration loaded into its own local machine store.
Once suitable certificates are created and stored, the policy file may be configured. All components should share a common policy file, and all components sending or receiving messages should have an entry in that policy file indicating what security policies to follow. Any component that is not in the file when the security policy is active will not be able to send or receive messages. The policy file is named PolicyCache.config and appears in the common configuration directory shared by all components.
Each component has a similar entry in the PolicyCache.config file:
<endpoint uri="http://HostName/Session/SessionManagerAdmin.ashx"> <defaultOperation> <request policy="#VerifyUserEncryptMessage" /> </defaultOperation>
The endpoint URI specifies that exact match of the URI that the component uses to receive messages. Note that this is an exact string match and it is case sensitive. The name of the node and the IP of the node are not considered identical. If there is any uncertainty as to which will be used to receive messages, place both in the configuration files. The request policy parameter simply refers to one of the three policies predefined in the configuration file at the end. They are:
- VerifyUser—Verify the user is a valid Windows user.
- EncryptMessage—Encrypt the selected parts of the message, the user name token, and the message body.
- VerifyUserEncryptMessage—Do validation and encryption. This is the default policy.
All the endpoints in the configuration file need to be altered at installation time to use the correct URI (determined in the previous installation steps) and insure they use the default policy to validate the user and encrypt the message. Note that the test programs that send message into the system—for example, the OssClient—need to be configured into the policy file as well and they need to alter their own configuration files (OssClient.exe.config) pointing to the policy file. Any external services accessed by Connected Services Framework also need to be added to and configured into this security scheme. They do not need to have all the endpoints configured in to their local policy files, but must have similar configurations for the endpoints they talk to.
The EncryptMessage and VerifyUserEncryptMessage policies have to be edited to have the correct certificate name specified in the wssp:SubjectName tag. This is the same name as is displayed in the certificate manager MMC plug-in in the issuedTo column.
The connection between the component and its security policy file is in the application's Web.config file (or similar configuration file) using the following parameters:
<microsoft.web.services2> <policy> <cache name="C:\CsfConfig\PolicyCache.config" /> </policy> <security> <x509 storeLocation="LocalMachine"/> </security> </microsoft.web.services2>
If the <policy> element is commented out, no security checks will be performed.
The <x509> element contains the location of the certificates. All certificates should be added to the machine store.
When certificates are used for encryption, the various accounts used to run the components must have access to the certificates or they will be unable to decrypt the incoming messages using the private keys. The WSE 2.0 distribution contains a utility that simplifies the setting of permissions on certificates. It is in the X509 Certificate Tool (Programs menu, Microsoft WSE 2.0 option). Open that tool and use it to load the local machine certificate. The certificate should be in the Local Computer and Personal store.
The Private Key File Permissions button at the bottom of the window brings up a standard file permission pop-up that can be used to set permissions for the private key on the local machine. All the accounts used by the services on the local machine will need read access to the certificate in order to decrypt incoming messages. It is easiest to bring up the IIS manager and check each service on the local machine to determine what account it is running under (the application pool identity) and grant that account access to the private key. Failure to do this will result in errors being written out to the trace logs of the service indicating that it cannot access the private key and cannot decrypt the message.
If test certificates are to be used, be aware that the makecert command delivered with the 1.1 version of the .NET Framework will not work. The version delivered in the platform SDK is correct. It is version 5.131.3672.0. To make test certificates and load them into the machine store, use the following command:
makecert -cy end -n "CN=Test Server" -sky exchange -sk "TestCompanyServer" -ss "My" -sr localmachine -in "Test Company" -ir localmachine
This produces a valid certificate with a public and private key named “Test Server” and loads it into the local machine store.
The x509 element in the configuration file will also need to be updated to allow test certificates to be used:
<x509 storeLocation="LocalMachine" allowTestRoot="true" allowRevocationUrlRetrieval="false" verifyTrust="false" />
Session has several levels of security that are checked at run time when messages are being sent through the Session. The first is when the Session is created. When the Session is created, SBEMasterController (or any other component creating Sessions) will send in its own credentials to allow the Session to be created. The second is when messages are routed. The Session will validate that the incoming credentials are valid Connected Services Framework users that are allowed to route messages. These users must be in the CSF AD domain as well as a part of the Requestors@CSF_Session user group. Since all users that are added to the CSF AD domain are automatically added to the Requestors@CSF_Session group, this should not require any actions other than the standard setup of user groups in Active Directory.
After the incoming message is validated by Session, the credentials will be cleared out. The outgoing request will have credentials added to it based on the configuration of the Session Manifest used when the Session is created. Based on that configuration, the session will either:
- Clear out and not replace the credentials—If the service that is the target of a message does not have any policy specified in the Session Manifest and there is no Persona specified in the manifest, the Session will clear out the credentials and the outbound message will not contain any credential information.
- Add in secondary credentials from SSO—If the service that is the target of a message has a policy specified in the Session Manifest and there is a Persona specified in the manifest, the Persona will check for secondary credentials through IDM in the SSO database for the user specified in the Persona in the manifest. This check of SSO will use the logical name of the target service as the application name in SSO. If there are secondary credentials in SSO, they will be passed along in the outbound message to the target service.
- Pass through the credentials of the Persona (user) in the Session Manifest at Session creation—If the service that is the target of a message has a policy specified in the Session Manifest and there is a Persona specified in the manifest, the Persona will check for secondary credentials through IDM in the SSO database for the user specified in the Persona in the manifest. This check of SSO will use the logical name of the target service as the application name in SSO. If there are no secondary credentials in SSO, the credentials of the user already in the Persona will be passed along to the target service.
Session Manifest Security Settings
As noted in the previous section, the behavior of Session and how it manages the user credentials is driven by the contents of the Session Manifest used to create the session. This manifest is created by the SBEMasterController, a component of Order Handling Standard Business Events (OH-SBE), based on the template manifest stored in the database as well as it own configuration checks at run time. This section covers the Session Manifest with respect to those setting controlling security and how those are set by the OH-SBE.
The SBE has several requirements for security at the manifest level.
- All Session Manifests must have a persona participant defined.
- All services must have a security policy defined.
The result of these requirements is that any message sent through the system will always have user credentials required for processing. These will either be the credentials from the persona when the Session is created or secondary credentials required by an external service.
So any template manifest in the database must have a Persona participant added to it or routing will fail at some point in the messaging. All example manifests have this configured. The relevant XML is:
<csfse:Participant timeout="30" role="Persona" mode="OneWay" type="WebService"> <csfse:ParticipantName>CSF_Session_PersonaParticipant</csfse:ParticipantName> </csfse:Participant>
The Connected Services Framework Profile Manager component will add in security policies for services when it processes the requests. Currently the policy document is a placeholder and the contents are not used except as a flag. Profile Manager adds in that policy document using the data in the VasServicesPolicyConfigurationData.config file. This file contains a simple mapping of the logical name of a service to an appropriate policy file. All services in the Session Manifest must have an appropriate entry in this file. A simple policy file, VasPolicyCache.config, is provided and may be used for all the services.