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:
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:
Status Codes:
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

Usage: freva-client auth [OPTIONS]

  Create OAuth2 access and refresh token.

Options:
  --host TEXT               Set the hostname of the databrowser, if not set
                            (default) the hostname is read from a config file
  -u, --username TEXT       The username used for authentication.  [default:
                            runner]
  -r, --refresh-token TEXT  Instead of using a password, you can use a refresh
                            token. refresh the access token. This is
                            recommended for non-interactive environments.
  -f, --force               Force token recreation, even if current token is
                            still valid.
  -v                        Increase verbosity  [default: 0]
  -V, --version             Show version an exit
  --help                    Show this message and exit.

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