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

                                                                                
 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.               │
│ --force       -f               Force token recreation, even if current token │
│                                is still valid.                               │
│ --timeout             INTEGER  Set the timeout for login in secdonds, 0 for  │
│                                indefinite                                    │
│                                [default: 30]                                 │
│               -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.

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:

  1. Either use the valid token with --token-file <my_token_file>.

  2. 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.