+ + +
+
+ +
+
+ +
+ +
+ + + + +
+ +
+ + +
+
+ + + + + +
+ +
+

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 parameters is optional an in most cases not neeede

    • +
+
+
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_in": 300,
+    "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUIiwia2lkIi.."
+    "refresh_expires_in": 1800,
+    "scope": "email",
+    "not-before-policy": 0
+}
+
+
+
+
+

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                         │
+│                                   [default: None]                            │
+│ --username       -u      TEXT     The username used for authentication.      │
+│                                   [default: runner]                          │
+│ --refresh-token  -r      TEXT     Instead of using a password, you can use a │
+│                                   refresh token. refresh the access token.   │
+│                                   This is recommended for non-interactive    │
+│                                   environments.                              │
+│                                   [default: None]                            │
+│ --force          -f               Force token recreation, even if current    │
+│                                   token is still valid.                      │
+│                  -v      INTEGER  Increase verbosity [default: 0]            │
+│ --version        -V               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
+
+
+
+
+ + +
+ + + + + + + +
+ + + +
+ + +
+
+ On this page +
+
+ +
+ + +
+
+ +
+ +