Settings

pydantic model gafaelfawr.config.Settings

pydantic model of Gafaelfawr configuration file.

This describes the configuration file as parsed from disk. This model will be converted to a Config dataclass for internal use so that some settings can be duplicated, rewritten, or parsed into internal formats for later convenience.

Several fields use an empty dictionary or empty list as a default value. Due to a quirk in how Python handles empty dict and list constructors, the caller must be careful to never modify those fields and instead treat the value as read-only. In practice, this isn’t much of a concern since this object is only used to convert to a Config object.

Parameters:

data (Any) –

Show JSON schema

{
   "title": "Settings",
   "description": "pydantic model of Gafaelfawr configuration file.\n\nThis describes the configuration file as parsed from disk.  This model\nwill be converted to a `Config` dataclass for internal use so that some\nsettings can be duplicated, rewritten, or parsed into internal formats for\nlater convenience.\n\nSeveral fields use an empty dictionary or empty list as a default value.\nDue to a quirk in how Python handles empty dict and list constructors, the\ncaller must be careful to never modify those fields and instead treat the\nvalue as read-only.  In practice, this isn't much of a concern since this\nobject is only used to convert to a `Config` object.",
   "type": "object",
   "properties": {
      "realm": {
         "title": "Realm",
         "type": "string"
      },
      "logLevel": {
         "allOf": [
            {
               "$ref": "#/$defs/LogLevel"
            }
         ],
         "default": "INFO"
      },
      "sessionSecretFile": {
         "format": "path",
         "title": "Sessionsecretfile",
         "type": "string"
      },
      "redisUrl": {
         "title": "Redisurl",
         "type": "string"
      },
      "redisPasswordFile": {
         "anyOf": [
            {
               "format": "path",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Redispasswordfile"
      },
      "databaseUrl": {
         "title": "Databaseurl",
         "type": "string"
      },
      "databasePasswordFile": {
         "anyOf": [
            {
               "format": "path",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Databasepasswordfile"
      },
      "bootstrapTokenFile": {
         "anyOf": [
            {
               "format": "path",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Bootstraptokenfile"
      },
      "tokenLifetimeMinutes": {
         "default": 1380,
         "title": "Tokenlifetimeminutes",
         "type": "integer"
      },
      "proxies": {
         "anyOf": [
            {
               "items": {
                  "anyOf": [
                     {
                        "format": "ipv4network",
                        "type": "string"
                     },
                     {
                        "format": "ipv6network",
                        "type": "string"
                     }
                  ]
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Proxies"
      },
      "afterLogoutUrl": {
         "format": "uri",
         "minLength": 1,
         "title": "Afterlogouturl",
         "type": "string"
      },
      "errorFooter": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Errorfooter"
      },
      "slackWebhookFile": {
         "anyOf": [
            {
               "format": "path",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Slackwebhookfile"
      },
      "github": {
         "anyOf": [
            {
               "$ref": "#/$defs/GitHubSettings"
            },
            {
               "type": "null"
            }
         ],
         "default": null
      },
      "oidc": {
         "anyOf": [
            {
               "$ref": "#/$defs/OIDCSettings"
            },
            {
               "type": "null"
            }
         ],
         "default": null
      },
      "ldap": {
         "anyOf": [
            {
               "$ref": "#/$defs/LDAPSettings"
            },
            {
               "type": "null"
            }
         ],
         "default": null
      },
      "firestore": {
         "anyOf": [
            {
               "$ref": "#/$defs/FirestoreSettings"
            },
            {
               "type": "null"
            }
         ],
         "default": null
      },
      "forgerock": {
         "anyOf": [
            {
               "$ref": "#/$defs/ForgeRockSettings"
            },
            {
               "type": "null"
            }
         ],
         "default": null
      },
      "oidcServer": {
         "anyOf": [
            {
               "$ref": "#/$defs/OIDCServerSettings"
            },
            {
               "type": "null"
            }
         ],
         "default": null
      },
      "quota": {
         "anyOf": [
            {
               "$ref": "#/$defs/QuotaSettings"
            },
            {
               "type": "null"
            }
         ],
         "default": null
      },
      "initialAdmins": {
         "items": {
            "type": "string"
         },
         "title": "Initialadmins",
         "type": "array"
      },
      "knownScopes": {
         "additionalProperties": {
            "type": "string"
         },
         "default": {},
         "description": "Known scopes (the keys) and their descriptions (the values)",
         "title": "Known scopes",
         "type": "object"
      },
      "groupMapping": {
         "additionalProperties": {
            "items": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "$ref": "#/$defs/GitHubGroup"
                  }
               ]
            },
            "type": "array"
         },
         "default": {},
         "description": "Mappings of scopes to lists of groups that provide them",
         "title": "Scope to group mapping",
         "type": "object"
      }
   },
   "$defs": {
      "FirestoreSettings": {
         "description": "pydantic model of Firestore configuration.",
         "properties": {
            "project": {
               "title": "Project",
               "type": "string"
            }
         },
         "required": [
            "project"
         ],
         "title": "FirestoreSettings",
         "type": "object"
      },
      "ForgeRockSettings": {
         "description": "pydantic model of ForgeRock Identity Management configuration.",
         "properties": {
            "url": {
               "title": "Url",
               "type": "string"
            },
            "username": {
               "title": "Username",
               "type": "string"
            },
            "passwordFile": {
               "format": "path",
               "title": "Passwordfile",
               "type": "string"
            }
         },
         "required": [
            "url",
            "username",
            "passwordFile"
         ],
         "title": "ForgeRockSettings",
         "type": "object"
      },
      "GitHubGroup": {
         "description": "An individual GitHub team.",
         "properties": {
            "github": {
               "$ref": "#/$defs/GitHubGroupTeam"
            }
         },
         "required": [
            "github"
         ],
         "title": "GitHubGroup",
         "type": "object"
      },
      "GitHubGroupTeam": {
         "description": "Specification for a GitHub team.",
         "properties": {
            "organization": {
               "title": "Organization",
               "type": "string"
            },
            "team": {
               "title": "Team",
               "type": "string"
            }
         },
         "required": [
            "organization",
            "team"
         ],
         "title": "GitHubGroupTeam",
         "type": "object"
      },
      "GitHubSettings": {
         "description": "pydantic model of GitHub configuration.",
         "properties": {
            "clientId": {
               "title": "Clientid",
               "type": "string"
            },
            "clientSecretFile": {
               "format": "path",
               "title": "Clientsecretfile",
               "type": "string"
            }
         },
         "required": [
            "clientId",
            "clientSecretFile"
         ],
         "title": "GitHubSettings",
         "type": "object"
      },
      "LDAPSettings": {
         "description": "pydantic model of LDAP configuration.",
         "properties": {
            "url": {
               "title": "Url",
               "type": "string"
            },
            "userDn": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Userdn"
            },
            "useKerberos": {
               "default": false,
               "title": "Usekerberos",
               "type": "boolean"
            },
            "passwordFile": {
               "anyOf": [
                  {
                     "format": "path",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Passwordfile"
            },
            "groupBaseDn": {
               "title": "Groupbasedn",
               "type": "string"
            },
            "groupObjectClass": {
               "default": "posixGroup",
               "title": "Groupobjectclass",
               "type": "string"
            },
            "groupMemberAttr": {
               "default": "member",
               "title": "Groupmemberattr",
               "type": "string"
            },
            "userBaseDn": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Userbasedn"
            },
            "userSearchAttr": {
               "default": "uid",
               "title": "Usersearchattr",
               "type": "string"
            },
            "nameAttr": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": "displayName",
               "title": "Nameattr"
            },
            "emailAttr": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": "mail",
               "title": "Emailattr"
            },
            "uidAttr": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Uidattr"
            },
            "gidAttr": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Gidattr"
            },
            "addUserGroup": {
               "default": false,
               "title": "Addusergroup",
               "type": "boolean"
            }
         },
         "required": [
            "url",
            "groupBaseDn"
         ],
         "title": "LDAPSettings",
         "type": "object"
      },
      "LogLevel": {
         "description": "Python logging level.",
         "enum": [
            "DEBUG",
            "INFO",
            "WARNING",
            "ERROR",
            "CRITICAL"
         ],
         "title": "LogLevel",
         "type": "string"
      },
      "NotebookQuotaSettings": {
         "description": "Quota settings for the Notebook Aspect.",
         "properties": {
            "cpu": {
               "title": "Cpu",
               "type": "number"
            },
            "memory": {
               "title": "Memory",
               "type": "number"
            }
         },
         "required": [
            "cpu",
            "memory"
         ],
         "title": "NotebookQuotaSettings",
         "type": "object"
      },
      "OIDCServerSettings": {
         "description": "pydantic model of issuer configuration.",
         "properties": {
            "issuer": {
               "title": "Issuer",
               "type": "string"
            },
            "keyId": {
               "title": "Keyid",
               "type": "string"
            },
            "audience": {
               "title": "Audience",
               "type": "string"
            },
            "keyFile": {
               "format": "path",
               "title": "Keyfile",
               "type": "string"
            },
            "secretsFile": {
               "format": "path",
               "title": "Secretsfile",
               "type": "string"
            }
         },
         "required": [
            "issuer",
            "keyId",
            "audience",
            "keyFile",
            "secretsFile"
         ],
         "title": "OIDCServerSettings",
         "type": "object"
      },
      "OIDCSettings": {
         "description": "pydantic model of OpenID Connect configuration.",
         "properties": {
            "clientId": {
               "title": "Clientid",
               "type": "string"
            },
            "clientSecretFile": {
               "format": "path",
               "title": "Clientsecretfile",
               "type": "string"
            },
            "loginUrl": {
               "format": "uri",
               "minLength": 1,
               "title": "Loginurl",
               "type": "string"
            },
            "loginParams": {
               "additionalProperties": {
                  "type": "string"
               },
               "default": {},
               "description": "Additional parameters to the login URL",
               "title": "Additional login parameters",
               "type": "object"
            },
            "redirectUrl": {
               "format": "uri",
               "minLength": 1,
               "title": "Redirecturl",
               "type": "string"
            },
            "tokenUrl": {
               "format": "uri",
               "minLength": 1,
               "title": "Tokenurl",
               "type": "string"
            },
            "enrollmentUrl": {
               "anyOf": [
                  {
                     "format": "uri",
                     "minLength": 1,
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Enrollmenturl"
            },
            "scopes": {
               "default": [],
               "description": "Scopes to request from the authentication provider. The `openid` scope will always be added and does not need to be specified.",
               "items": {
                  "type": "string"
               },
               "title": "Scopes to request",
               "type": "array"
            },
            "issuer": {
               "title": "Issuer",
               "type": "string"
            },
            "audience": {
               "title": "Audience",
               "type": "string"
            },
            "usernameClaim": {
               "default": "uid",
               "title": "Usernameclaim",
               "type": "string"
            },
            "uidClaim": {
               "default": "uidNumber",
               "title": "Uidclaim",
               "type": "string"
            },
            "gidClaim": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Gidclaim"
            },
            "groupsClaim": {
               "default": "isMemberOf",
               "title": "Groupsclaim",
               "type": "string"
            }
         },
         "required": [
            "clientId",
            "clientSecretFile",
            "loginUrl",
            "redirectUrl",
            "tokenUrl",
            "issuer",
            "audience"
         ],
         "title": "OIDCSettings",
         "type": "object"
      },
      "QuotaGrantSettings": {
         "description": "One grant of quotas.\n\nThere may be one of these per group, as well as a default one, in the\noverall quota configuration.",
         "properties": {
            "api": {
               "additionalProperties": {
                  "type": "integer"
               },
               "default": {},
               "description": "Mapping of service names to quota of requests per 15 minutes",
               "title": "Service quotas",
               "type": "object"
            },
            "notebook": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/NotebookQuotaSettings"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null
            }
         },
         "title": "QuotaGrantSettings",
         "type": "object"
      },
      "QuotaSettings": {
         "description": "Quota settings.",
         "properties": {
            "default": {
               "$ref": "#/$defs/QuotaGrantSettings"
            },
            "groups": {
               "additionalProperties": {
                  "$ref": "#/$defs/QuotaGrantSettings"
               },
               "default": {},
               "description": "Additional quota grants by group name",
               "title": "Quota grants by group",
               "type": "object"
            }
         },
         "required": [
            "default"
         ],
         "title": "QuotaSettings",
         "type": "object"
      }
   },
   "required": [
      "realm",
      "sessionSecretFile",
      "redisUrl",
      "databaseUrl",
      "afterLogoutUrl",
      "initialAdmins"
   ]
}

Fields:

• afterLogoutUrl (pydantic_core._pydantic_core.Url)

• bootstrapTokenFile (pathlib.Path | None)

• databasePasswordFile (pathlib.Path | None)

• databaseUrl (str)

• errorFooter (str | None)

• firestore (gafaelfawr.config.FirestoreSettings | None)

• forgerock (gafaelfawr.config.ForgeRockSettings | None)

• github (gafaelfawr.config.GitHubSettings | None)

• groupMapping (dict[str, list[str | gafaelfawr.config.GitHubGroup]])

• initialAdmins (list[str])

• knownScopes (dict[str, str])

• ldap (gafaelfawr.config.LDAPSettings | None)

• logLevel (safir.logging.LogLevel)

• oidc (gafaelfawr.config.OIDCSettings | None)

• oidcServer (gafaelfawr.config.OIDCServerSettings | None)

• proxies (list[ipaddress.IPv4Network | ipaddress.IPv6Network] | None)

• quota (gafaelfawr.config.QuotaSettings | None)

• realm (str)

• redisPasswordFile (pathlib.Path | None)

• redisUrl (str)

• sessionSecretFile (pathlib.Path)

• slackWebhookFile (pathlib.Path | None)

• tokenLifetimeMinutes (int)

Validators:

• _valid_known_scopes » knownScopes

• _valid_ldap_config » ldap

• _validate_initial_admins » initialAdmins

• validator » all fields

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

Default URL to which to send the user after logging out.

Constraints:

• allowed_schemes = [‘http’, ‘https’]

Validated by:

• validator

field bootstrapTokenFile: Path | None = None (name 'bootstrap_token_file')

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:

• validator

field databasePasswordFile: Path | None = None (name 'database_password_file')

File containing the password for the PostgreSQL database.

Validated by:

• validator

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

URL for the PostgreSQL database.

Validated by:

• validator

field errorFooter: str | None = None (name 'error_footer')

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

Validated by:

• validator

field firestore: FirestoreSettings | None = None

Settings for Firestore-based UID/GID assignment.

Validated by:

• validator

field forgerock: ForgeRockSettings | None = None

Settings for ForgeRock Identity Management server.

Validated by:

• validator

field github: GitHubSettings | None = None

Settings for the GitHub authentication provider.

Validated by:

• validator

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

Mappings of scopes to lists of groups that provide them

Validated by:

• validator

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

Initial token administrators to configure when initializing database.

Validated by:

• _validate_initial_admins

• validator

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

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

Validated by:

• _valid_known_scopes

• validator

field ldap: LDAPSettings | None = None

Settings for the LDAP-based group lookups with OIDC provider.

Validated by:

• _valid_ldap_config

• validator

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

Logging level.

Validated by:

• validator

field oidc: OIDCSettings | None = None

Settings for the OpenID Connect authentication provider.

Validated by:

• validator

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

Settings for the internal OpenID Connect server.

Validated by:

• validator

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

Trusted proxy IP netblocks in front of Gafaelfawr.

If this is set to a non-empty list, it will be used as the trusted list of proxies when parsing X-Forwarded-For for the /auth route. 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 will allow logging of accurate client IP addresses.

Validated by:

• validator

field quota: QuotaSettings | None = None

Quota for users.

Validated by:

• validator

field realm: str [Required]

Realm for HTTP authentication.

Validated by:

• validator

field redisPasswordFile: Path | None = None (name 'redis_password_file')

File containing the password to use when connecting to Redis.

Validated by:

• validator

field redisUrl: str [Required] (name 'redis_url')

URL for the Redis server that stores sessions.

Validated by:

• validator

field sessionSecretFile: Path [Required] (name 'session_secret_file')

File containing encryption secret for session cookie and store.

Validated by:

• validator

field slackWebhookFile: Path | None = None (name 'slack_webhook_file')

File containing the Slack webhook to which to post alerts.

Validated by:

• validator

field tokenLifetimeMinutes: int = 1380 (name 'token_lifetime_minutes')

Number of minutes into the future that a token should expire.

Validated by:

• validator

model_dump(**kwargs)

Export the model as a dictionary.

Overridden to change the default of by_alias from False to True, so that by default the exported dictionary uses camel-case.

Parameters:

kwargs (Any) –

Return type:

dict[str, Any]

model_dump_json(**kwargs)

Export the model as JSON.

Overridden to change the default of by_alias from False to True, so that by default the exported dictionary uses camel-case.

Parameters:

kwargs (Any) –

Return type:

str