Handling Testbed Specific Terms & Conditions (i.e. handling GDPR)

Testbed Specific Terms & Conditions (T&C)

Each testbed needs to have a site, with Testbed Specific Terms & Conditions. This is not necessarily hosted on the same domain as the AM, but that is possible and not a bad idea.

The basic requirements for such site are that they store if a user has consented to the T&C. So some form of DB is typically needed. When a user has not yet consented, the testbed can choose to disallow the user access. For this functionality, the testbed AM needs to access the consent DB.

Users need to identify themself to T&C sites, the only logical method of doing is, is using the fed4fire method: https client certificates (= X509 certificates used in SSL client authentication).

jFed support for Testbed Specific Terms & Conditions (T&C)

jFed has extensive support for sites with Testbed Specific Terms & Conditions. Testbed Specific T&C sites can integrate with jFed, to do this, T&C sites need to be registered in the jFed central config. No more is required.

Once this is done, jFed will show a link to the T&C site when a new experiment on the testbed is started. jFed also shows the user if he has already approved the terms or not.

Additionally, T&C sites can integrate further with jFed, by using jFed specific javascript, to:

  • Detect if they are running inside jFed: if (window.jfed)
  • Report to jFed if the user has consented (and for how long), or has declined the T&C: jfed.decline(); and jfed.approveWithDateISO8601(\"2018-05-19T13:05:00+02:00\"); (and other date options)
  • Request jFed to close the browser window: jfed.close();

As mentioned, jFed also works with sites that do not use any of the specific javascript. In this case, jFed will open the site in a window, and when it is closed will assume that the user has accepted the T&C.

To make this all work, the jFed central config contains for each testbed:

  • The URL of the site
  • The version number of the T&C site
  • The default approval expiration period (typically 1 year)
  • (The “accept subject”, this is an advanced feature which is “USER” by default)

Once a user has opened a T&C site through jFed, jFed stores the approval (or decline) of it detects (or assumes). It stores:

  • The URL of the site
  • The data until the approval is invalid. (This is given by the site using javascript. If not, the value in the central jFed config for the testbed is used.)
  • The version number stored in the cental jFed config for the testbed.
  • The user logged in to jFed

Note that only the T&C URL is stored, NOT the testbed. This means that testbeds can share the same T&C site. If the version number of the T&C site is updated in the central jFed config, all jFed users will see that they need to re-approve the terms.

jFed T&C integration javascript details

When jFed loads the T&C site, it is useful to let jFed know if the user has already accepted the T&C before, or not. However, when the site javascript runs, jFed has not yet had time to inject its code into the site. To solve this, you can use this method:

function initJFed() {
  if (window.jfed && window.jfed.decline) {
      //Here, you would check if the user has accepted the terms and conditions, or not.
      //if the user has accepted, let jFed know
      //window.jfed.approve(); //uses default timeframe configured in the jFed central config

      //if the user hasn't accepted yet, let jFed know
      window.jfed.decline();
  }
}

//run this to automatically contact jFed when its javascript becomes available
if (window.jfed) {
  initJFed();
} else {
  //window.jfed is not (yet) available
  //trick to make browser call  initJFed() when window.jfed becomes available.
  Object.defineProperty(window, 'jfed', {
    configurable: true,
    enumerable: true,
    writeable: true,
    get: function() {
      return this._jfed;
    },
    set: function(val) {
      this._jfed = val;
      initJFed();
    }
  });
}

There are multiple methods to signal to jFed that the user has accepted the T&C:

//report approval of the T&C to jFed (without specifying end date of approval)
//(This will cause the default duration configured for this specific testbed in the central jFed config to be used)
jfed.approve();

//report approval of the T&C to jFed, and specify a date in ms since epoch  (javascript Date.getTime() returns this)
jfed.approveWithDateInMillisecondsSinceEpoch(Date.now()+(24*3600*30*1000));

//report approval of the T&C to jFed, and specify the relative date in days from now
jfed.approveDaysFromNow(7);

//report approval of the T&C to jFed, and specify a data in ISO8601 format (RFC3339 is a subset of ISO8601)
jfed.approveWithDateISO8601(\"2018-05-19T13:05:00+02:00\");

You can also report that the T&C are not accepted:

//report decline of the T&C to jFed
jfed.decline();

You can also request jFed to close the browser window:

//close the jFed T&C window from within javascript
jfed.close();

When something goes wrong, and no javascript is used, jFed reverts to the fallback. This means that when you close the window, jFed will assume that the user has accepted the T&C. Because of this, it’s not a bad idea to initially call jfed.decline();.

Parts of a T&C site

There are 3 parts that make up a T&C site:

  • Part 1: The “T&C frontend website”, which serves the html page to the browser, is thus accessible through https, and identifies users.
  • Part 2: The “Acceptance DB web api”: A web api to store if users acceptance of the T&C. This links the AM and the T&C frontend website.
  • Part 3: The AM, which checks if the T&C is accepted for the current user.

There are many ways to seperate or combine these parts. Some examples:

  • Scenario A: Part 1 can be hosted on a regular webserver (apache, nginx) and be made up of only html, css and javascript. Part 2 is a stadalone web api running on a different part of the website, for example it could be a python “flask” based web api running on a seperate port, to which the main website proxies. The AM contains part 3 which could call the acceptance DB web api to determine if a user has accepted the T&C.
  • Scenario B: Part 1 and part 2 combined can be a php website with a DB behind it. The T&C frontend website and “Acceptance DB web api” are tightly integrated in this case. In this scenario, part 3 could be code in the AM that calls the DB directly to determine if a user has accepted the T&C.
  • Scenario C: All 3 parts can be integrated directly into the AM. The AM thus has to serve a website in addition to the AM API.

Example: Standalone “Acceptance DB web api”

(This is scenario A, where part 2 can be fully seperated from part 1 and 3)

A standalone “Acceptance DB web api”:

  • Use https with client authentication enabled. Since the site has no purpose without a valid user, it makes sense to make SSL user authentication mandatory (this is an SSL setting).
  • The web api must be configured to allow users of the fed4fire authority access. (This is done by trusting the root certificate for wall2 in the server config)
  • The web api must extract the user URN from the certificate used to authenticate.
  • When a user signals decline or approval of the T&C using a call, this decision must be stored in a DB at the server.

The technology chosen for the web api (php, python, java, …) and the specific DB used are up to the testbed to decide.

Here is a possible API:

  • GET /terms_conditions/accept returns a JSON object in the form:

    {
  "accept": true,
  "testbed_access": true,
  "user_urn": "urn:publicid:IDN+authtld+user+username",
  "until": "2020-02-13T14:44:44.944825+00:00"
}

  • PUT /terms_conditions/accept is used to register accept or decline to the T&C. The same form of JSON object is used, but the “user_urn”, “until” and “testbed_access” fields do not have to be sent (they are set by the web api).

  • Optional: DELETE /terms_conditions/accept the user explicitly declines all terms. Any acceptance record will be removed from the DB (So and all mention of the user can be removed as well).

Our github has an example API in python

Example: Standalone T&C site

(This is scenario A, where part 2 can be fully seperated from part 1 and 3)

(We might add an example of such a standalone site in the future)

Optionally, this site can use the jFed T&C integration javascript mentioned above.

Our github has a minimalistic example site

Example: AM with T&C site built in

(This is scenario C)

It’s also possible to integrate the site directly in the AM code. One of the advantages is that the site can then easily run at the same domain and port of the AM. The SSL authentication is also already configured as the AM requires the same.

To demo this, we’ve modified a GCF based site, the docker AM. Looking at these changes, you should be able to modify any gcf based site in the same way. The main files for this addon are here: https://github.com/wvdemeer/docker-am/tree/master/gcf_docker_plugin/terms_conditions The exact changes that were needed can be seen here: https://github.com/open-multinet/docker-am/compare/master…wvdemeer:master

Note that these changes require changes to the geni-tools repository (“geni-tools” submodule). The needed changes can be found in this branch: https://github.com/wvdemeer/geni-tools/tree/feature-cust-req-hand-cls (There is a pull request to pul lthese changes into geni-tools, so if that is closed, this step won’t be needed: https://github.com/GENI-NSF/geni-tools/pull/927)

Add T&C site info to central jFed config

Send us the following info:

  • What is the URL of the T&C site for your testbed?
  • Do these T&C need to be approved per user? Or per project or even slice? (we recommand per user if possible)
  • For per user approval, how long does the approval remain valid (i.e. how long before the user need to re-approve)? (in days)

We will add this info to the central jFed config, so that jFed will send users to the T&C site when they start an experiment.

In case you update the conditions on the T&C site, let us know. We can change the version in the config, which will cause jFed to require all users to visit the T&C site again.

Technical details: We add the following to the testbed config:

{
    "gdprInfo": {
        "grpdUrl": "https://example.com/terms_conditions/index.html",
        "acceptPeriodInDays": 365,
        "acceptSubject": "USER",
        "version": "1",
        "@type": "GDPRInfo"
      }
}

Here’s an example: https://flsmonitor-api.fed4fire.eu/testbed/iminds-docker

Make the AM reject users that did not approve the Terms & Conditions

It should be sufficient to only add a check to the Allocate call.

In case the user is not known to have approved the T&C of the testbed, we strongly recommend using this error message:

{
   "output": "[T&C-APPROVAL-MISSING] Approval of the Terms & Conditions is required in order to use this testbed. Please visit https://example.com/termsandconditions",
   "code": { "geni_code": 7 }
}

Notes:

  • The above is a JSON representation of the XML-RPC reply, the actual reply is off course in XML. (But JSON is much easier to read.)
  • geni_code 7 is used. This code is the general code for “REFUSED” “Operation Refused”
  • Be sure to include “[GDPR-CONSENT-MISSING]” for automatic detection of this error by jFed. jFed can then show the appropriate error dialog.
  • It is also important to include a human readable message, and a link to the actual terms and conditions of the testbed. This is essential for users that do not use jFed.
  • The value field is ommitted above, but it may be included. It is optional because this is an error reply.
  • An AM may optionally include an am_type and am_code. You are free to use what you want for these.