Inbound calls

An inbound call is a service provided by Litium Studio being called from an external system, for example an ERP or PIM.

Developing

An inbound call implementation should extend Litium.Studio.Integration.Services.BaseService. The BaseService is a class that implements helper methods to get the SecurityToken for the current user requesting the service. The security token is used to authenticate the user and give access to authorized operations.

Using the SystemToken is not recommended since users may gain access to non-authorized operations.

For code samples on how to build services using Litium Studio API, open the code behind files (.cs) in the sample project.

How to obtain a certificate

To obtain an X.509 certificate, you can either buy it through a trusted reseller or create a self-signed certificate. Read more on how to obtain an X.509 certificate on the Microsoft developer site.

We recommend that you use a certificate bought through a reseller. For a developing or staging server the self-signed certificate is an alternative. If you already have a certificate for you website you might use that instead of buying a new one.

The inbound service framework will support an X.509 certificate from the computer’s certification store or load a certificate from a pfx file in the file system.

Configure bindings, behaviors and services

You need to configure the binding and behaviors to enable authentication and authorization in the Web.Config file. This needs to be done even if you choose to load an X.509 certificate from a pfx file.

Note: The following paragraphs will only describe how to configure and host the WCF services inside Microsoft IIS with HTTP as transport protocol.

Authorization and authentication

To enable the authorization and authentication to work with Litium Studio you need to add your own bindings and serviceBehaviors in the Web.Config file. (Remember to name your binding and behaviour since you need to reference to them when specifying your services.)

The bindings should be inside the system.serviceModel\bindings\wsHttpBinding node. Security mode should be set to “Message” and the client credential type for the message to “UserName”.

binding

The serviceBehaviors should be inside the system.serviceModel\behaivors node. In the serviceAuthorization node, set the principalPermissionMode to “UseAspNetRoles”. In the serviceCredentials\userNameAuthentication node, set the userNamePasswordValidationMode to “Custom” and the customUserNamePasswordValidatorType to “Litium.Studio.Integration.Security.AuthenticationValidator, Litium.Studio.Integration”.

behavior

Configure the certificate to be used

To tell the WCF service which X.509 certificate that should be used you need to make the following configuration.

If using a certificate from the certificate store:

  • Add the serviceCertificate element inside the system.serviceModel\behaviour\serviceCredentials element to specify the way to find the certificate. Read more on the Microsoft developer site at http://msdn.microsoft.com/en-us/library/ms731899.aspx

If your X.509 certificate is stored in a pfx-file:

  • Copy the file into your web folder (in a folder that is not accessible for clients, for example the App_Data folder).
  • Add the IntegrationCertificate and IntegrationPassword in the appSettings-section of the Web.Config file;
    • IntegrationCertificate should contain the path and filename for the certificate file. This can be an absolute or relative path.
    • IntegrationPassword should contain the password for the certificate to be able to use the private key for the certificate.

certificate key

Configure services for client access

Each service needs to be configured to be accessible for clients. In the Web.config you describe where the IIS will find the service and the service contracts that should be used.
The services configuration should be inside the system.serviceModel\services node in the Web.config.

The service configuration should look like this:

service

Configure the factory for the service

To use the certificate entered in the Web.config the service factory needs to be configured for the service. You do this in the Service.svc file (Service.svc should be replaced with the filename for the service you have created) where you also find the service name. When you open up the markup for the Service.svc file you should find a Factory attribute, if the service is already configured to use the inbound service framework. If the Factory attribute isn’t in the file you can add it and point to the class Litium.Studio.Integration.ServiceModel.CertificateServiceHostFactory.

Example of the service-host configuration in the Service.svc file:

servicehost.png

Is this page helpful?
Thank you for your feedback!