Version 17 (modified by antonio, 5 years ago) (diff)


What is TAP

The aim of the THREDDS Access Panel (TAP) project lies in the idea of solving the huge problem existing in the Unidata THREDDS application with the management of users, roles and dataset access. The Thredds user authentication is delegated to Tomcat Basic which gets users and roles from a given Realm. In order to authorize users, THREDDS checks whether the dataset is restricted and if so, gets the user roles to make a decision. TAP manages the datasource mentioned to control user access to protected datasets.

Environment setup

TAP and THREDDS get users and roles from a database created specifically to model all the entities and processes involved. The main idea is to include easily a database instance to work with. Derby network allow users to access db instances even from outside when they are running and most people are familiar with it. To accomplish this step you need four main components:

  • Derby library
  • Derby database
  • Apache Tomcat 7.0.59
  • jre 1.7.0_75

Attached is a preconfigured environment which includes a lib folder (appz) , the Apache Tomcat 7.0.59 with thredds and TAP deployed and the jre 1.7.0_75

If you want to build it by yourself, we suggest to follow these steps:

  1. Create a deployment folder (eg. deployment_test)
  1. Create an appz folder in deployment_test to place libraries.
  1. Extract Derby library in /deployment_test/appz
  1. Extract Tomcat 7.0.59 or paste the customized Tomcat provided.
  1. Place the Derby DB folder (derbydb) in $CATALINA_HOME/content/data

Derby setup

To start Derby successfully add a socket permission in JAVA 7 by including in $JRE_HOME/lib/security/java.policy the following line:

permission "HOST:DERBY_PORT", "listen,resolve";

Start derby

$JRE_HOME/bin/java -jar $PATH_TO_DERBY_LIB/db-derby- server start -p DERBY_PORT -h &

Tomcat setup

Although attached is a customized tomcat ready to run, you can use another and configure it following these steps

Expose our datasource in Tomcat

Tomcat gets users and roles from conf/tomcat-users.xml by default. We are going to change this in order to get users and roles from a given database. First of all, include both derbyclient.jar and derbynet.jar in $CATALINA_HOME/lib. After doing that, we need to add a new resource called “jdbc/admin” in GlobalNamingResources?:

	  <Resource name="jdbc/adminDB" auth="Container" type="javax.sql.DataSource" 
		validationQuery="SELECT count(*) FROM users" maxActive="20" maxIdle="10" username="admin" password="adm!n"
		url="jdbc:derby://YOUR_HOST:YOUR_PORT/../content/data/derbydb" readOnly="false"/>

Set the realm

A Realm is a “database” of usernames and passwords that identify valid users of a web application (or set of web applications), plus an enumeration of the list of roles associated with each valid user. The servlet container will be connected to the database and it also be aware of the username and the corresponding roles. Define this realm inside <Engine> in your server.xml:

<Realm className="org.apache.catalina.realm.DataSourceRealm" digest="MD5" debug="0" dataSourceName="jdbc/adminDB" 
    userTable="USERS" userNameCol="USERNAME" userCredCol="PASSWORD" userRoleTable="V_USERS_ROLES" roleNameCol="ROLENAME"/>

Expose the datasource as JNDI resource

TAP gets the datasource from the JNDI resource "jdbc/adminDB". Add to $CATALINA_HOME/conf/context.xml the following line:

<ResourceLink global="jdbc/adminDB" name="jdbc/adminDB" type="javax.sql.DataSource"/>

Start Tomcat

We strongly recomend you before run Tomcat, set JAVA_OPTS="-Xms256m -Xmx4096m -XX:+DisableExplicitGC -XX:PermSize=256m -XX:MaxPermSize=512m -XX:-UseGCOverheadLimit"

Run Tomcat


Check the Initialization

tail -f /deployment_test/apache-tomcat-7.0.59/logs/catalina.out

Initial TAP setup

You need to configure some files in order to adapt it for your needs. Shutdown Tomcat and go to /deployment_test/apache-tomcat-7.0.59/webapps/tap

Configure WEB_INF/classes/

recaptcha.verificationurl =
recaptcha.privatekey = YOUR_RECAPTCHA_PRIVKEY
recaptcha.publickey = YOUR_RECAPTCHA_PUBKEY

tap.baseurl = http://localhost:8080/tap =, #They will receive emails if people join groups =

You need to create a recaptcha and set both private and public keys in the previous file. You also need to set your base url like localhost:8080/tap or yourhost/tap, the managers emails which allow people to keep in touch of the group events (when user wants to join a group, etc)

Configure WEB-INF/classes/

mail.port = port_number = email_host

You can change the email templates optionally in WEB-INF/classes/templates

You can change the messages optionally in WEB-INF/classes/locale/

Thredds and TAP deployment

Start the Tomcat instance and the Derby network instance. If Thredds is not able to start due to a directory error, please create a folder called “thredds” in $CATALINA_HOME/content to solve that issue.

First steps in TAP

When the initial setup is finished TAP is ready to register users, send confirmation emails, let people join groups, etc. With your preconfigured TAP there is a Derby db with demo data. If you have deployed successfully both Thredds and TAP and they are running, go to http://yourhost/tap and log in with the following credentials:

username: admin
password: adm!n

You will find new admin options in the main menu. From there you can control users, roles, groups, dataset policies and send messages to your users or a set of them.

System users


  1. User roles: Add or remove user roles directly.
  2. User groups: Add or remove user groups direcly (Some requires user acceptance)
  3. Edit record: Edit user details.
  4. Delete record: Remove a user from the app and the relations with roles and groups.

System groups


  1. Group roles: Add or remove roles from the group.
  2. Edit record: Edit group details.
  3. Delete record: Remove a group from the app and the relations with roles and users.

System roles


  1. Policy assignment: Add or remove policies from the role/dataset.
  2. Edit record: Edit role details.
  3. Delete record: Remove a role from the app and the relations with groups and users.

Roles have metadata. You can insert the following keys to show them:

  1. url
  2. type
  3. isPrivate
  4. label



System policies


  1. Edit record: Edit policy details.
  2. Delete record: Remove a policy from the app and the relations with roles.

System messages

You can send messages to your users filtering by groups, newsletter, admins, etc.

The messages you send are customized. You don't need to include Hi, Dear nothing or goodbye. The template is the following:

Dear admin,


Best regards,

TAP Manager

Thredds restricted dataset

Thredds allows users to restrict dataset access in two different ways:

  • URL restriction using Tomcat: difficult to maintain. You need to restrict every dataset by URL and set the role in the web.xml
  • Dataset restriction using TDS Catalog: most commonly used by adding an attribute on a dataset or datasetScan element in the TDS catalog. Eg, restrictAccess=”roleName”

If you set the mentioned attribute in a Dataset, users need two roles to access it: restrictedDatasetUser and roleName. That means, every user who wants to access to a restricted dataset needs the restrictedDatasetUser role by default and also the role of the dataset. Here is where TAP does the job for you.

Restrict dataset access

As we mentioned, TAP manages users, roles, groups, policies and their relationships. It is a common scenario to have a dataset with policies that prevent you of doing an illegal use of the data. In the given example you will find the default Thredds catalog example. The first step is to protect the dataset:

<dataset name="Test Single Dataset" ID="testDataset"
           serviceName="dap"  urlPath="test/" dataType="Grid" restrictAccess="testDataset"/>

When a user tries to access this dataset, the Thredds authorizer expects to find the roles "testDataset" and "restrictedDatasetUser" in the user's granted authorities.

Allow access to a restricted dataset from TAP

To allow access to the previous dataset, create the role in /tap/admin/roles "Add new record":

Fill the form:

  • Name: testDataset
  • Description: a description of the dataset
  • Restricted: True if you want to moderate its access. Users will wait until a confirmation from an Admin or manager
  • Dataset: True in this case. If you want to create an internal role in TAP set to false.

Create a policy in /tap/admin/policies "Add new record" :

Fill the form

  • Description: Description of the policy
  • Disable policy: ignore this in the creation. If you edit the policy and you want users accept again the agreement, set to true.
  • Agreement: You can paste html directly by clicking in the source button.

Create a Group in /tap/admin/groups "Add new record":

After creating the Policy, asociate it with the dataset (role) testDataset:

Fill the form

  • Name: TEST_GROUP
  • Description: Description of the group
  • Is project: If the group represents a project like EUPORIAS, VALUE, CORDEX...
  • Coordinator: If you want to delegate the user acceptance. TAP will send an email to the coordinator containing two links: accept or reject the user group request.

After creating the group, it is necessary to asociate the dataset(role) testDataset to the group:

Hidden modes selection

Show dataset select to find groups which include selected datasets:


Show matched groups filtered by a given dataset:


Select groups




If you find any issue, problem or make a comment, please drop us a ticket!!.

You can submit the ticket anonymously, but if you want to receive notifications on updates and feedbacks you can provide your e-mail address in the ticket form.

This is the list of tickets, so far:

Ticket Summary Type
#259 Notificación al administración nuevas altas enhancement
#260 Registration problem support
#261 Country list in registration panel defect
#265 En la pagina de error de autorización no se captura bien el role necesario defect
#267 Conexión caducada defect
#275 Motivation field in the login form enhancement
#314 Pagina "rara" al resetear el password defect
#320 Ocultar roles no necesarios enhancement
#321 Modificar página de registro enhancement
#324 Problemas con el loginfailed defect
#331 Institution field allows more than 35 characters defect
#335 Propuestas de mejora para el TAP: visibilidad de roles enhancement
#336 crear un rol specs enhancement
#337 modification of the ECOMS-UDG policy enhancement
#376 Problem changing password defect
#387 Unable to change my password support
#388 Mecanismo de contacto con usuarios de TAP [Incidencias] enhancement
#389 Redefinir el envío de correos para que queden los mensajes más claros enhancement
#401 User list orderingesn't work defect
#403 Incluir botón de ver policies en los datasets de /datasets enhancement
#404 Servicio email cambiar sendGroupAuthorizationResponseEmail defect
#405 Mostrar los terms of use en un jquery dialog enhancement
#406 Poder asignar grupos tipo TAP_USER desde el panel de Admin defect
#407 Modificar la ventana de admin de los grupos de usuario. enhancement
#408 Solucionar encoding UTF-8 en las plantillas defect
#409 Cambiar mensaje de updatePolicy defect
#410 Incluir username en el correo de Reset password defect
#411 Asunto mal generado en email de DatasetAcceptance defect
#412 Fallo en el datasets.js. Necesario especificar el rolename defect
#413 Eliminar los botones de policies y datasets y que salgan en el selector todos los grupos defect
#415 Mensaje erróneo al añadir una policy a un dataset defect
#436 broken link defect
#577 En agreements cortos no salta el scroll de la ventana por lo que no se pueden aceptar las condiciones defect
#889 Improve TAP welcome page enhancement
#1912 Avoid special and blank characters defect
#1914 Comprobar que no se introduzcan espacios en blanco ni caracteres extraños en el campo username del registro defect
#1915 Modificar My Account (cambio de password, cambio de email, datos...) enhancement
#1916 The dialogs are disappearing when they are dragged defect
#1917 The radio buttons groups are not independent defect
#5908 The new policy dialog needs to force obligatory fields support
#5909 The link dialog for the HTML editor behaves weird support
#5910 Simplifying the form of the TAP registration enhancement
#5911 Incluir campo búsqueda en la tabla de usuarios enhancement
#5917 El grupo TAP_ADMIN interpreta que sus roles son datasets con policies defect
#5918 Agregar nuevos campos de información a los datasets enhancement
#5919 Cambiar mensajes en el panel de asignación de grupos defect
#5920 Mejorar validación del registro y aumentar el tamaño del campo Institution defect
#5923 Integrar los catalogos thredds de los datasets en el TAP enhancement
#5924 The sign-up button in the membership authorization doesn't work defect
#5926 Navbar y footer cortan vista de ventana modal en ventanas estrechas verticalmente defect
#5928 report information about users, projects and institutions enhancement
#5929 In the policy acceptance dialog, the accept button it's overlapped defect
#6113 Field Description max length when creating a group defect
#6114 TAP does not allow to assign roles to a group defect
#6117 Show dataset URL to allow access from R enhancement

Attachments (13)