Config

pydantic settings gafaelfawr.config.Config

Configuration for Gafaelfawr.

Parameters:

data (Any)

Fields:
Validators:

  • _validate_bootstrap_token » bootstrapToken

  • _validate_initial_admins » initialAdmins

  • _validate_known_scopes » knownScopes

  • _validate_optional » all fields

  • _validate_scopes » all fields

  • _validate_token_lifetime » tokenLifetime

  • _validate_userinfo » all fields

field afterLogoutUrl: HttpUrl [Required] (name 'after_logout_url')

Default URL to which to send the user after logging out

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field allowSubdomains: bool = False (name 'allow_subdomains')

Allow authenticated ingresses in subdomains of the base URL. This requires use of domain-scoped cookies instead of host cookies and therefore requires every subdomain of the domain in the base URL be under the full control of Gafaelfawr. Otherwise, enabling this may cause cookies to leak and compromise the security of the protected applications.

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field baseInternalUrl: HttpUrl [Required] (name 'base_internal_url')

Base URL for internal-only routes such as /ingress/auth

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field baseUrl: HttpUrl [Required] (name 'base_url')

Base URL for user-facing routes such as /login

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field bootstrapToken: SecretStr [Required] (name 'bootstrap_token')

File containing the bootstrap authentication token. This token can be used with specific routes in the admin API to change the list of admins and create service and user tokens.

Validated by:

  • _validate_bootstrap_token

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field cilogon: CILogonConfig | None = None

Configuration for the CILogon authentication provider

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field databasePassword: SecretStr [Required] (name 'database_password')

Password for the PostgreSQL database

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field databaseUrl: EnvAsyncPostgresDsn [Required] (name 'database_url')

DSN for the PostgreSQL database

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field enableSentry: bool = False (name 'enable_sentry')

Send trace and telemetry information to Sentry if the Sentry environment variables are set

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

HTML to add (inside <p>) to login error pages

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field firestore: FirestoreConfig | None = None

Configuration for UID/GID allocation using Firestore

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field github: GitHubConfig | None = None

Configuration for the GitHub authentication provider

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field groupMapping: dict[str, list[str | GitHubGroup]] = {} (name 'group_mapping')

Mappings of scopes to lists of groups that provide them

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field initialAdmins: list[str] = [] (name 'initial_admins')

List of usernames to mark as admins during database initialization

Validated by:

  • _validate_initial_admins

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field internalDatabase: bool = False (name 'internal_database')

Whether to use a cluster-internal database. This setting is only used by Helm, not by Gafaelfawr itself.

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field knownScopes: dict[str, str] = {} (name 'known_scopes')

Known scopes (the keys) and their descriptions (the values)

Validated by:

  • _validate_known_scopes

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field ldap: LDAPConfig | None = None

Configuration for retrieving user information from LDAP

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field logLevel: LogLevel = LogLevel.INFO (name 'log_level')

Python logging level

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field metrics: MetricsConfiguration [Required]

Configuration for reporting metrics to Kafka

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field oidc: OIDCConfig | None = None

Configuration for the OpenID Connect authentication provider

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field oidcServer: OIDCServerConfig | None = None (name 'oidc_server')

Configuration for Gafaelfawr’s internal OpenID Connect server

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field proxies: list[IPv4Network | IPv6Network] | None = None

If this is set to a non-empty list, it will be used as the trusted list of proxies when parsing the X-Forwarded-For HTTP header in incoming requests. IP addresses from that header will be discarded from the right side when they are within a netblock in this list until a non-matching IP is reached or there is only one IP left, and then that IP will be used as the remote IP for logging purposes. This allows logging of accurate client IP addresses.

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field quota: QuotaConfig | None = None

Rules for assigning quota to users

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field redisEphemeralUrl: EnvRedisDsn [Required] (name 'redis_ephemeral_url')

DSN for the Redis server that stores ephemeral data

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field redisPassword: SecretStr | None = None (name 'redis_password')

Password for both Redis servers

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field redisPersistentUrl: EnvRedisDsn [Required] (name 'redis_persistent_url')

DSN for the Redis server that stores tokens

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field sessionSecret: SecretStr [Required] (name 'session_secret')

Fernet encryption key used for session cookie and store

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field slackAlerts: bool = False (name 'slack_alerts')

Whether to enable Slack alerts. If true, slack_webhook must also be set.

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field slackWebhook: SecretStr | None = None (name 'slack_webhook')

If set, alerts will be posted to this Slack webhook

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

field tokenLifetime: HumanTimedelta = datetime.timedelta(days=30) (name 'token_lifetime')

Lifetime of newly-created session tokens

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_token_lifetime

  • _validate_userinfo

field updateSchema: bool = False (name 'update_schema')

This setting is interpreted by Helm and triggers a SQL schema update via a Helm hook. It is not used by Gafaelfawr directly.

Validated by:

  • _validate_optional

  • _validate_scopes

  • _validate_userinfo

configure_logging()

Configure logging based on the Gafaelfawr configuration.

Return type:

None

classmethod from_file(path)

Construct a Config object from a configuration file.

Parameters:

path (Path) – Path to the configuration file in YAML.

Returns:

The corresponding Config object.

Return type:

Config

get_scopes_for_group(group)

Return the scopes granted by a given group membership.

Parameters:

group (str) – Name of the group.

Returns:

Scopes granted by that group membership. This will be the empty set if the group was not recognized.

Return type:

frozenset of str

is_hostname_allowed(hostname)

Check whether a hostname is within the Gafaelfawr domain.

Numerous places in Gafaelfawr want to allow only hostnames that fall within the base domain of Gafaelfawr. If subdomains are disabled, the hostname must match the base hostname exactly. If subdomains are allowed, the hostname must be a subdomain of that base domain.

Parameters:

hostname (str | None) – Hostname to check. None is allowed for typing convenience but is always rejected.

Returns:

Whether that hostname is allowed for this Gafaelfawr instance.

Return type:

bool

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:

self: The BaseModel instance. context: The context.

Parameters:

  • self (BaseModel)

  • context (Any)

Return type:

None

property add_user_group: bool

Whether to add a synthetic private user group.

property base_hostname: str

Realm to use for HTTP authentication.

property cookie_parameters: CookieParameters

Parameters to pass to fastapi.Response.set_cookie.

property redis_rate_limit_url: str

Redis DSN to use for rate limiting.

The limits package requires the Redis DSN in a specific format with the password already included.