Authentication using the freva-client library#

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

freva_client.authenticate(*, token_file: str | Path | None = None, host: str | None = None, force: bool = False, timeout: int | None = 30) → Token#

Authenticate to the host.

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

Parameters:

token_file (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.
host (str, optional) – The hostname of the REST server.
force (bool, default: False) – Force token recreation, even if current token is still valid.
timeout (int, default: 30) – Set the timeout, None for indefinate.

Returns:

Token

Return type:

The authentication token.

Examples

Interactive authentication:

from freva_client import authenticate
token = authenticate(timeout=120)
print(token)

Batch mode authentication with a refresh token:

from freva_client import authenticate
token = authenticate(token_file="~/.freva-login-token.json")

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
  --token-file TEXT  Instead of authenticating via code based authentication
                     flow you can set the path to the json file that contains
                     a `refresh token` containing a refresh_token key.
  -f, --force        Force token recreation, even if current token is still
                     valid.
  --timeout INTEGER  Set the timeout for login in secdonds, 0 for indefinate
                     [default: 30]
  -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.

In the process of token generation, you would want to store your token data securely in a file, and use it as a refresh token to create new ones, eventually:

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

For security reasons you cannot pass your password as an argument to the command line interface. This means that, in a non-interactive session such as a batch job, you will have two options:

Either use the valid token with --token-file <my_token_file>.
Or, if you want to create a new one, you will only be able to do it with help of an already pre-existing valid refresh token.
```
freva-client auth --token-file ~/.my_old_token.json > ~/.my_new_token.json
chmod 600 ~/.my_new_token.json
```

Warning

Avoid storing access tokens insecurely. Access tokens are sensitive and should be treated like passwords. Do not store them in publicly readable plaintext or in code repositories. Instead:

Use environment variables or secure storage (e.g. .netrc, OS keychains).
Rotate and expire tokens regularly if implementing long-running SPs.