Description

Futurama Webservices provide several security options to use. First of those is authentication using JWT - JSON Web Token. For that to work you will need an integration with IdP (Identity Provider) which will issue the token that will be used with every request. This is a safe, modern and recommended way of increasing security, it applies both to the WCF and REST Futurama Webservices. The second option is to use basic authentication with username and password. However this is an outdated method of authentication and not the most safe, since the username and password data is kept in plain text in the config file, thus not the recommended security method to use.

Authentication with JSON Web Token

When you are using Futurama in web service mode you can configure it to use JSON Web Token authentication. This applies both to WCF and REST web services. If authentication is enabled then for each request to the Futurama application there needs to be a JSON Web Token present in the request authorization header (except for WSDL and HealthCheck endpoints). JWT authentication can be configured with any Identity Provider (IdP) who issues JWTs and has JSON Web Key Set (JWKS) retrieval endpoint to check that issued JWT. Once the integration is done with the IdP, to enable the JWT authentication in Futurama, you need to specify the configuration in the web.config as described below.

Configuration

Two sections need to be defined in order for JWT authentication to work:

1. Under <system.servicemodel>, a new tag behavior extension needs to be added as follow:

<extensions>
	<behaviorExtensions>
		<add name="authorizationJWTCheckBehavior" type="ActuIT.Futurama.Engine.JWTAuthentication.JwtAuthCheckBehaviorExtension, ActuIT.Futurama.Engine">
		</add>
	</behaviorExtensions>
</extensions>

2. Under <servicebehaviors><behavior> tags of the WCF service:

<authorizationJWTCheckBehavior>
	<jwtConfig issuer="issuerValue" audience="audienceValue" jwksUrl="jwksUrlValue"/>
</authorizationJWTCheckBehavior>

Explanation

<behaviorExtensions>

Defines a behavior extension for a WCF service. “Name” attribute can be set to anything, but then it is required to use the same value for the tag name in the second configuration section.

<jwtConfig>

Tag where all configurational values are specified.

Issuer

The issuer identifies the Identity Provider that issued the JWT.

Audience

The audience identifies the intended recipients of the JWT. It is a mechanism to ensure that the token is used by the correct party.

jwksUrl

The jwksUrl is a URL where a JSON Web Key Set (JWKS) is hosted. The JWKS contains public keys used to verify JWTs

Important note:

When all of the above mentioned values are specified in web.config, then JWT authentication is automatically enabled in the application for every call (except for WSDL and HealthCheck endpoints).

Basic Authentication

When you use WCF, you can use the message security options that WCF provides.

You can use message security, for example with a certificate, or with a username and password.

To use a username and password, you need to specify a few things in the web.config

First you define the 'ServiceCredentialsInHeaderAdapter' extension by adding it to system.serviceModel

<extensions>
	<behaviorExtensions>
		<add name="ServiceCredentialsInHeaderAdapter" type="ActuIT.Futurama.Engine.ServiceCredentialsInHeaderAdapterBehaviorElement, 
      ActuIT.Futurama.Engine, Version=*, Culture=neutral, PublicKeyToken=null">
		</add>
	</behaviorExtensions>
</extensions>

Then you add the name of a behavior to the binding of the service

<service behaviorConfiguration="ActuIT.Futurama.WcfService.Service" name="ActuIT.Futurama.WcfService.Service">
	<!-- Service Endpoints -->
	<endpoint address="" binding="basicHttpBinding" bindingConfiguration="BasicHttpBinding_Service" contract="ActuIT.Futurama.WcfService.IService">
	</endpoint>
</service>

Then you add the usernames to the behavior

<behavior name="ActuIT.Futurama.WcfService.Service">
	<!-- To avoid disclosing metadata information, set the value below to false 
        and remove the metadata endpoint above before deployment -->
	<serviceMetadata httpGetEnabled="true"/>
	<!-- To receive exception details in faults for debugging purposes, set the value below to true.  
    Set to false before deployment to avoid disclosing exception information -->
	<serviceDebug includeExceptionDetailInFaults="true"/>
	<serviceCredentials>
		<userNameAuthentication customUserNamePasswordValidatorType="ActuIT.Futurama.WcfService.FuturamaUserNameValidator, ActuIT.Futurama.WcfService" userNamePasswordValidationMode="Custom">
		</userNameAuthentication>
	</serviceCredentials>
	<serviceCredentialsInHeaderAdapter>
		<users>
			<user password="testpassword" username="testuser"/>
			<user password="testpassword2" username="testuser2"/>
		</users>
	</serviceCredentialsInHeaderAdapter>
</behavior>

Make sure the binding configuration BasicHttpBinding_Service is defined within basicHttpBinding.

To apply ServiceCredentials to a Rest call you can define the same behavior. Make sure to name the behavior ActuIT.Futurama.WcfService.RestService.

Feedback

If you have any questions about this subject or if you want to provide us feedback please send us an e-mail.