Skip to content

_main

OAuthClientConfig

Bases: BaseModel

OAuth Client Config Model

This model wraps the variables that define a client against an Identity Provider. As some providers are supported by the libraries used within the server, some attributes are optional.

Attributes:

Name Type Description
CLIENT_NAME str

The name of the client
CLIENT_ID str

ID of client
CLIENT_SECRET SecretStr

Secret to authorise against the identity provider
OIDC_CONFIGURATION_ENDPOINT str | None

OpenID configuration endpoint, allowing to discover the required endpoints automatically
REDIRECT_URL str | None

String to be used as redirect_url argument for fastapi_users.get_oauth_router, and then in httpx_oauth.integrations.fastapi.OAuth2AuthorizeCallback.
Source code in fractal_server/config/_main.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
class OAuthClientConfig(BaseModel):
    """
    OAuth Client Config Model

    This model wraps the variables that define a client against an Identity
    Provider. As some providers are supported by the libraries used within the
    server, some attributes are optional.

    Attributes:
        CLIENT_NAME:
            The name of the client
        CLIENT_ID:
            ID of client
        CLIENT_SECRET:
            Secret to authorise against the identity provider
        OIDC_CONFIGURATION_ENDPOINT:
            OpenID configuration endpoint,
            allowing to discover the required endpoints automatically
        REDIRECT_URL:
            String to be used as `redirect_url` argument for
            `fastapi_users.get_oauth_router`, and then in
            `httpx_oauth.integrations.fastapi.OAuth2AuthorizeCallback`.
    """

    CLIENT_NAME: str
    CLIENT_ID: str
    CLIENT_SECRET: SecretStr
    OIDC_CONFIGURATION_ENDPOINT: str | None = None
    REDIRECT_URL: str | None = None

    @model_validator(mode="before")
    @classmethod
    def check_configuration(cls, values):
        if values.get("CLIENT_NAME") not in ["GOOGLE", "GITHUB"]:
            if not values.get("OIDC_CONFIGURATION_ENDPOINT"):
                raise FractalConfigurationError(
                    f"Missing OAUTH_{values.get('CLIENT_NAME')}"
                    "_OIDC_CONFIGURATION_ENDPOINT"
                )
        return values

Settings

Bases: BaseSettings

Contains all the configuration variables for Fractal Server

The attributes of this class are set from the environment.

Source code in fractal_server/config/_main.py 
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
class Settings(BaseSettings):
    """
    Contains all the configuration variables for Fractal Server

    The attributes of this class are set from the environment.
    """

    model_config = SettingsConfigDict(**SETTINGS_CONFIG_DICT)

    OAUTH_CLIENTS_CONFIG: list[OAuthClientConfig] = Field(default_factory=list)

    # JWT TOKEN
    JWT_EXPIRE_SECONDS: int = 180
    """
    JWT token lifetime, in seconds.
    """

    JWT_SECRET_KEY: SecretStr
    """
    JWT secret

    ⚠️ **IMPORTANT**: set this variable to a secure string, and do not disclose
    it.
    """

    # COOKIE TOKEN
    COOKIE_EXPIRE_SECONDS: int = 86400
    """
    Cookie token lifetime, in seconds.
    """

    @model_validator(mode="before")
    @classmethod
    def collect_oauth_clients(cls, values):
        """
        Automatic collection of OAuth Clients

        This method collects the environment variables relative to a single
        OAuth client and saves them within the `Settings` object in the form
        of an `OAuthClientConfig` instance.

        Fractal can support an arbitrary number of OAuth providers, which are
        automatically detected by parsing the environment variable names. In
        particular, to set the provider `FOO`, one must specify the variables

            OAUTH_FOO_CLIENT_ID
            OAUTH_FOO_CLIENT_SECRET
            ...

        etc (cf. OAuthClientConfig).
        """
        oauth_env_variable_keys = [
            key for key in environ.keys() if key.startswith("OAUTH_")
        ]
        clients_available = {
            var.split("_")[1] for var in oauth_env_variable_keys
        }

        values["OAUTH_CLIENTS_CONFIG"] = []
        for client in clients_available:
            prefix = f"OAUTH_{client}"
            oauth_client_config = OAuthClientConfig(
                CLIENT_NAME=client,
                CLIENT_ID=getenv(f"{prefix}_CLIENT_ID", None),
                CLIENT_SECRET=getenv(f"{prefix}_CLIENT_SECRET", None),
                OIDC_CONFIGURATION_ENDPOINT=getenv(
                    f"{prefix}_OIDC_CONFIGURATION_ENDPOINT", None
                ),
                REDIRECT_URL=getenv(f"{prefix}_REDIRECT_URL", None),
            )
            values["OAUTH_CLIENTS_CONFIG"].append(oauth_client_config)
        return values

    ###########################################################################
    # FRACTAL SPECIFIC
    ###########################################################################

    # Note: we do not use ResourceType here to avoid circular imports
    FRACTAL_RUNNER_BACKEND: Literal[
        "local", "slurm_ssh", "slurm_sudo"
    ] = "local"
    """
    Select which runner backend to use.
    """

    FRACTAL_LOGGING_LEVEL: int = logging.INFO
    """
    Logging-level threshold for logging

    Only logs of with this level (or higher) will appear in the console logs.
    """

    FRACTAL_API_MAX_JOB_LIST_LENGTH: int = 50
    """
    Number of ids that can be stored in the `jobsV2` attribute of
    `app.state`.
    """

    FRACTAL_GRACEFUL_SHUTDOWN_TIME: int = 30
    """
    Waiting time for the shutdown phase of executors
    """

    FRACTAL_VIEWER_AUTHORIZATION_SCHEME: Literal[
        "viewer-paths", "users-folders", "none"
    ] = "none"
    """
    Defines how the list of allowed viewer paths is built.

    This variable affects the `GET /auth/current-user/allowed-viewer-paths/`
    response, which is then consumed by
    [fractal-vizarr-viewer](https://github.com/fractal-analytics-platform/fractal-vizarr-viewer).

    Options:

    - "viewer-paths": The list of allowed viewer paths will include the user's
      `project_dir` along with any path defined in user groups' `viewer_paths`
      attributes.
    - "users-folders": The list will consist of the user's `project_dir` and a
       user-specific folder. The user folder is constructed by concatenating
       the base folder `FRACTAL_VIEWER_BASE_FOLDER` with the user's
       `slurm_user`.
    - "none": An empty list will be returned, indicating no access to
       viewer paths. Useful when vizarr viewer is not used.
    """

    FRACTAL_VIEWER_BASE_FOLDER: AbsolutePathStr | None = None
    """
    Base path to Zarr files that will be served by fractal-vizarr-viewer;
    This variable is required and used only when
    FRACTAL_VIEWER_AUTHORIZATION_SCHEME is set to "users-folders".
    """

    def check(self):
        """
        Make sure that required variables are set

        This method must be called before the server starts
        """
        # FRACTAL_VIEWER_BASE_FOLDER is required when
        # FRACTAL_VIEWER_AUTHORIZATION_SCHEME is set to "users-folders"
        # and it must be an absolute path
        if self.FRACTAL_VIEWER_AUTHORIZATION_SCHEME == "users-folders":
            viewer_base_folder = self.FRACTAL_VIEWER_BASE_FOLDER
            if viewer_base_folder is None:
                raise FractalConfigurationError(
                    "FRACTAL_VIEWER_BASE_FOLDER is required when "
                    "FRACTAL_VIEWER_AUTHORIZATION_SCHEME is set to "
                    "users-folders"
                )

COOKIE_EXPIRE_SECONDS = 86400 class-attribute instance-attribute

Cookie token lifetime, in seconds.

FRACTAL_API_MAX_JOB_LIST_LENGTH = 50 class-attribute instance-attribute

Number of ids that can be stored in the jobsV2 attribute of app.state.

FRACTAL_GRACEFUL_SHUTDOWN_TIME = 30 class-attribute instance-attribute

Waiting time for the shutdown phase of executors

FRACTAL_LOGGING_LEVEL = logging.INFO class-attribute instance-attribute

Logging-level threshold for logging

Only logs of with this level (or higher) will appear in the console logs.

FRACTAL_RUNNER_BACKEND = 'local' class-attribute instance-attribute

Select which runner backend to use.

FRACTAL_VIEWER_AUTHORIZATION_SCHEME = 'none' class-attribute instance-attribute

Defines how the list of allowed viewer paths is built.

This variable affects the GET /auth/current-user/allowed-viewer-paths/ response, which is then consumed by fractal-vizarr-viewer.

Options:

  • "viewer-paths": The list of allowed viewer paths will include the user's project_dir along with any path defined in user groups' viewer_paths attributes.
  • "users-folders": The list will consist of the user's project_dir and a user-specific folder. The user folder is constructed by concatenating the base folder FRACTAL_VIEWER_BASE_FOLDER with the user's slurm_user.
  • "none": An empty list will be returned, indicating no access to viewer paths. Useful when vizarr viewer is not used.

FRACTAL_VIEWER_BASE_FOLDER = None class-attribute instance-attribute

Base path to Zarr files that will be served by fractal-vizarr-viewer; This variable is required and used only when FRACTAL_VIEWER_AUTHORIZATION_SCHEME is set to "users-folders".

JWT_EXPIRE_SECONDS = 180 class-attribute instance-attribute

JWT token lifetime, in seconds.

JWT_SECRET_KEY instance-attribute

JWT secret

⚠️ IMPORTANT: set this variable to a secure string, and do not disclose it.

check()

Make sure that required variables are set

This method must be called before the server starts

Source code in fractal_server/config/_main.py 
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
def check(self):
    """
    Make sure that required variables are set

    This method must be called before the server starts
    """
    # FRACTAL_VIEWER_BASE_FOLDER is required when
    # FRACTAL_VIEWER_AUTHORIZATION_SCHEME is set to "users-folders"
    # and it must be an absolute path
    if self.FRACTAL_VIEWER_AUTHORIZATION_SCHEME == "users-folders":
        viewer_base_folder = self.FRACTAL_VIEWER_BASE_FOLDER
        if viewer_base_folder is None:
            raise FractalConfigurationError(
                "FRACTAL_VIEWER_BASE_FOLDER is required when "
                "FRACTAL_VIEWER_AUTHORIZATION_SCHEME is set to "
                "users-folders"
            )

collect_oauth_clients(values) classmethod

Automatic collection of OAuth Clients

This method collects the environment variables relative to a single OAuth client and saves them within the Settings object in the form of an OAuthClientConfig instance.

Fractal can support an arbitrary number of OAuth providers, which are automatically detected by parsing the environment variable names. In particular, to set the provider FOO, one must specify the variables

OAUTH_FOO_CLIENT_ID
OAUTH_FOO_CLIENT_SECRET
...

etc (cf. OAuthClientConfig).

Source code in fractal_server/config/_main.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
@model_validator(mode="before")
@classmethod
def collect_oauth_clients(cls, values):
    """
    Automatic collection of OAuth Clients

    This method collects the environment variables relative to a single
    OAuth client and saves them within the `Settings` object in the form
    of an `OAuthClientConfig` instance.

    Fractal can support an arbitrary number of OAuth providers, which are
    automatically detected by parsing the environment variable names. In
    particular, to set the provider `FOO`, one must specify the variables

        OAUTH_FOO_CLIENT_ID
        OAUTH_FOO_CLIENT_SECRET
        ...

    etc (cf. OAuthClientConfig).
    """
    oauth_env_variable_keys = [
        key for key in environ.keys() if key.startswith("OAUTH_")
    ]
    clients_available = {
        var.split("_")[1] for var in oauth_env_variable_keys
    }

    values["OAUTH_CLIENTS_CONFIG"] = []
    for client in clients_available:
        prefix = f"OAUTH_{client}"
        oauth_client_config = OAuthClientConfig(
            CLIENT_NAME=client,
            CLIENT_ID=getenv(f"{prefix}_CLIENT_ID", None),
            CLIENT_SECRET=getenv(f"{prefix}_CLIENT_SECRET", None),
            OIDC_CONFIGURATION_ENDPOINT=getenv(
                f"{prefix}_OIDC_CONFIGURATION_ENDPOINT", None
            ),
            REDIRECT_URL=getenv(f"{prefix}_REDIRECT_URL", None),
        )
        values["OAUTH_CLIENTS_CONFIG"].append(oauth_client_config)
    return values