Python internal API

gafaelfawr Package

The Gafaelfawr service.

Variables

__version__

The application version string (PEP 440 / SemVer compatible).

gafaelfawr.auth Module

Utility functions for manipulating authentication headers.

Functions

clean_authorization(headers)	Remove Gafaelfawr tokens from Authorization headers.
clean_cookies(headers)	Remove Gafaelfawr cookies from cookie headers.
generate_challenge(context, auth_type, exc)	Convert an exception into an HTTP error with WWW-Authenticate.
generate_unauthorized_challenge(context, ...)	Construct exception for a 401 response with AJAX handling.
parse_authorization(context, *[, ...])	Find a token in the Authorization header.

gafaelfawr.cache Module

Shared caches.

These caches are process-global, managed by ProcessContext. The common theme is some storage wrapped in an asyncio.Lock, possibly with some complex structure to allow per-user locking. These services sit below the main service layer and are only intended for use via their service layer (TokenCacheService, LDAPService, and FirestoreService).

Classes

BaseCache()	Base class for caches managed by a cache dependency.
IdCache()	A cache of UIDs or GIDs.
InternalTokenCache()	Cache for internal tokens.
LDAPCache(content)	A cache of LDAP data.
NotebookTokenCache()	Cache for notebook tokens.
PerUserCache()	Base class for a cache with per-user locking.
TokenCache()	Base class for a cache of internal or notebook tokens.
UserLockManager(general_lock, user_lock)	Helper class for managing per-user locks.

Class Inheritance Diagram

gafaelfawr.config Module

Configuration for Gafaelfawr.

Gafaelfawr is primarily configured by a YAML file injected into the pod that contains a copy of the config key of the Helm chart values. However, many settings are based on Phalanx global settings or secrets, and those are injected via environment variables.

Every part of the configuration that accepts environment variables uses the same prefix for simplicity in the Helm chart. Only the settings with explicit validation_alias settings support configuration via environment variable. There is unfortunately no way to disable environment variable support for the other settings that should always come from the configuration file.

Order of fields in the configuration models should match the order of the fields in Gafaelfawr’s values.yaml file, although there will be more settings here since some settings are only injected via environment variables and cannot be set in the config.

Classes

CamelCaseSettings	Base class for Pydantic settings supporting camel-case.
Config	Configuration for Gafaelfawr.
EnvFirstSettings	Base class for Pydantic settings with environment overrides.
FirestoreConfig	Configuration for Firestore-based UID/GID assignment.
GitHubConfig	Configuration for the GitHub authentication provider.
GitHubGroup	An individual GitHub team.
GitHubGroupTeam	Specification for a GitHub team.
LDAPConfig	Configuration for LDAP support.
NotebookQuota	Quota settings for the Notebook Aspect.
OIDCClient	Configuration for a single OpenID Connect client of our server.
OIDCConfig	Configuration for a generic OpenID Connect authentication provider.
OIDCServerConfig	Configuration for the OpenID Connect server.
QuotaConfig	Quota configuration.
QuotaGrant	One grant of quotas.

Variables

HttpsUrl

URL type that accepts only https URLs.

Class Inheritance Diagram

gafaelfawr.constants Module

Constants for Gafaelfawr.

Variables

ACTOR_REGEX	Regex matching all valid actors (including <bootstrap>).
ALGORITHM	JWT algorithm to use for all tokens.
BOT_USERNAME_REGEX	Regex matching a valid username that is also a bot user.
CHANGE_HISTORY_RETENTION	Retention of old token change history entries.
CONFIG_PATH	Default configuration path.
COOKIE_NAME	Name of the state cookie.
CURSOR_REGEX	Regex matching a valid cursor.
GID_MAX	Maximum gid for groups.
GID_MIN	Minimum GID for groups.
GROUPNAME_REGEX	Regex matching all valid group names.
HTTP_TIMEOUT	Timeout (in seconds) for outbound HTTP requests to auth providers.
ID_CACHE_SIZE	How many UID or GID values to cache in memory.
KUBERNETES_TIMER_DELAY	How long (in seconds) to delay timers after startup and changes.
KUBERNETES_TOKEN_INTERVAL	How frequently (in seconds) to validate service tokens stored in secrets.
KUBERNETES_WATCH_TIMEOUT	Timeout (in seconds) for the Kubernetes operator watch operation.
LDAP_CACHE_LIFETIME	Lifetime of the LDAP caches in seconds.
LDAP_CACHE_SIZE	Maximum numbr of entries in LDAP caches.
LDAP_TIMEOUT	Timeout (in seconds) for LDAP queries.
MINIMUM_LIFETIME	Minimum expiration lifetime for a token.
NGINX_SNIPPET	Code snippet to put into NGINX configuration for each ingress.
OIDC_AUTHORIZATION_LIFETIME	How long (in seconds) an authorization code is good for.
REDIS_BACKOFF_MAX	Maximum delay (in seconds) to wait after a Redis failure.
REDIS_BACKOFF_START	How long (in seconds) to initially wait after a Redis failure.
REDIS_POOL_SIZE	Size of the Redis connection pool.
REDIS_POOL_TIMEOUT	Seconds to wait for a connection from the pool before giving up.
REDIS_RETRIES	How many times to try to connect to Redis before giving up.
REDIS_TIMEOUT	Timeout in seconds for a Redis network operation (including connecting).
SCOPE_REGEX	Regex matching a valid scope.
TOKEN_CACHE_SIZE	How many internal or notebook tokens to cache in memory.
UID_BOT_MAX	Maximum UID for bot users.
UID_BOT_MIN	Minimum UID for bot users.
UID_USER_MIN	Minimum UID for users.
USERNAME_REGEX	Regex matching all valid usernames.

gafaelfawr.dependencies.auth Module

Authentication dependencies for FastAPI.

Functions

verified_oidc_token(*, context)

Require that a request be authenticated with an OpenID Connect token.

Classes

Authenticate(*[, require_session, ...])	Dependency to verify user authentication.
AuthenticateRead(*[, require_session, ...])	Authenticate a read API.
AuthenticateWrite(*[, require_session, ...])	Authenticate a write API.

Class Inheritance Diagram

gafaelfawr.dependencies.config Module

Config dependency for FastAPI.

Classes

ConfigDependency()

Provides the configuration as a dependency.

Variables

config_dependency

The dependency that will return the current configuration.

Class Inheritance Diagram

gafaelfawr.dependencies.context Module

Request context dependency for FastAPI.

This dependency gathers a variety of information into a single object for the convenience of writing request handlers. It also provides a place to store a structlog.BoundLogger that can gather additional context during processing, including from dependencies.

Classes

ContextDependency()	Provide a per-request context as a FastAPI dependency.
RequestContext(request, ip_address, config, ...)	Holds the incoming request and its surrounding context.

Variables

context_dependency

The dependency that will return the per-request context.

Class Inheritance Diagram

gafaelfawr.dependencies.return_url Module

FastAPI dependencies for checking the return URL.

Several API routes allow the caller to request a redirect back to a return URL given as a parameter. To avoid creating an open redirect, those return URLs must be located at the same hostname as the route being called. Provide several variations of a dependency to check this.

Functions

return_url(*[, rd])	Validate a return URL in an rd parameter.
return_url_with_header(*[, rd, ...])	Validate a return URL in an rd parameter or header.

gafaelfawr.events Module

Metrics implementation for Gafaelfawr.

Classes

ActiveUserSessionsEvent	Current count of the number of active user sessions.
ActiveUserTokensEvent	Current count of the number of active user tokens.
AuthBotEvent	An authentication to a service by a bot user.
AuthUserEvent	An authentication to a service by a user.
FrontendEvents()	Event publishers for Gafaelfawr frontend events.
LoginAttemptEvent	User attempted to log in and was directed to the identity provider.
LoginEnrollmentEvent	Authenticated but unknown user redirected to the enrollment flow.
LoginFailureEvent	User authentication failed.
LoginSuccessEvent	User successfully authenticated.
StateEvents()	Event publishers for metrics about the current Gafaelfawr state.

Class Inheritance Diagram

gafaelfawr.exceptions Module

Exceptions for Gafaelfawr.

Classes

DatabaseSchemaError(message[, user, failed_at])	Gafaelfawr database schema is invalid.
DuplicateAdminError(message)	The user attempted to add an admin who already existed.
DuplicateTokenNameError(message)	The user tried to reuse the name of a token.
ExternalUserInfoError(message[, user, failed_at])	Error in external user information source.
FetchKeysError(message, *[, failed_at, ...])	Cannot retrieve the keys from an issuer.
FirestoreError(message[, user, failed_at])	An error occurred while reading or updating Firestore data.
FirestoreNotInitializedError(message[, ...])	Firestore has not been initialized.
GitHubError(message[, user, failed_at])	The response from GitHub for a request was invalid.
GitHubWebError(message, *[, failed_at, ...])	A web request to GitHub failed.
InputValidationError(message[, location, ...])	Represents an input validation error.
InsufficientScopeError	The provided token does not have the right authorization scope.
InvalidCSRFError(message)	Invalid or missing CSRF token.
InvalidClientError	The provided client_id and client_secret could not be validated.
InvalidClientIdError(message)	Invalid client ID for OpenID Connect server.
InvalidDelegateToError(message)	The delegate_to parameter was set to an invalid value.
InvalidExpiresError(message)	The provided token expiration time was invalid.
InvalidGrantError	The provided authorization code is not valid.
InvalidIPAddressError(message)	The provided IP address has invalid syntax.
InvalidMinimumLifetimeError(message)	The minimum_lifetime parameter was set to an invalid value.
InvalidRequestError	The provided Authorization header could not be parsed.
InvalidReturnURLError(message, field)	Client specified an unsafe return URL.
InvalidScopesError(message)	The provided token scopes are invalid or not available.
InvalidServiceError(message)	The service parameter was set to an invalid value.
InvalidTokenClaimsError(message[, user, ...])	One of the claims in the token is of an invalid format.
InvalidTokenError	The provided token was invalid.
KubernetesError([_TemporaryError__msg, delay])	An error occurred during Kubernetes secret processing.
KubernetesObjectError(kind, name, namespace, exc)	A Kubernetes object could not be parsed.
LDAPError(message[, user, failed_at])	User or group information in LDAP was invalid or LDAP calls failed.
MissingGIDClaimError(message[, user, failed_at])	The token is missing the required GID claim.
MissingUIDClaimError(message[, user, failed_at])	The token is missing the required UID claim.
MissingUsernameClaimError(message[, user, ...])	The token is missing the required username claim.
NoAvailableGidError(message[, user, failed_at])	The assigned UID space has been exhausted.
NoAvailableUidError(message[, user, failed_at])	The assigned UID space has been exhausted.
NoScopesError(message[, location, field_path])	The user has no valid scopes and therefore cannot log in.
NotConfiguredError(message[, location, ...])	The requested operation was not configured.
NotFoundError(message[, location, field_path])	The named resource does not exist.
OAuthBearerError	An error that can be returned as a WWW-Authenticate challenge.
OAuthError	An OAuth-related error occurred.
OIDCError(message[, user, failed_at])	Response from the OpenID Connect provider was invalid or an error.
OIDCNotEnrolledError(message[, user, failed_at])	The user is not enrolled in the upstream OpenID Connect provider.
OIDCWebError(message, *[, failed_at, ...])	A web request to the OpenID Connect provider failed.
PermissionDeniedError(message[, location, ...])	The user does not have permission to perform this operation.
ProviderError(message[, user, failed_at])	Something failed while talking to an authentication provider.
ProviderWebError(message, *[, failed_at, ...])	A web request to an authentication provider failed.
ReturnUriMismatchError(message)	Specified return URI does not match return URI of registered client.
UnknownAlgorithmError(message[, user, failed_at])	The issuer key was for an unsupported algorithm.
UnknownKeyIdError(message[, user, failed_at])	The reqeusted key ID was not found for an issuer.
UnsupportedGrantTypeError	The grant type is not supported.
VerifyTokenError(message[, user, failed_at])	Base exception class for failure in verifying a token.

Class Inheritance Diagram

gafaelfawr.factory Module

Create Gafaelfawr components.

Classes

Factory(context, session, logger)	Build Gafaelfawr components.
ProcessContext(config, firestore, ...)	Per-process application context.

Class Inheritance Diagram

gafaelfawr.keypair Module

RSA key pair handling.

Classes

RSAKeyPair(private_key)

An RSA key pair with some simple helper functions.

Class Inheritance Diagram

gafaelfawr.middleware.state Module

State cookie management.

Classes

BaseState()	Base class for state information stored in a cookie.
StateMiddleware(app, *, cookie_name, state_class)	Middleware to read and update an encrypted state cookie.

Class Inheritance Diagram

gafaelfawr.models.admin Module

Representation of a token administrator.

Classes

Admin

A token administrator.

Class Inheritance Diagram

gafaelfawr.models.auth Module

Representation of authentication-related data.

Classes

APIConfig	Configuration information for the API.
APILoginResponse	Response to an API login request.
AuthChallenge(auth_type, realm)	Represents a WWW-Authenticate header for a simple challenge.
AuthError(value[, names, module, qualname, ...])	Valid authentication errors for a WWW-Authenticate header.
AuthErrorChallenge(auth_type, realm, error, ...)	Represents a WWW-Authenticate header for an error challenge.
AuthType(value[, names, module, qualname, ...])	Authentication types for the WWW-Authenticate header.
Satisfy(value[, names, module, qualname, ...])	Authorization strategies.
Scope	A known token scope.

Class Inheritance Diagram

gafaelfawr.models.enums Module

Enums used in Gafaelfawr models.

Notes

These are kept in a separate module because some models need to import ORM objects in order to define pagination cursors, but ORM objects often refer to enums for column definitions.

Classes

AdminChange(value[, names, module, ...])	Type of change made to a token admin.
TokenChange(value[, names, module, ...])	Type of change made to a token.
TokenType(value[, names, module, qualname, ...])	The class of token.

Class Inheritance Diagram

gafaelfawr.models.history Module

Representation of a token or admin history event.

Classes

AdminHistoryEntry	A record of a change to the token administrators.
TokenChangeHistoryCursor(previous, time, id)	Pagination cursor for token history entries.
TokenChangeHistoryEntry	A record of a change to a token.
TokenChangeHistoryRecord	A token change history entry populated from the database.

Class Inheritance Diagram

gafaelfawr.models.kubernetes Module

Models for Kubernetes operators.

Classes

GafaelfawrIngress	Representation of a GafaelfawrIngress resource.
GafaelfawrIngressConfig	Configuration settings for an ingress using Gafaelfawr for auth.
GafaelfawrIngressDelegate	Configuration for delegated tokens requested for a service.
GafaelfawrIngressDelegateInternal	Configuration for a delegated internal token.
GafaelfawrIngressDelegateNotebook	Configuration for a delegated notebook token.
GafaelfawrIngressMetadata	Metadata used to create an Ingress object.
GafaelfawrIngressPath	A path routing rule for an ingress.
GafaelfawrIngressPathBackend	Backend that serves a given path.
GafaelfawrIngressPathService	Service that serves a given path.
GafaelfawrIngressRule	A routing rule for an ingress.
GafaelfawrIngressRuleHTTP	Routing rules for HTTP access.
GafaelfawrIngressScopesAll	Represents scopes where all scopes are required.
GafaelfawrIngressScopesAnonymous	Represents anonymous access.
GafaelfawrIngressScopesAny	Represents scopes where any scope is sufficient.
GafaelfawrIngressScopesBase	Base class for specifying the required scopes.
GafaelfawrIngressSpec	Template for spec portion of Ingress resource.
GafaelfawrIngressTLS	A TLS certificate rule for an ingress.
GafaelfawrIngressTemplate	Template for Ingress created from GafaelfawrIngress resource.
GafaelfawrServicePortName	Port for a service.
GafaelfawrServicePortNumber	Port for a service.
GafaelfawrServiceToken	Representation of a GafaelfawrServiceToken resource.
GafaelfawrServiceTokenSpec	Holds the spec section of a GafaelfawrServiceToken resource.
KubernetesMetadata	The metadata section of a Kubernetes resource.
KubernetesResource	A Kubernetes resource being processed by an operator.
KubernetesResourceStatus(message, ...[, ...])	Represents the processing status of a Kubernetes resource.
PathType(value[, names, module, qualname, ...])	Matching types for paths in ingress rules.
StatusReason(value[, names, module, ...])	Reason for the status update of a GafaelfawrServiceToken.

Class Inheritance Diagram

gafaelfawr.models.ldap Module

Data models for LDAP.

Classes

LDAPUserData([name, email, uid, gid])

Data for a user from LDAP.

Class Inheritance Diagram

gafaelfawr.models.oidc Module

Representation of data for OpenID Connect support.

Classes

JWK	The schema for a JSON Web Key (RFCs 7517 and 7518).
JWKS	Schema for the /.well-known/jwks.json endpoint.
OIDCAuthorization	Represents an authorization for an OpenID Connect client.
OIDCAuthorizationCode	An OpenID Connect authorization code.
OIDCConfig	Schema for the /.well-known/openid-configuration endpoint.
OIDCScope(value[, names, module, qualname, ...])	A recognized OpenID Connect scope.
OIDCToken	Holds an encoded JWT.
OIDCTokenReply	A reply to a successful OpenID Connect token request.
OIDCVerifiedToken	Holds a verified JWT.

Class Inheritance Diagram

gafaelfawr.models.state Module

Representation of Gafaelfawr state stored in a cookie.

This is the Gafaelfawr version of BaseState, used by the StateMiddleware middleware. It holds the data that Gafaelfawr stores in a session cookie.

Classes

State([csrf, token, github, return_url, ...])

State information stored in a cookie.

Class Inheritance Diagram

gafaelfawr.models.token Module

Representation of an authentication token and associated data.

Classes

AdminTokenRequest	A request to create a new token via the admin interface.
NewToken	Response to a token creation request.
Token	An opaque token.
TokenBase	Base information about a token common to several representations.
TokenData	Data about a token stored in Redis.
TokenInfo	Information about a token.
TokenUserInfo	User metadata stored with the token.
UserTokenModifyRequest	The parameters of a user token that can be changed.
UserTokenRequest	The parameters of a user token that are under the user's control.

Class Inheritance Diagram

gafaelfawr.models.userinfo Module

Models for user metadata.

Classes

CADCUserInfo	User metadata required by the CADC authentication code.
Group	Information about a single group.
NotebookQuota	Notebook Aspect quota information for a user.
Quota	Quota information for a user.
UserInfo	Metadata about a user.

Class Inheritance Diagram

gafaelfawr.operator Package

Kubernetes operator framework.

This module imports all of the handlers for Gafaelfawr’s Kubernetes operator and serves as an entry point for Kopf.

gafaelfawr.operator.health Module

Kubernetes operator health checks.

Functions

get_health(memo, **_)

Health check for Gafaelfawr data stores.

gafaelfawr.operator.ingress Module

Kubernetes operator handlers for GafaelfawrIngress.

Functions

create(name, namespace, body, memo, **_)

Handle creation or modiication of a GafaelfawrIngress object.

gafaelfawr.operator.startup Module

Kubernetes operator startup and shutdown.

Functions

shutdown(memo, **_)	Shut down a running Kubernetes operator.
startup(memo, settings, **_)	Initialize global data for Kubernetes operators.

gafaelfawr.operator.tokens Module

Kubernetes operator handlers for GafaelfawrServiceTokens.

Functions

create(name, namespace, body, memo, **_)	Handle creation or modification of a GafaelfawrServiceToken object.
periodic(name, namespace, body, memo, **_)	Periodically re-check all GafaelfawrServiceToken objects.

gafaelfawr.providers.base Module

Base class for authentication providers.

Classes

Provider()

Abstract base class for authentication providers.

Class Inheritance Diagram

gafaelfawr.providers.github Module

GitHub authentication provider.

Classes

GitHubProvider(*, config, http_client, logger)

Authenticate a user with GitHub.

Class Inheritance Diagram

gafaelfawr.providers.oidc Module

OpenID Connect authentication provider.

Classes

OIDCProvider(*, config, verifier, ...)	Authenticate a user with GitHub.
OIDCTokenVerifier(config, http_client, logger)	Verify a JWT issued by an OpenID Connect provider.

Class Inheritance Diagram

gafaelfawr.pydantic Module

Pydantic data types for Gafaelfawr models.

Variables

IpAddress	Type alias.
Scopes	Type alias.
Timestamp	Type alias.

gafaelfawr.sentry Module

Setup code for exporting telemetry and traces to Sentry.

Functions

enable_telemetry()

Enable sending telemetry and trace information to Sentry.

gafaelfawr.services.admin Module

Manage the configured token administrators.

Classes

AdminService(*, admin_store, ...)

Manage the token administrators.

Class Inheritance Diagram

gafaelfawr.services.firestore Module

UID/GID assignment using Firestore.

Classes

FirestoreService(*, uid_cache, gid_cache, ...)

Manage UID and GID assignments using Firestore.

Class Inheritance Diagram

gafaelfawr.services.health Module

Health check for the Gafaelfawr service.

Classes

HealthCheckService(*, token_db_store, ...)

Check the health of the Gafaelfawr service.

Class Inheritance Diagram

gafaelfawr.services.kubernetes Module

Manage Kubernetes secrets.

Classes

KubernetesIngressService(config, storage, logger)	Manage Ingress resources with Gafaelfawr annotations.
KubernetesTokenService(*, token_service, ...)	Manage Gafaelfawr service tokens stored in Kubernetes secrets.

Class Inheritance Diagram

gafaelfawr.services.ldap Module

LDAP lookups for user information.

Classes

LDAPService(*, ldap, group_cache, ...)

Perform LDAP lookups for user information.

Class Inheritance Diagram

gafaelfawr.services.oidc Module

OpenID Connect identity provider support.

Classes

OIDCService(*, config, token_lifetime, ...)

Minimalist OpenID Connect identity provider.

Class Inheritance Diagram

gafaelfawr.services.token Module

Manage tokens.

Classes

TokenService(*, config, token_cache, ...)

Manage tokens.

Class Inheritance Diagram

gafaelfawr.services.token_cache Module

Cache for internal and notebook tokens.

Classes

TokenCacheService(*, config, internal_cache, ...)

Manage cache internal and notebook tokens.

Class Inheritance Diagram

gafaelfawr.services.userinfo Module

Service layer for user metadata.

Classes

UserInfoService(*, config, ldap, firestore, ...)

Retrieve user metadata from external systems.

Class Inheritance Diagram

gafaelfawr.storage.admin Module

Storage for token administrators.

Classes

AdminStore(session)

Stores and retrieves token administrators.

Class Inheritance Diagram

gafaelfawr.storage.firestore Module

Firestore storage layer for Gafaelfawr.

Classes

FirestoreStorage(client, logger)

Google Firestore storage layer.

Class Inheritance Diagram

gafaelfawr.storage.history Module

Storage for change and authentication history.

Classes

AdminHistoryStore(session)	Stores and retrieves the history of changes to token administrators.
TokenChangeHistoryStore(session)	Stores and retrieves the history of changes to tokens.

Class Inheritance Diagram

gafaelfawr.storage.kubernetes Module

Kubernetes storage layer for Gafaelfawr.

Classes

KubernetesIngressStorage(api_client, logger)	Kubernetes storage layer for ingress objects.
KubernetesTokenStorage(api_client, logger)	Kubernetes storage layer for service token objects.

Class Inheritance Diagram

gafaelfawr.storage.ldap Module

LDAP storage layer for Gafaelfawr.

Classes

LDAPStorage(config, pool, logger)

LDAP storage layer.

Class Inheritance Diagram

gafaelfawr.storage.oidc Module

Storage for OpenID Connect authorizations.

Classes

OIDCAuthorizationStore(storage)

Stores and retrieves OpenID Connect authorizations.

Class Inheritance Diagram

gafaelfawr.storage.token Module

Storage for tokens.

Classes

TokenDatabaseStore(session)	Stores and manipulates tokens in the database.
TokenRedisStore(storage, slack_client, logger)	Stores and retrieves token data in Redis.

Class Inheritance Diagram

gafaelfawr.templates Module

Templated responses.

Since the primary UI is provided by JavaScript, these are generally used only for error messages.

Variables

templates

The template manager.

gafaelfawr.util Module

General utility functions.

Functions

add_padding(encoded)	Add padding to base64 encoded bytes.
base64_to_number(data)	Convert base64-encoded bytes to an integer.
group_name_for_github_team(organization, team)	Convert a GitHub organization and team to a group name.
is_bot_user(username)	Return whether the given username is a bot user.
number_to_base64(data)	Convert an integer to base64-encoded bytes in big endian order.
random_128_bits()	Generate random 128 bits encoded in base64 without padding.