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: Path | str | 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 indefinite.

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

[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 not   [2m│[0m
[2m│[0m                                set (default) the hostname is read from a     [2m│[0m
[2m│[0m                                config file                                   [2m│[0m
[2m│[0m [1;36m-[0m[1;36m-token[0m[1;36m-file[0m          [1;33mTEXT   [0m  Instead of authenticating via code based      [2m│[0m
[2m│[0m                                authentication flow you can set the path to   [2m│[0m
[2m│[0m                                the json file that contains a `refresh token` [2m│[0m
[2m│[0m                                containing a refresh_token key.               [2m│[0m
[2m│[0m [1;36m-[0m[1;36m-force[0m       [1;32m-f[0m      [1;33m       [0m  Force token recreation, even if current token [2m│[0m
[2m│[0m                                is still valid.                               [2m│[0m
[2m│[0m [1;36m-[0m[1;36m-timeout[0m             [1;33mINTEGER[0m  Set the timeout for login in secdonds, 0 for  [2m│[0m
[2m│[0m                                indefinite                                    [2m│[0m
[2m│[0m                                [2m[default: 30]                                [0m [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.

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.