Terrain Server

STK Terrain Server Installation Guide

This guide walks you through the process of installing and configuring STK Terrain Server on your system.

Contents

System Requirements

  • 64-bit Windows, including Windows Server 2008R2 or later, and Windows 7 or later.
  • Microsoft .NET Framework v4.5 or later.
  • Internet Information Services (IIS) v7.0 or later.
  • 4 GB RAM or more.

Additional System Considerations

  • Faster CPUs, Solid State Drive, and more RAM will significantly improve terrain processing time.
  • Plenty of disk space for storing raw and processed terrain data. We recommend 1 TB of disk space for hosting the separately-licensed STK World Terrain Dataset; this curated tileset will continue to grow in size.
  • Processing high resolution (sub meter) terrain tilesets will require additional GB of RAM, a minimum of 8 GB of RAM is recommended.

Installation

  1. Install Internet Information Services (IIS) v7.0+, Microsoft .NET Framework v4.5+, and ASP.NET if they’re not already installed. Use "Turn Windows Features On/Off" or "Server Manager, Add Roles" to enable these requirements. The following list demonstrates the minimum set of Windows Features that must be enabled on Windows 7 or Windows Server 2012R2:
  2. After enabling the required Windows Features, double-click install.exe to run the STK Terrain Server installer and follow the on-screen instructions.
  3. Launch License Manager and use it to install your STK Terrain Server license.
  4. Launch STK Terrain Server by selecting it from the Start menu/screen, or by visiting http://localhost/stk-terrain.

Default Authentication

The STK Terrain Server installer defaults to enabling Windows Authentication for read-write access to the Terrain Server Application. All users, including anonymous, unauthenticated users, are allowed to do GET requests. In STK Terrain Server, GET requests cannot make modifications to the server, so this rule provides read-only access to everyone. Only users that are members of the Windows Group specified during installation (StkTerrainServerAdmins, by default) can modify the STK Terrain Server contents. If there is no possibility of accidental or intentional misuse in your environment, you may disable the Windows Authentication in the Setup dialog. To further restrict read-only access to the STK Terrain Server, see the optional configuration section below, Configuring Authentication in IIS

Creating a Windows Group for Read-Write Access

The Windows Group may be set to a different Windows Group if preferred by specifying a new group name from the Terrain Server Installer. In the case of electing to keep Windows Authentication enabled during the installation process, you must create a Windows Group configured to match the Group name chosen during installation, defaulting to StkTerrainServerAdmins. Windows groups can be added and managed from the Computer Management Windows application, via the Groups folder under "Local Users and Groups".

To Add a new Windows User Group, launch the Computer Management Windows application. In recent versions of Windows, this is easily done by clicking on the Windows button or pressing the Windows key, and typing "management" to filter the list of available programs to those that contain the word "management". Right click on "Computer Management" from this list and choose to "Run as Administrator".

In the Computer Management application, find the Groups folder in the left panel. Right click on the Groups folder and choose "New Group...".

Define the Group Name to match the group name chosen during installation. As an example in this guide, we'll configure the default group, "StkTerrainServerAdmins". We also recommend that administrators provide a readable description of the group for clarity and charity.

"Members of this group have permissions to perform 'write' operations on the STK Terrain Server."

At this point, we have defined the Windows Group that will have administrative privileges to the Terrain Server's Web Admin UI. The next step is to specify the user's Windows accounts that will belong to this group and gain access to these elevated Terrain Server permissions. To add Windows Users to this new group, open the StkTerrainServerAdmins group if it not already open by double clicking on the Group name in the Computer Management Application. Click on the Add... button. This is a standard windows permissions dialog; provide all or a majority of the user name and use Check Names to lookup and verify the username is recognized by the domain. A valid windows user account can belong to the Windows domain as shown in the image below, or can be a local user account.

After adding users to the StkTerrainServerAdmins group, click Create to finalize the group followed by Close to close the dialog.

Finally, you can verify this new users group is configured correctly. Open a web browser and navigate to the STK Terrain Server DataSources page. Create a new DataSource by clicking on the Add DataSource button. With this configuration complete, the web browser will automatically prompt for login credentials when attempting to perform an action within the STK Terrain Server application that does not allow anonymous access. In some cases, the login may be automatic (no explicit prompt) when you’re logged into the server as a user that is allowed access, or if your network has a Windows domain and your domain user is allowed access.

Licensing

If a license for STK Terrain Server is not yet installed, browsing to the Data Sources or Tilesets page in the web interface will redirect to a license information page:

As the page says, the easiest way to install a license is by running the STK License Manager on the server. The "Obtain Purchased License" tab allows you to obtain an already-purchased license through AGI’s Customer Licensing System, and also contains contact information if you need to purchase a license.

If you already have a license file, click the "Manage Licenses" and click the Install a License File button. Browse to your license and click Open. Then, return to the STK Terrain Service licensing page and click the "Check Again" button. If the license was installed successfully, you will be automatically directed to the Data Sources or Tilesets page. If there is a problem with the license, diagnostic information will be displayed on the page. Please contact AGI support if you have difficulties with licensing.

Advanced Authentication and Authorization for IIS

The following section provides an overview of additional configurations that can be made to an IIS deployed terrain server installation. In most cases, the default configuration chosen during installation described in the section above is appropriate for the operating environment.

Configuring Authentication in IIS

The current version of STK Terrain Server supports authentication using the Windows or Basic authentication mechanism in Internet Information Services (IIS). It allows you to designate Windows users or groups that are allowed to make modifications inside the application. To set it up, open the Internet Information Service (IIS) Manager and navigate to the "stk-terrain" virtual directory in the "Default Web Site". Your virtual directory may have a different name if you changed the default during installation. Then, choose the Authentication feature.

Then, enable "Windows authentication" or "Basic authentication". We recommend that you use Windows authentication whenever possible. Basic authentication will send login credentials in clear text in the HTTP request, which is a security problem unless your server is also configured to require an HTTPS connection.

If the authentication mechanism you want does not appear in the list, you will need to install it. On Windows Server 2008 and 2012, authentication mechanisms are installed using Server Manager. Navigate to the IIS pane, scroll down to the Role Services section, and click the "Add Role Services" button or select "Add Roles and Features" from the Tasks drop-down. The features are found under Web Server (IIS), Web Server, Security.

On Windows Vista, 7, 8, and 8.1, authentication mechanisms are installed via "Turn Windows features on or off", under Internet Information Services, World Wide Web Services, Security.

Next, we configure which users and groups are allowed access to the application. In the Features View for the stk-terrain virtual directory again, select .NET Authorization Rules.

IIS .NET authorization rules are evaluated in top-down order, and the first rule that matches a user and HTTP verb takes effect. If the first matching rule has a mode of "Allow" the user will be allowed to perform that action. If the first matching rule has a mode of "Deny" the user will not be allowed to perform that action.

The first rule in the list, set up by the STK Terrain Server installer, specifies that all users, including anonymous, unauthenticated users, are allowed to do GET requests. In STK Terrain Server, GET requests cannot make modifications to the server, so this rule provides read-only access to everyone. To only allow specified users or groups to read data on the server, double-click the first rule in the list and choose a radio button to specify an allowed user or group.

Users and groups refer to Windows users or groups on the web server. They can be qualified with a Windows domain name if necessary.

The next rule in the list grants all users full access (read and write) to the STK Terrain Server application. We recommend that you double-click this rule and select a user or group in order to limit write access. You can designate multiple users or groups by inserting additional, similar rules at the same position in the rule list.

The third rule in the list denies access to all users who weren’t granted access by previous rules. The fourth and subsequent rules in the list, which could be different on your server, are inherited from the parent web site.

With this configuration complete, web browsers will automatically prompt for login credentials when attempting to perform an action within the STK Terrain Server application that does not allow anonymous access. In some cases, the login may be automatic (no explicit prompt) when you’re logged into the server as a user that is allowed access, or if your network has a Windows domain and your domain user is allowed access.

Troubleshooting Authentication

If authentication doesn’t work - in particular, if you’re using Windows authentication and the server will not accept your credentials - here are some things to try.

Configure the StkTerrainServerAppPool to use the NetworkService identity instead of the ApplicationPoolIdentity. This often helps because NetworkService is set up by default to work with Kerberos authentication on a Windows domain, whereas ApplicationPoolIdentity is not. In IIS Manager, select Application Pools in the tree on the left, and then click StkTerrainServerAppPool in the list. Click "Advanced Settings…" on the right. Under "Process Model" select "Identity" and then click the "…" button next to it. Under "Built-in account" select "NetworkService".

Configure Windows authentication to prefer NTLM over Negotiate. This may help when authenticating Windows domain users, because Negotiate will often choose to use Kerberos authentication in this scenario, which can be tricky to get working. Navigate back to the Authentication feature for the stk-terrain virtual directory in IIS Manager. Select Windows Authentication from the list and then click "Providers…" on the right. Move NTLM above Negotiate.

Configuring Web Service Authorization

In the above sections, we showed how the STK Terrain Server can restrict anonymous users to read only access. For some, this level of security may not be adequate enough, as any user can still retrieve information on tilesets and datasources defined on the STK Terrain Server. Authorization of users to only have permissions to request tiles and tileset metadata can be achieved by using the Url Authorization Feature for IIS.

The Url Authorization Feature for IIS must first be enabled on your server. On Windows Server 2008 and 2012, Url Authorization is installed using Server Manager. Navigate to the IIS pane, scroll down to the Role Services section, and click the "Add Role Services" button or select "Add Roles and Features" from the Tasks drop-down. The feature is found under Web Server (IIS), Web Server, Security.

On Windows Vista, 7, 8, and 8.1, authentication mechanisms are installed via "Turn Windows features on or off", under Internet Information Services, World Wide Web Services, Security.

With URL Authorization enabled for IIS, authorization can now be configured for each REST webservice. Open the Web.Config file located at the root of the stk-terrain install directory. Inside the configuration element, a REST webservice virtual location can be identified and assigned authorization control. The following example would restrict the use of localhost/stk-terrain/admin REST API to only users in the StkTerrainServerAdmins user group.

Users and groups refer to Windows users or groups on the web server. They can be qualified with a Windows domain name if necessary.

Following the pattern illustrated in the example above, the "path" attribute can be configured for authorization of the following admin REST API end points:

location path Endpoint Description
admin/datasources Returns json that defines the collection of datasources defined on the STK Terrain Server.
admin/datasources/{name} Returns the json that defines the configuration of a named datasource. Named datasources will inherit the authorization defined at the datasources level; defining authorization rules for a named datasource will override the authorization above.
admin/settings Returns json that defines the configuration settings for viewing a tileset.
admin/license Returns json that describes the STK Terrain Server license state.
admin/datasources/files Defines an interface for uploading files to a STK Terrain Server datasource.
admin/tilesets Returns json that defines the collection of tilesets defined on the STK Terrain Server. This web service allows for the discovery of tilesets on the server, but provides admin information about the tileset, including the directory location of the tileset and status on the incorporation of data sources into this tileset, including percent complete and the time elapsed to incorporate the data source.

The public REST API end points can also be configured for authorization control:

location path Endpoint Description
v1/tilesets Returns json that defines the collection of tilesets defined on the STK Terrain Server. This web service allows for the discovery of tilesets on the server, but does not include the additional admin datasource processing information.
v1/tilesets/{name}/tiles Root path of all Terrain Server tiles. For legacy Cesium applications, the v1 can be optional for tile and layer.json retrieval endpoints, however this unversioned REST API may be deprecated in the future. These legacy endpoints are
  • tilesets/{name}/tiles/layer.json
  • tilesets/{name}/tiles/{z}/{y}/{x}.terrain
tilesets/{name}/tiles Unversioned, legacy endpoint that maps to the same endpoint as v1/tilesets/{name}/tileset