Configuring the iMIS SOA web service

Warning!
iMIS SOA installs as an enabled service, so be sure to secure the service before going live.

For the SOA service to receive connections and pass Windows security, configure the following on the machine that is hosting the SOA service:

  1. Install iMIS. This installs the SOA service host with the correct database connection information.
  2. Disable simple file sharing. In Windows Explorer, go to Folder Options > View > Advanced settings.

    3. Note: Missing this can cause the following error:
    A remote side security requirement was not fulfilled during authentication. Try increasing the ProtectionLevel and/or ImpersonationLevel.

Preventing unauthorized access through SOA

If IIS is installed on your computer, then iMIS SOA is integrated with IIS so there is no separate service. The default port is 808. You can change this port through IIS administration. For example:

<setting key="EntityManagerDefaultBaseUri" value="net.tcp://10.10.10.10:808/NetTcp"/>

Note: You can use a TCP port other than port 808 if it is a valid TCP port and is not in use by any other service. Because the default port for net.tcp is 808, ASI recommends that you increment from there.
The 10.10.10.10 IP address is an example only. Use your own IP address.

Note: If you change the default port, you must change the EntityManagerDefaultBaseUri key in the site web.config files, as well as any client that uses SOA.

Do the following to help prevent unauthorized access through SOA:

  1. Limit access to this port to specifically trusted IP addresses only:
    • At minimum, the addresses of any iMIS servers that will be using SOA, or hosting content items that use SOA.
    • The addresses of any other machines hosting in-house applications that use Windows Communication Foundation (WCF) to consume the SOA service.

      • Warning!
      Do not make this endpoint available externally. For B2B and other external scenarios, use the Soap11 (username/password required) endpoint.

  2. To secure the host service’s port, configure Internet Protocol Security (IPSec) to prevent unauthorized access. For complete walkthroughs of IPSec on Windows, see Microsoft’s IPSec guidance.

Accessing the WSDL metadata definition

In order for the WSDL definition to be properly accessed by third-party vendors, the out-of-the-box web.config file for the Scheduler site must be modified:

  1. Open the C:\AsiPlatform\Asi.Scheduler_[your instance]\web.config file.
  2. Change the line:
    3. <serviceMetadata httpGetEnabled="true" httpGetUrl="" />

    to the following:

    <serviceMetadata httpGetEnabled="true" httpGetUrl="" httpsGetEnabled="true" httpsGetUrl="" />

Using IIS, you will not see the ASI SOA host service because it is integrated under IIS. Because of this integration, you must do the following to turn on NetTcp for your sites, for each virtual root you create:

  1. Open Internet Information Services (IIS) Manager on the iMIS server.
  2. In the Connections pane, select Sites.
  3. In the Sites pane, select the virtual root.

  4. In the Actions pane, select Manage Web Site > Advanced Settings.
  5. Make sure net.tcp appears in Enabled Protocols:

  6. Repeat this process for each of your virtual roots.

Note: After you change any iMIS system configuration item, restart the SOA service to ensure that the changes take effect.

By default, iMIS SOA provides the following levels of security to customer data:

  • Transport Layer Security (TLS)
  • A required user name and password
  • User type access rights (ClaimsMap)

In addition, you can protect your customer data by disabling external access, or by restricting SOA or web services access to use by internal systems and trusted partners only. To achieve this, use your Microsoft IIS server to restrict services access by IP address. Regardless of which IIS server version you have, the approach centers on the EntityService.svc file to restrict SOA or ASICommon/Services directory in the web root to restrict access to web services. Choose one of the following strategies:

  • DISABLE – If you do not need outside access to your database, disable external access by renaming SOA/EntityService.svc or ASICommon/Services.
  • RESTRICT – Add another level of security by applying the specific IP address restrictions to EntityService.svc or ASICommon/Services.

Note: To use EntityService.svc, you must have a security certificate from a certificate authority installed.

Do the following to disable access to external services:

  1. Locate SOA\EntityService.svc in the scheduler root or ASICommon/Services in the web root.
  2. Rename the file or directory (such as *.bak).

Note: There is a second EntityService.svc file in the directory \SOA\NetTcp. Do not rename or delete this second file, as it is provides internal-only access (using a protocol not available to external users), and it is required for the operation of iMIS.

By default, IIS installations do not enable IP restrictions, so restricting IPs requires a few more steps.

Do the following to restrict services access by IP:

  1. Ensure that your server has IP security enabled.
    • Windows Server 2012 or Windows Server 2012 R2:
      1. On the taskbar, click Server Manager.
      2. In Server Manager, click the Manage menu, and then click Add Roles and Features.
      3. In the Add Roles and Features wizard, click Next.
      4. Select the installation type and click Next.
      5. Select the destination server and click Next.
      6. On the Server Roles page, expand Web Server (IIS) > Web Server > Security, and then select IP and Domain Restrictions.

      7. Click Next.
      8. On the Select features page, click Next.
      9. On the Confirm installation selections page, click Install.
      10. On the Results page, click Close.
    • Windows 2008/R2:
      1. Go to Start > Administrative Tools > Server Manager.
      2. Select Roles > Web Server.
      3. Select Add Role Services.
      4. Ensure IP and Domain Restrictions is checked.

    • Windows 7:
      1. Go to Start > Control Panel > Programs and Features.
      2. Select Turn Windows features on and off.
      3. Go to World Wide Web Services > Security.
      4. Ensure IP Security is checked.
      5. Click OK and close.

  2. Enable read/write on IIS IPv4 Address and Domain Restrictions:
    1. Open Internet Information Service Manager.
    2. In the Connections pane, select the machine name.
    3. In the <Machine Name> Home pane, click Feature Delegation.
    4. Ensure that IPv4 Address and Domain Restrictions are set to Read/Write.

  3. Edit the applicationHost.config file under C:\Windows\System32\inetsrv\config. You must modify the applicationHost.config file to access the service at the application level.

    Modify the following line:

    <section name="ipSecurity" overrideModeDefault="Deny" />

    change to: 

    <section name="ipSecurity" overrideModeDefault="Allow" />

    Also modify the following:

    <sectionGroup name="security">
	<section name="ipSecurity" overrideModeDefault="Deny" />

    change to:

    <sectionGroup name="security">
	<section name="ipSecurity" overrideModeDefault="Allow" />
  4. Add IP restrictions to the web.config files:
    1. Locate the web.config files in the root of the website:
      • C:\Program Files (x86)\ASI\iMIS\Net\web.config
      • C:\AsiPlatform\Asi.Scheduler_[your instance]\web.config
    2. Right-click on the web.config file.
    3. Select Properties.
    4. Ensure the Read-only check box is clear.
    5. Open the web.config file with a text editor.

      6. Warning!
      The following ASMX web services are no longer supported. Please see Working with iMIS SOA and Using REST for more information.

    6. At the bottom of the file, above the </configuration> line, add the appropriate IP restrictions for the services to which you want to restrict access:

      7. SOA:

      <location path="SOA/EntityService.svc">
	<system.webServer>
	<security>
	<ipSecurity allowUnlisted="false">
		<add ipAddress="127.0.0.1" allowed="true" />
	</ipSecurity>
	</security>
	</system.webServer>
</location>

      MembershipWebService:

      <location path="[iMIS instance]/AsiCommon/Services/Membership/MembershipWebService.asmx">
	<system.webServer>
	<security>
	<ipSecurity allowUnlisted="false">
		<add ipAddress="127.0.0.1" allowed="true" />
	</ipSecurity>
	</security>
	</system.webServer>
</location>

      ClientLog:

      <location path="[iMIS instance]/AsiCommon/Services/ClientLog/loggingservice.asmx">
	<system.webServer>
	<security>
	<ipSecurity allowUnlisted="false">
		<add ipAddress="127.0.0.1" allowed="true" />
	</ipSecurity>
	</security>
	</system.webServer>
</location>

      QueryService:

      <location path="[iMIS instance]/AsiCommon/Services/Query/queryservice.asmx">
	<system.webServer>
	<security>
	<ipSecurity allowUnlisted="false">
		<add ipAddress="127.0.0.1" allowed="true" />
	</ipSecurity>
	</security>
	</system.webServer>
</location>

      SiteMapWebService:

      <location path="[iMIS instance]/AsiCommon/Services/SiteMap/SiteMapWebService.asmx">
	<system.webServer>
	<security>
	<ipSecurity allowUnlisted="false">
		<add ipAddress="127.0.0.1" allowed="true" />
	</ipSecurity>
	</security>
	</system.webServer>
</location>

      For example, these IP restrictions restrict external/http/soap access to only the local computer

A simple test determines if external web access is allowed to your site with a browser. It is important to make such a test to ensure the procedure has been applied correctly.

Go to https://publicservername.imiscloud.com/asi.scheduler_virtualrootname/SOA/EntityService.svc.

So for example, 

https://UK300CloudApp2.imiscloud.com/Asi.Scheduler_<virtualrootname>/SOA/EntityService.svc

  • If access is allowed, a simple display starting with EntityService Service or ASICommon/Services should be displayed.
  • If you have restricted access, a form of an access denied message should be displayed.

Note: A username and password are still required to access data.

Security for these web services is set in the web.config file, which defaults to C:\Program Files (x86)\ASI\iMIS\Net\.

The QueryService web service gives an administrator access to query results for a specific query or for the default query, if the document folder is specified.

By default, the web.config file value of the AppSetting key "secureQueryWebService" is set to "true". When this value is "true", only authenticated users with the SysAdmin role can access or run queries through the QueryService web service. When this value is set to "false", anyone can access or run queries through this web service.

The QueryService.asmx web service file is located at http://<domainname>/imis/AsiCommon/Services/query/queryservice.asmx.

MembershipWebService gives an administrator access to specific membership operations, such as changing user passwords, user names, logins, and so forth.

By default, the web.config value of the AppSetting key "secureMembershipWebService" is set to "true". When this value is "true", only authenticated users with the SysAdmin role can access or change this membership data through the MembershipWebService web service. When this value is set to "false", anyone can access or change this membership data through this web service.

The MembershipWebService.asmx web service file is located in the membership folder at http://<domainname>/imis /AsiCommon/Services/membership/membershipwebservice.asmx.

Note: ASICommon/Services contains the Membership Web Service used for logging in. If you add security on ASICommon/Services, you must grant access to each computer using the Advanced Accounting Console. Secure the group using subnet.