Authentication#

Some functionality of the freva-rest API and the client library is only accessible after successful authentication. This authentication is realised with OAuth2 token creation. You can create new access and refresh tokens. Refresh tokens can be used to create new access tokens without needing to log in via username and password, thereby minimising the risk of exposing login credentials. Bear in mind that both login and refresh tokens have a limited lifetime.

Generally speaking, you have three options to interact with the authorization system:

via the REST API /api/auth/v2 endpoints
via the freva_client.authenticate() function
via the freva-client auth command-line interface

Using the restAPI endpoints#

The API supports token-based authentication using OAuth2. To obtain an access token, clients can use the /api/auth/v2/token endpoint by providing valid username and password credentials. The access token should then be included in the authorization header for secured endpoints.

POST /api/auth/v2/token#

Create an new login token from a username and password. You should either set a username and password or an existing refresh token. You can also set the client_id. Client id’s are configured to gain access, specific access for certain users. If you don’t set the client_id, the default id will be chosen.

Form Parameters:

username – The username for the login
password – The password for the login
refresh_token – The refresh token that is used to create a new token the refresh token can be used instead of authorizing via user creentials.
client_id – The unique identifier for your application used to request an OAuth2 access token from the authentication server, this form parameter is optional.
client_secret – An optional client secret used for authentication. This param. is optional and in most cases not needed

Status Codes:

200 OK – no error
401 Unauthorized – unauthorized

Response Headers:

Content-Type – application/json: access and refresh token.

Example Request#

POST /api/auth/v2/token HTTP/1.1
host: www.freva.dkrz.de

{
    "username": "your_username",
    "password": "your_password"
}

Example Request#

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6.."
    "token_type": "Bearer",
    "expires": 1722874908,
    "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUIiwia2lkIi.."
    "refresh_expires": 1722876408,
    "scope": "profile email address",
}

Code examples#

Below you can find example usages of this request in different scripting and programming languages

Shell
Python
gnuR
Julia
C/C++

curl -X POST https://www.freva.dkrz.de/api/auth/v2/token \
 -d "username=janedoe" \
 -d "password=janedoe123"

import requests
response = requests.post(
  "https://www.freva.dkrz.de/api/auth/v2/token",
  data={"username": "janedoe", "password": "janedoe123"}
)
token_data = response.json()

library(httr)

url <- "https://freva.dkrz.de/api/auth/v2/token"
response <- POST(
   "https://www.freva.dkrz.de/api/auth/v2/token",
   body = list(username = "janedoe", password = "janedoe123"),
   encode = "form"
)
token_data <- content(response, "parsed")

using HTTP
using JSON

response = HTTP.POST(
  "https://www.freva.dkrz.de/api/auth/v2/token",
  body = Dict("username" => "janedoe", "password" => "janedoe123")
)
token_data = JSON.parse(String(response.body))

#include <stdio.h>
#include <curl/curl.h>

int main() {
    CURL *curl;
    CURLcode res;

    curl_global_init(CURL_GLOBAL_DEFAULT);
    curl = curl_easy_init();
    if(curl) {
        struct curl_slist *headers = NULL;
        headers = curl_slist_append(headers, "Content-Type: application/x-www-form-urlencoded");

        curl_easy_setopt(curl, CURLOPT_URL, "https://www.freva.dkrz.de/api/auth/v2/token");
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
        curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "username=janedoe&password=janedoe123");

        res = curl_easy_perform(curl);
        curl_easy_cleanup(curl);
    }
    curl_global_cleanup();
    return 0;
}

—

GET /api/auth/v2/status#

Check the status of an access token.

Request Headers:

Authorization – The OAuth2 access token

Status Codes:

200 OK – no error
401 Unauthorized – unauthorized

Response Headers:

Content-Type – application/json: access and refresh token.

Example Request#

POST /api/auth/v2/status HTTP/1.1
host: www.freva.dkrz.de
Authorization: Bearer your_access_token

Example Request#

HTTP/1.1 200 OK
Content-Type: application/json

{
    "sub": "648692af-aaed-4f82-9f74-2d6baf96f5ea",
    "exp": 1719261824,
    "email": "jane@example.com"
}

Code examples#

Below you can find example usages of this request in different scripting and programming languages

Shell
Python
gnuR
Julia
C/C++

curl -X GET https://www.freva.dkrz.de/api/auth/v2/status \
 -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

import requests
response = requests.get(
  "https://www.freva.dkrz.de/api/auth/v2/status",
  headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
)
token_data = response.json()

library(httr)

response <- GET(
   "https://www.freva.dkrz.de/api/auth/v2/status",
   add_headers(Authorization = paste("Bearer", "YOUR_ACCESS_TOKEN"))
)
token_data <- content(response, "parsed")

using HTTP
using JSON

response = HTTP.get(
  "https://www.freva.dkrz.de/api/auth/v2/status",
  headers = Dict("Authorization" => "Bearer YOUR_ACCESS_TOKEN")
)
token_data = JSON.parse(String(response.body))

#include <stdio.h>
#include <curl/curl.h>

int main() {
    CURL *curl;
    CURLcode res;

    curl_global_init(CURL_GLOBAL_DEFAULT);
    curl = curl_easy_init();
    if(curl) {
        struct curl_slist *headers = NULL;
        headers = curl_slist_append(headers, "Authorization: Bearer YOUR_ACCESS_TOKEN");

        curl_easy_setopt(curl, CURLOPT_URL, "https://www.freva.dkrz.de/api/auth/v2/status");
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);

        res = curl_easy_perform(curl);
        curl_easy_cleanup(curl);
    }
    curl_global_cleanup();
    return 0;
}

—

Using the freva-client python library#

The freva-client python library offers a very simple interface to interact with the authentication system.

Client software freva evaluation system framework (freva):

Freva, the free evaluation system framework, is a data search and analysis platform developed by the atmospheric science community for the atmospheric science community. With help of Freva researchers can:

quickly and intuitively search for data stored at typical data centers that host many datasets.
create a common interface for user defined data analysis tools.
apply data analysis tools in a reproducible manner.

The code described here is currently in testing phase. The client and server library described in the documentation only support searching for data. If you need to apply data analysis plugins, please visit the

freva_client.authenticate(*, refresh_token: str | None = None, username: str | None = None, host: str | None = None, force: bool = False) → Token#

Authenticate to the host.

This method generates a new access token that should be used for restricted methods.

Parameters#

refresh_token: str, optional: Instead of setting a password, you can set a refresh token to refresh the access token. This is recommended for non-interactive environments.
username: str, optional: The username used for authentication. By default, the current system username is used.
host: str, optional: The hostname of the REST server.
force: bool, default: False: Force token recreation, even if current token is still valid.

Returns#

Token: The authentication token.

Examples#

Interactive authentication:

from freva_client import authenticate
token = authenticate(username="janedoe")
print(token)

Batch mode authentication with a refresh token:

from freva_client import authenticate
token = authenticate(refresh_token="MYTOKEN")

Using the command line interface#

Token creation and refreshing can also be achieved with help of the auth sub command of the command line interface

freva-client auth --help

Results

[1m                                                                                [0m
[1m [0m[1;33mUsage: [0m[1mfreva-client auth [OPTIONS][0m[1m                                            [0m[1m [0m
[1m                                                                                [0m
 Create OAuth2 access and refresh token.                                        
                                                                                
[2m╭─[0m[2m Options [0m[2m───────────────────────────────────────────────────────────────────[0m[2m─╮[0m
[2m│[0m [1;36m-[0m[1;36m-host[0m                   [1;33mTEXT   [0m  Set the hostname of the databrowser, if    [2m│[0m
[2m│[0m                                   not set (default) the hostname is read     [2m│[0m
[2m│[0m                                   from a config file                         [2m│[0m
[2m│[0m                                   [2m[default: None]                           [0m [2m│[0m
[2m│[0m [1;36m-[0m[1;36m-username[0m       [1;32m-u[0m      [1;33mTEXT   [0m  The username used for authentication.      [2m│[0m
[2m│[0m                                   [2m[default: runner]                    [0m      [2m│[0m
[2m│[0m [1;36m-[0m[1;36m-refresh[0m[1;36m-token[0m  [1;32m-r[0m      [1;33mTEXT   [0m  Instead of using a password, you can use a [2m│[0m
[2m│[0m                                   refresh token. refresh the access token.   [2m│[0m
[2m│[0m                                   This is recommended for non-interactive    [2m│[0m
[2m│[0m                                   environments.                              [2m│[0m
[2m│[0m                                   [2m[default: None]                           [0m [2m│[0m
[2m│[0m [1;36m-[0m[1;36m-force[0m          [1;32m-f[0m      [1;33m       [0m  Force token recreation, even if current    [2m│[0m
[2m│[0m                                   token is still valid.                      [2m│[0m
[2m│[0m                  [1;32m-v[0m      [1;33mINTEGER[0m  Increase verbosity [2m[default: 0][0m            [2m│[0m
[2m│[0m [1;36m-[0m[1;36m-version[0m        [1;32m-V[0m      [1;33m       [0m  Show version an exit                       [2m│[0m
[2m│[0m [1;36m-[0m[1;36m-help[0m                   [1;33m       [0m  Show this message and exit.                [2m│[0m
[2m╰──────────────────────────────────────────────────────────────────────────────╯[0m

You can create a token using your user name and password. For security reasons you can not pass your password as an argument to the command line interface. This means that you can only create a new token with help of a valid refresh token in a non-interactive session. Such as a batch job.

Therefore you want to store your token data securely in a file, and use the refresh token to create new tokens:

freva-client auth -u janedoe > ~/.mytoken.json
chmod 600 ~/.mytoken.json

Later you can use the jq json command line parser to read the refresh token from and use it to create new access tokens.

export re_token=$(cat ~/.mytoken.json | jq -r .refresh_token)
freva-client auth -r $re_token > ~/.mytoken.json