Click or drag to resize

How To: Consume an Informatie Vlaanderen SOAP Service

This section describes how to use the FederatedChannelFactoryT to consume an Informatie Vlaanderen SOAP service.

Consuming an Informatie Vlaanderen SOAP service can be done using the standard tooling Visual Studio offers, to generate a proxy. Once the proxy is generated, you can use this proxy in your code to call methods of the service. WCF handles all the WS-Trust stuff for you.

Behind the scenes, WCF will:

  1. Obtain a token from our Security Token Service for an Informatie Vlaanderen SOAP service, using the client credentials passed to the proxy.

  2. Call the Informatie Vlaanderen SOAP service with the received token.

Obtaining a token is done the first time you call an operation on the proxy. On every other call the token will be reused, as long as the proxy is not disposed. Requesting a new token is a costly operation, and the out-of-the-box implementation of WCF does not cache the received token between proxy instances to the same service. Not caching the token can lead to unneccessary requests for tokens, certainly in the case of web applications where one action of a user can trigger several requests calling the service.

The FederatedChannelFactoryT provides a means to safely call a claims aware service, and cache the token for subsequent calls to the service.

Prerequisites:

In order to call an Informatie Vlaanderen SOAP service, you need the following information:

  • The hostname of the STS.

  • The realm of the STS.

  • The address of the service.

  • The realm of the service.

  • The certificate used to authenticate against the service.

Consuming an Informatie Vlaanderen SOAP service

  1. Add a service reference to the project.

    This will generate a proxy and add the necessary changes to your configuration file.

  2. Install the nuget package for your framework

    Installing the nuget package (Be.Vlaanderen.Framework.Identity) will provide you with the necessary dll's and config transformations, to call your service. The packages are available at Nuget.Org .

  3. Configure the certificate credentials used to call the service.

    Replace the %Certificate Subject Distinguished Name% placeholder with the subject distinguished name of the certificate in the endpointbehavior, you can find this by copying this from the .cer file. It's under details -> Subject. The different values need to be seperated by comma's (e.g. "CN=YourCompany.ServiceAccount, O=YourCompany, OU=It Department")

    XML
    Copy
    <endpointBehaviors>
...
<behavior name="CertificateEndpointBehavior">
  <clientCredentials>
    <clientCertificate findValue="%Certificate Subject Distinguished Name%" storeLocation="LocalMachine" storeName="My" x509FindType="FindBySubjectDistinguishedName" />
  </clientCredentials>
</behavior>
...
</endpointBehaviors>

    Next we configure our endpoint to use this certificate.

    XML
    Copy
    <endpoint ...
           behaviorConfiguration="CertificateEndpointBehavior"
           ...>

</endpoint>

  4. Configure the STS host and realm.

    When installing the nuget package the beta realm and host are automatically entered in the appSettings, so you just need to enter the application realm. For production you need to change the settings according to the provided table.

    XML
    Copy
    <appSettings>
  ...
  <add key="STSHost" value="%Host%"/>
  <add key="STSRealm" value="%STS realm urn%"/>
  <add key="ApplicationRealm" value="%Application realm%"/>
  ...
</appSettings>
    STS settings

    Setting

    Description

    Beta

    Production

    STSHost

    The hostname of the STS

    beta.auth.vlaanderen.be

    auth.vlaanderen.be

    STSRealm

    The realm urn for the STS

    urn:informatievlaanderen.be/sts/beta

    urn:informatievlaanderen.be/sts

    ApplicationRealm

    The realm urn for the application

    see List of consumable services

    see List of consumable services

    Note Note

    In case you need multiple SOAP services in one application you can use the provided stsClientConfiguration section. This will allow you to link the attribute 'name' from your endpoint to an application Realm

    XML
    Copy
    <configSections>
  <section name="stsClientConfiguration" type="Be.Vlaanderen.Framework.Identity.Protocols.StsClientConfigurationSection, Be.Vlaanderen.Framework.Identity, Version=1.0.0.0, Culture=neutral, PublicKeyToken=234f85563f12b566">
</configSections>
...
<stsClientConfiguration>
  <applicationRealms>
    <applicationRealm name="urn:informatievlaanderen.be/gipod/service/prod" endpoint="WS2007FederationHttpBinding_IGipodService" />
    <applicationRealm name="urn:informatievlaanderen.be/grbmeldingservice/prod" endpoint="ws2007Federation_IGRBMSService" />
  </applicationRealms>
</stsClientConfiguration>

  5. Use FederatedChannelFactoryT to call the service.

    The following example shows how to create a factory and channel to call the operation on the service in the case you provided certificate credentials via configuration (see above.)

    C#
    Copy
    using Be.Vlaanderen.Framework.Identity;
using Be.Vlaanderen.Framework.ServiceModel;

namespace ConsumeService
{
  class Program
  {
    static void Main(string[] args)
    {
      var factory = new FederatedChannelFactory<ServiceReference.IServiceChannel>("InformatieVlaanderenService_WsFed");
      var channel = factory.CreateChannel();
      using (channel.CreateSafeDisposer())
      {
        var data = channel.GetSomeData();
      }
    }
  }
}

    FederatedChannelFactoryT has 3 public methods used for 3 different scenario's:

    CreateChannel

    The ClaimsIdentity passed to the service contains the identity and claims corresponding to the certificate used to call the service.

    This method is mostly used when you have a batch process, making calls to the service.

    CreateChannelActingAsCurrentUser

    The ClaimsIdentity passed to the service contains the identity and claims corresponding to the certificate used to call the service, and the ClaimsIdentity from the currently logged on user.

    For more information see: How To: Call an Informatie Vlaanderen SOAP Service in an ActAs scenario

    CreateChannelOnBehalfOfCurrentUser

    The ClaimsIdentity passed to the service contains only ClaimsIdentity of the currently logged on user.

    For more information see: How To: Call an Informatie Vlaanderen SOAP Service in an OnBehalfOf scenario

See Also