Introduction
============

Many datasets at GEOFON contain *restricted* data.
By this, we mean that access is limited to those people authorised by the data provider, typically, the PI(s).
Who the PI authorises is their choice; we can help you request access if desired.
Sometime an entire seismic network is restricted; other times only a few stations or channels may be restricted.

To ensure that we do not serve restricted data to unauthorised people,
we must ask you to authenticate to our service - that is, present some
credentials which identify who you are.
You may use our services unauthenticated, but then we can only provide
you with open (unrestricted) data.

For Arclink service, we ask for your user name (typically, your e-mail address),
and serve data which has been encrypted using a password which was sent
to you previously.

This approach is not possible using FDSN web services (`fdsnws-dataselect`, etc).
Instead we use a token-based system.
The token is a cookie-like piece of data, containing identifying information, such as your name.

 #. The token is for your personal use, and only one is needed for all the different data sets at GEOFON that you may be entitled to access.
 #. The token is digitally signed by a trusted party [#foot-trusted]_,
    and has a fixed validity period.
 #. You present the token to the service's /auth method, at a URL such as
     https://geofon.gfz-potsdam.de/fdsnws/dataselect/1/auth

 #. If the digital signature is valid, a temporary account for /queryauth is created.
 #. You then use the /queryauth method to request data, instead of the usual /query method.

When a token expires, you simply go back to the trusted party to generate a new one.

FDSNWS authentication is also supported by the
`latest version of WebDC 3 <http://eida.gfz-potsdam.de/webdc3/?fdsnws=enabled>`_.

Below we show you:

 1. How to obtain credentials (via a token).
 2. How to use these to request data.

For advanced users, we provide some additional details
in :ref:`sec-auth-details`.
Information about the personal data we retain is also there.

 .. note::
     This is a new service, and we expect that there will be problems,
     misunderstandings, and gaps in the documentation.
     In case of difficulties, don't hesitate to contact us.
     The :ref:`sec-auth-faq` section may help you.


.. [#foot-trusted] What is a trusted party?
    Today, tokens are provided by the EIDA Authentication Service (EAS) at
    `https://geofon.gfz-potsdam.de/eas` .
    In the background we use a service which
    could act as a proxy to eduGAIN, in the case that your home institution allows
    it, or lets you create a local account. An eduGAIN Identity Provider
    serves as the trusted party - you give it, not us, your credentials,
    and it provides a token which we accept as proof of your
    identity. Both we and you trust the eduGAIN infrastructure
    to do this correctly.