Server Side Authentication Using WCF Endpoints for AgilePoint Server

The APIs for AgilePoint Server are exposed as a standard WCF service. So your applications can use any desired binding, all API endpoints (Admin, Workflow, Event Service, and so on) are exposed over all available bindings. These bindings include wsHttps, basicHttp, netTcp, and webHttp.

For example, you may want an ASP.NET application to use the netTcp binding because it is faster, and you may want a mobile application to use the webHttp binding, which exposes AgilePoint API as RESTful endpoint.

Server Side Authentication

When WCF-based AgilePoint Server receives an API call, it performs a server-side authentication. The type of server-side authentication method is associated with the binding used to make the API call. This association is set in the file [AgilePoint Server installation folder]\bin\Ascentn.AgilePoint.WCFService.exe.config.

The following example shows a setting in Ascentn.AgilePoint.WCFService.exe.config where AgilePoint Server uses Windows Authentication to perform server side authentication for any API call coming in over netTcp binding.

<netTcpBinding>
  <binding name="AgilePointNetTcpBinding" closeTimeout="00:05:00" openTimeout="00:05:00" receiveTimeout="00:10:00" sendTimeout="00:05:00" transactionFlow="false" transferMode="Buffered" hostNameComparisonMode="StrongWildcard" listenBacklog="100" maxBufferPoolSize="2147483647" maxBufferSize="2147483647" maxConnections="100" maxReceivedMessageSize="2147483647">
    <readerQuotas maxDepth="32" maxStringContentLength="2147483647" maxArrayLength="2147483647" maxBytesPerRead="4096" maxNameTableCharCount="16384" />
    <reliableSession ordered="true" inactivityTimeout="00:10:00" enabled="false" />
    <security mode="Transport">
      <transport clientCredentialType="Windows" protectionLevel="EncryptAndSign" />
      <message clientCredentialType="Windows" />
    </security>
  </binding>
</netTcpBinding>

Issues Using Windows Authentication with webHttp Binding for REST

Using Windows authentication for server-side authentication with webHttp binding and REST works fine with Internet Explorer 10 and lower. However, IE 11 and non-IE browser, such as Firefox or Chrome fail in this scenario.

The reason for the failure in IE 11 uses a preflight request that is sent to the server with the OPTION verb, which prevents cross domain access. Microsoft support has not provided AgilePoint a solution for this issue.

In any case, REST APIs are often used for non-Microsoft apps such as HTML with JQuery, or a mobile applications. These apps cannot use Windows authentication, so a custom security model must be provided.

Using Custom Authentication Model

If you want to use REST APIs with IE 11, non-IE browsers, or non-Microsoft apps, you must use a custom security model. You need only create this security module once. AgilePoint provides the following implementations of the custom security module out of the box:

Authenticate users against your Active Directory
Authenticate users against your local machine. Use this option if the AgilePoint Server is not part of an Active Directory domain.

By default the custom authentication model reads the authentication header from incoming request and validates it against your Active Directory. However this is a customizable module where you can provide your own authentication for a REST endpoint. It even allows you to provide different authentication for different apps on the same REST port. This way you are not restricted to Windows authentication, and your REST APIs work for non-Microsoft apps securely.

To support custom authentication, in the file [AgilePoint Server installation folder]\bin\Ascentn.AgilePoint.WCFService.exe.config, sect clientCredentialType="None".

<netTcpBinding>
  <binding name="AgilePointNetTcpBinding" closeTimeout="00:05:00" openTimeout="00:05:00" receiveTimeout="00:10:00" sendTimeout="00:05:00" transactionFlow="false" transferMode="Buffered" hostNameComparisonMode="StrongWildcard" listenBacklog="100" maxBufferPoolSize="2147483647" maxBufferSize="2147483647" maxConnections="100" maxReceivedMessageSize="2147483647">
    <readerQuotas maxDepth="32" maxStringContentLength="2147483647" maxArrayLength="2147483647" maxBytesPerRead="4096" maxNameTableCharCount="16384" />
    <reliableSession ordered="true" inactivityTimeout="00:10:00" enabled="false" />
    <security mode="Transport">
      <transport clientCredentialType="None" protectionLevel="EncryptAndSign" />
      <message clientCredentialType="None" />
    </security>
  </binding>
</netTcpBinding>

For more information about creating your custom security model, see Creating a Custom Authentication Mechanism

Using Windows Authentication with IE 10 and Lower

If you want to use REST APIs for web apps used over IE 10 and below only, in the file [AgilePoint Server installation folder]\bin\Ascentn.AgilePoint.WCFService.exe.config, sect clientCredentialType="Windows", as shown in the following example. This is not a common scenario.

<netTcpBinding>
  <binding name="AgilePointNetTcpBinding" closeTimeout="00:05:00" openTimeout="00:05:00" receiveTimeout="00:10:00" sendTimeout="00:05:00" transactionFlow="false" transferMode="Buffered" hostNameComparisonMode="StrongWildcard" listenBacklog="100" maxBufferPoolSize="2147483647" maxBufferSize="2147483647" maxConnections="100" maxReceivedMessageSize="2147483647">
    <readerQuotas maxDepth="32" maxStringContentLength="2147483647" maxArrayLength="2147483647" maxBytesPerRead="4096" maxNameTableCharCount="16384" />
    <reliableSession ordered="true" inactivityTimeout="00:10:00" enabled="false" />
    <security mode="Transport">
      <transport clientCredentialType="Windows" protectionLevel="EncryptAndSign" />
      <message clientCredentialType="Windows" />
    </security>
  </binding>
</netTcpBinding>