Restricting Access to Datasets in the TDS

1. Restrict by URL using Tomcat

You can use the built in Tomcat mechanism to restrict a pattern of URLs, by adding <security-constraint> elements into the web.xml file. The following fragment will force all URL accesses that have the urlPattern to authorized users with the role roleName. The <transport-guarantee> elements forces a switch to using an SSL socket.

  <security-constraint>
    <web-resource-collection>
      <web-resource-name>restrict by URL</web-resource-name>
      
  <url-pattern>urlPattern</url-pattern>
      <http-method>GET</http-method>
    </web-resource-collection>
    <auth-constraint>
      
  <role-name>roleName</role-name>
    </auth-constraint>
    <user-data-constraint>
      <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
  </security-constraint>

A concrete example might look like:

  <security-constraint>
    <web-resource-collection>
      <web-resource-name>restrict by URL</web-resource-name>
      <url-pattern>/dodsC/dataRoot/*</url-pattern>
      <http-method>GET</http-method>
    </web-resource-collection>
    <auth-constraint>
      <role-name>tiggeRole</role-name>
    </auth-constraint>
    <user-data-constraint>
      <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
  </security-constraint>

Note that you don't include /thredds in the url-pattern. Also note that if you are using multiple data services, you must include each service's URL pattern, for example:

    <web-resource-collection>
      <web-resource-name>restrict by URL</web-resource-name>
      <url-pattern>/dodsC/testEnhanced/*</url-pattern>

  <url-pattern>/fileServer/testEnhanced/*</url-pattern>
      <http-method>GET</http-method>
    </web-resource-collection>

Using Tomcat to provide restricted access works well when you want to restrict your entire site to a single set of users. When you want to give access to different datasets to different users, you must understand in some detail what the URLs look like.

2. Restrict by Dataset using TDS Catalog

A more fine-grained approach is to modify the dataset elements in the TDS configuration catalog. To do this, you add an attribute on a dataset or datasetScan element in the TDS catalog, eg restrictAccess="roleName". All services that use that dataset will be restricted to users with the named role.

When a client tries to access a restricted dataset, it is redirected to a URL that triggers a security challenge. If the challenge is successful, the client is redirected back to the original dataset URL, except now it has an authenticated session, represented by a session cookie passed to the client. For subsequent requests by the same client, no authentication is needed as long as the session remains valid.

The default TDS configuration uses Digest authentication. By modifying web.xml, the server administrator can require that authentication be done differently, for example require SSL (changes to the TDS web.xml must be manually propagated to new versions of the TDS when upgrading). You can also plug in your own Authentication.

To access any restricted dataset that a TDS might serve, a client such as a browser, OPeNDAP enabled application, or WCS client, must be able to:

follow redirects, including circular redirects.
switch to SSL and back.
perform Basic and Digest authentication
answer security challenges with the appropriate user name and password.
return session cookies.

Configuring Restricted Datasets

1. Decide on distinct sets of datasets that need to be restricted. For each set, choose a name called a security role. Avoid special characters in the role names, especially /"><' and space. For example, suppose you have three sets of restricted data that you call ccsmData, fieldProject, tiggeData.

2. Add each role to the ${tomcat_home}/conf/tomcat-users.xml file, along with the restrictedDatasetUser role:

  <role rolename="restrictedDatasetUser"/>
  <role rolename="ccsmData"/>
  <role rolename="fieldProject"/>   
  <role rolename="tiggeData"/>

If you only have one set of datasets that you want to restrict, you can use just the restrictedDatasetUser (ie you don't need to have multiple roles). However you must always use the name restrictedDatasetUser.

3. Add each user who should have authorization to the tomcat-users.xml file. A user may have multiple roles, and must always have the restrictedDatasetUser role, eg:

  <user username="john" password="dorkology" roles="ccsmData,restrictedDatasetUser"/>
  <user username="tiggeUser" password="flabulate" roles="tiggeData,restrictedDatasetUser"/>
  <user username="luci" password="designated" roles="fieldProject,tiggeData,restrictedDatasetUser"/>

Make sure that none of these restrictedDatasetUsers have any of the "secure" roles such as tdsConfig, manager, or admin. (Here's why). In this example we are storing passwords in cleartext, but you are advised to store passwords in digest form.

You can also manage users and roles with the tomcat admin application, if you have installed it.

4. In the TDS configuration catalogs, add restrictAccess={security role} attributes to the dataset or datasetScan elements. This will also restrict access to all children of those dataset. Example:

<?xml version="1.0" encoding="UTF-8"?>
<catalog name="TDS Catalog" xmlns="http://www.unidata.ucar.edu/namespaces/thredds/InvCatalog/v1.0">

  <service name="thisDODS" serviceType="OpenDAP" base="/thredds/dodsC/" />
  <datasetRoot path="test" location="/data/testdata/"/>
 
  <dataset name="Test Single Dataset" ID="testDataset" serviceName="thisDODS"
      urlPath="test/testData.nc" restrictAccess="tiggeData">

    <dataset name="Nested" ID="nested" serviceName="thisDODS" urlPath="test/nested/testData.nc" />
  </dataset>

  <datasetScan name="Test all files in a directory" ID="testDatasetScan"
      path="testAll" location="/data/testdata" restrictAccess="ccsmData" >
    
    <metadata inherited="true">
      <serviceName>thisDODS</serviceName>
    </metadata> 
 
  </datasetScan>
</catalog>

The dataset with ID testDataset, as well as its child dataset nested are restricted, as are all the datasets generated by the datasetScan. Users can see these datasets in the catalogs, but when they try to access the data, they will be challenged.

4. After restarting Tomcat, use a browser to navigate to a restricted dataset. You should be prompted for a username and password. This must match a user that has a role matching the restrictAccess attribute on the dataset.

Troubleshooting:

If your browser has cached credentials which are wrong, it will simply send them without giving you a chance to renter. Firefox, at least, doesn't seem to have a way to clear this cache. Try exiting all instances of the browser and restarting it.
You are denied access when you enter in your username/password, but subsequent tests allow you to access the data. Make sure that your user has both the restrictedDatasetUser and the particular security role needed for that dataset.

Requiring SSL authentication

To require authentication to be done over SSL, do everything in the default configuration above, plus the following:

1. Enable Tomcat Security / SSL

You must enable Secure Sockets. See the TDS Remote Management guide.

We also recommend that you store Digest Passwords. See the Tomcat Security guide.

2. Modify the TDS web.xml file

After thredds.war is expanded, edit ${tomcat_home}/webapps/thredds/WEB-INF/web.xml.

2.1 Find the following element:

  <security-constraint>
    <web-resource-collection>
      <web-resource-name>restrictedAccess</web-resource-name>
      <url-pattern>/restrictedAccess/*</url-pattern>
      <http-method>GET</http-method>
    </web-resource-collection>
    <auth-constraint>
      <role-name>restrictedDatasetUser</role-name>
    </auth-constraint>
  </security-constraint>

Add the following to it:

  <security-constraint>
    <web-resource-collection>
      <web-resource-name>restrictedAccess</web-resource-name>
      <url-pattern>/restrictedAccess/*</url-pattern>
      <http-method>GET</http-method>
    </web-resource-collection>
    <auth-constraint>
      <role-name>restrictedDatasetUser</role-name>
    </auth-constraint>
    
  <user-data-constraint>
 <transport-guarantee>CONFIDENTIAL</transport-guarantee>
 </user-data-constraint>
  </security-constraint>

2.2 Find the following element:

   <!-- Restricted Access (using Tomcat) -->
  <servlet>
    <servlet-name>RestrictedDataset</servlet-name>
    <servlet-class>thredds.servlet.restrict.RestrictedDatasetServlet</servlet-class>

 	  <init-param>
      <param-name>Authorizer</param-name>
      <param-value>thredds.servlet.restrict.TomcatAuthorizer</param-value>
    </init-param>

    <init-param>
      <param-name>useSSL</param-name>
      <param-value>false</param-value>
    </init-param>

    <init-param>
      <param-name>portSSL</param-name>
      <param-value>8443</param-value>
    </init-param>

    <load-on-startup>2</load-on-startup>
 </servlet>

Change useSSL to true, and change portSSL to the correct value if it is not 8443.

3. Restart Tomcat and Test

Troubleshooting:

Your browser may tell you that your server certificate has expired. Create a new one, and restart Tomcat.
Your browser will cache credentials (passwords), which may interfere with your ability to test these features. Turn password saving off, delete saved passwords, and restart your browser if needed.

Unique Realm Name

If you are not using SSL, it is more secure to have a Realm name unique to your server, then to use the default THREDDS Data Server Realm name, so we recommend that you change it in the web.xml file. This name is presented to the user during authentication, so it should be descriptive and include the hostname, for example:

  <login-config>
    <auth-method>DIGEST</auth-method>
    <realm-name>Unidata IDD Server (motherload.ucar.edu))</realm-name>
  </login-config>

This document is maintained by Unidata and was last updated October 2012. Send comments to THREDDS support.