Configuring Aptify SOA

This topic provides details on the configuring options for Aptify services. It also details common steps that are needed. The details are provided in the following topics:

About the Aptify SOA Web.config Settings

The behavior of Aptify Unified SOA has various settings that can be configured in the IIS web.config file. Changing any Aptify specific attribute in web.config for SOA requires SOA to be restarted for the changes.

Authentication Settings

The following settings customize the token validation handler that is responsible for validation the Aptify token sent on service requests.

  • Aptify.Services.Authentication.BypassAuthRegex – a regular expression for URL paths that should not require authentication. At the very least this property should be set to the authentication endpoint so tokens can be generated. 
  • Aptify.Services.Authentication.AllowTokenInURL – A legacy option for clients that cannot send the Aptify token in the Authorization header. This specifies the token will be in the URL as a query string parameter instead. This is less secure than sending the token in the header, as URLs are typically copied and shared with other users which would expose the access token and provide those users access to the service application. 
  • Aptify.Services.Authentication.DefaultScheme – A legacy option that sets the default scheme when TokenInScheme is being used. The scheme portion of the Authorization header normally describes what authentication provider will be used to validate the token. When the token is being sent in the scheme for legacy applications, the system needs to know what authentication provider to use. This value should be set to the lookup name of the default authentication provider. 
  • Aptify.Services.Authentication.EnableToken – set to false to turn off the token requirement on service calls. This will leave the service end points completely open and allow anyone to make service calls without first performing authentication. This should only be used if HTTP access to the application is secured by another means. 
  • Aptify.Services.Authentication.HeaderName – The header name where the Aptify token should be set. If AllowTokenInURL is being used, this is the name of the query parameter that will have the token value. 
  • Aptify.Services.Authentication.TokenDisabledTimeout – The amount of time, in minutes, that Aptify will cache authentication information in memory. It is possible that a token will have expired based on Token Provider settings but still be available in the cache due to this setting. 
  • Aptify.Services.Authentication.TokenExtensionDelay – The amount of time, in seconds, that Aptify should wait before renewing a token that has been used. For performance reasons we do not do this on every use of the token. Aptify will enforce a default value of 5 minutes if no value is given.
  • Aptify.Services.Authentication.TokenInScheme – a legacy option for clients that are sending the Aptify token in the Authorization header scheme instead of the Authorization header parameter. Set to true to enable this legacy behavior. If this is enabled the DefaultScheme option must also bet set. Using this option also means that only one authentication provider can be used for this service application.
  • Aptify.Services.Authentication.UseSession – set to true to store authenticated information on the user in the container session object. This is useful when service URLs will be used in a scenario where the token cannot be set in the header, such as in-lining URLs to an image service for HTML <img> tags. Default value is false.


This setting has a significant performance cost that results in disparate service requests for the same user blocking each other. The result is that when this setting is set to true, an application will feel slower.

  • Aptify.Services.CredentialContainer.UseAptifyCookie -  set to true to store authenticated information on the user in the container session object. This is useful when service URLs will be used in a scenario where the token cannot be set in the header, such as in-lining URLs to an image service for HTML <img> tags. Default value is true.


This setting serves the same functional purpose as Aptify.Services.Authentication.UseSession (with regard to the token not being set in the header), but it does not impact application performance.

Cross Origin Resource Sharing (CORS)

Cross Origin Resource Sharing, or CORS, is a W3C standard that allows Javascript to make HTTP request to another domain. For security reasons modern browsers will reject any HTTP response that comes from a domain other than the origin domain the script is hosted from. By sending specific HTTP headers on service responses, Aptify can instruct the browser to accept these requests. The following settings can be applied, and all are mandatory except PreflightTimeout. 

  • Aptify.Services.CORS.AllowCredentials – If set to true will add the Access-Control-Allow-Credentials header and give it a value of true. It allows client applications to send authentication credentials on service requests. Most Aptify installations will require this to be enabled. 
  • Aptify.Services.CORS.AllowedDomains – a semi colon delimited list of domains that CORS requests are allowed from. This should be set to the domain hosting the client Javascript application. A value of * will not work if AllowCredentials is enabled. 
  • Aptify.Services.CORS.AllowedHeaders – a semi colon delimited list of HTTP headers that are allowed for CORS requests. A value of * will allow all headers. 
  • Aptify.Services.CORS.AllowedMethods – a semi colon delimited list of HTTP methods that are allowed for CORS requests. A value of * will allow all HTTP methods. Aptify.Services.CORS.PreflightTimeout – the time in seconds that a preflight response can be cached in the browser. There is no default timeout applied. 

HTTPS Settings

Aptify provides the ability to enforce HTTPS communication from within the service application. This check is performed independently of the software hosting the application. If HTTPS is required and a GET request is received, the service application will respond with a 302 status code to the HTTPS end point. 

  • Aptify.Services.Security.RequireHttps – set to false to disable the HTTPS requirement for all service end points.
  • Aptify.Services.Security.RequireHttpsExceptionFilter – a regular expression that should match any URL paths that should not require HTTPS.

Other Settings

  • Aptify.Framework.AuthorizationPlugins - throws an explicit exception if plugin does not inherit from the expected base class. 

  • Aptify.Framework.Services.Controllers - Controller Configuration Collections raise an error if the pre/post processor plugin is the same as the controller itself.

  • Aptify.Framework.UploadsPath – the path where files processed by the upload service should be written to disk. 
  • Aptify.Services.General.ApplicationName – the name of the service application. This should correspond to a record in the Service Applications entity. It will dictate what authentication providers are available for this application.
  • Aptify.Services.General.ServiceRoute – a URL path element that should be appended after the hosted website name but before the explicit service end point. 
  • Aptify.Framework.LoginServices.AptifyLogin - these are the standard Aptify settings for logon information. This represents the initial connection into Aptify that the service application makes to validate authentication requests. 

Changing Authentication Providers

Using a different Authentication Provider requires 2 changes. First, the Service Application record in Aptify for the particular Unified SOA installation must have its Authentication Provider subtype records updated to indicate which Authentication Providers are valid. Updating any records in Aptify under the Web Service application requires a restart of the service layer for the changes to be recognized. Second, the client Javascript application must be updated to indicate which Authentication Provider it is using. This is done in the External.js file with the Aptify.framework.configuration.authenticationMethod variable.

Changing the Unified SOA URL

It may be desirable to change the URL of the SOA application after installation has been completed. The following keys must be updated in the External.js file to reflect the new location:

  • Aptify.framework.configuration.signalrUrl
  • Aptify.framework.configuration.servicesUrl

The main page of your client application will also need to be updated to have the correct location for the signalR end point. Typically the main page is the index.html page. Check the script list in that page for any fully qualified URLs to SOA and update them as necessary.

You may potentially need to update the Attributes on the Authentication Provider records. This will vary depending on the Authentication Provider, and it is only necessary if those attributes reference a fully qualified service end point.

Changing the Database Server

If the Aptify database moves to a different server the web.config files for all applications will need to be updated. Attributes for the Authentication Providers will also need to be updated to reflect the new server information.

Adding a New Client Application

If you develop a new client application Aptify SOA will need its CORS settings updated in order for the client application's service requests to be successful. See the CORS section in About the Aptify SOA Web.config Settings for more information. 


Was this article helpful?
0 out of 0 found this helpful



Please sign in to leave a comment.