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#

Inheritance diagram of gafaelfawr.cache.BaseCache, gafaelfawr.cache.IdCache, gafaelfawr.cache.InternalTokenCache, gafaelfawr.cache.LDAPCache, gafaelfawr.cache.NotebookTokenCache, gafaelfawr.cache.PerUserCache, gafaelfawr.cache.TokenCache, gafaelfawr.cache.UserLockManager

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([_case_sensitive, ...])

Base class for Pydantic settings supporting camel-case.

Config(**data)

Configuration for Gafaelfawr.

CookieParameters

Settings passed to fastapi.Response.set_cookie to set cookies.

EnvFirstSettings([_case_sensitive, ...])

Base class for Pydantic settings with environment overrides.

FirestoreConfig(**data)

Configuration for Firestore-based UID/GID assignment.

GitHubConfig([_case_sensitive, ...])

Configuration for the GitHub authentication provider.

GitHubGroup(**data)

An individual GitHub team.

GitHubGroupTeam(**data)

Specification for a GitHub team.

LDAPConfig([_case_sensitive, ...])

Configuration for LDAP support.

OIDCClient(**data)

Configuration for a single OpenID Connect client of our server.

OIDCConfig([_case_sensitive, ...])

Configuration for a generic OpenID Connect authentication provider.

OIDCServerConfig(**data)

Configuration for the OpenID Connect server.

QuotaConfig(**data)

Quota configuration.

Variables#

HttpsUrl

URL type that accepts only https URLs.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.config.CamelCaseSettings, gafaelfawr.config.Config, gafaelfawr.config.CookieParameters, gafaelfawr.config.EnvFirstSettings, gafaelfawr.config.FirestoreConfig, gafaelfawr.config.GitHubConfig, gafaelfawr.config.GitHubGroup, gafaelfawr.config.GitHubGroupTeam, gafaelfawr.config.LDAPConfig, gafaelfawr.config.OIDCClient, gafaelfawr.config.OIDCConfig, gafaelfawr.config.OIDCServerConfig, gafaelfawr.models.quota.QuotaConfig

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_EPHEMERAL_POOL_SIZE

Size of the ephemeral Redis connection pool (without rate limiting.)

REDIS_PERSISTENT_POOL_SIZE

Size of the persistent Redis connection pool.

REDIS_POOL_TIMEOUT

Seconds to wait for a connection from the pool before giving up.

REDIS_RATE_LIMIT_POOL_SIZE

Size of the rate limiting Redis connection pool.

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(*[, allow_cookies, ...])

Dependency to verify user authentication.

AuthenticateRead(*[, allow_cookies, ...])

Authenticate a read API.

AuthenticateWrite(*[, allow_cookies, ...])

Authenticate a write API.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.dependencies.auth.Authenticate, gafaelfawr.dependencies.auth.AuthenticateRead, gafaelfawr.dependencies.auth.AuthenticateWrite

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#

Inheritance diagram of gafaelfawr.dependencies.config.ConfigDependency

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#

Inheritance diagram of gafaelfawr.dependencies.context.ContextDependency, gafaelfawr.dependencies.context.RequestContext

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(**data)

Current count of the number of active user sessions.

ActiveUserTokensEvent(**data)

Current count of the number of active user tokens.

AuthBotEvent(**data)

An authentication to a service by a bot user.

AuthUserEvent(**data)

An authentication to a service by a user.

BaseAuthEvent(**data)

Base class for authentication events.

FrontendEvents()

Event publishers for Gafaelfawr frontend events.

LoginAttemptEvent(**data)

User attempted to log in and was directed to the identity provider.

LoginEnrollmentEvent(**data)

Authenticated but unknown user redirected to the enrollment flow.

LoginFailureEvent(**data)

User authentication failed.

LoginSuccessEvent(**data)

User successfully authenticated.

RateLimitEvent(**data)

Authentication request rejected by API rate limits.

StateEvents()

Event publishers for metrics about the current Gafaelfawr state.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.events.ActiveUserSessionsEvent, gafaelfawr.events.ActiveUserTokensEvent, gafaelfawr.events.AuthBotEvent, gafaelfawr.events.AuthUserEvent, gafaelfawr.events.BaseAuthEvent, gafaelfawr.events.FrontendEvents, gafaelfawr.events.LoginAttemptEvent, gafaelfawr.events.LoginEnrollmentEvent, gafaelfawr.events.LoginFailureEvent, gafaelfawr.events.LoginSuccessEvent, gafaelfawr.events.RateLimitEvent, gafaelfawr.events.StateEvents

gafaelfawr.exceptions Module#

Exceptions for Gafaelfawr.

Classes#

DatabaseSchemaError(message[, user, failed_at])

Gafaelfawr database schema is invalid.

DisallowedCORSRequestError

The OPTIONS CORS preflight check was rejected.

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.

FirestoreAPIError(message, *, errors[, reason])

A Google API error occurred while talking to Firestore.

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.

KubernetesIngressError

The GafaelfawrIngress configuration is invalid.

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.

OptionsNotSupportedError

The OPTIONS request is not a valid CORS preflight request.

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#

Inheritance diagram of gafaelfawr.exceptions.DatabaseSchemaError, gafaelfawr.exceptions.DisallowedCORSRequestError, gafaelfawr.exceptions.DuplicateAdminError, gafaelfawr.exceptions.DuplicateTokenNameError, gafaelfawr.exceptions.ExternalUserInfoError, gafaelfawr.exceptions.FetchKeysError, gafaelfawr.exceptions.FirestoreAPIError, gafaelfawr.exceptions.FirestoreError, gafaelfawr.exceptions.FirestoreNotInitializedError, gafaelfawr.exceptions.GitHubError, gafaelfawr.exceptions.GitHubWebError, gafaelfawr.exceptions.InputValidationError, gafaelfawr.exceptions.InsufficientScopeError, gafaelfawr.exceptions.InvalidCSRFError, gafaelfawr.exceptions.InvalidClientError, gafaelfawr.exceptions.InvalidClientIdError, gafaelfawr.exceptions.InvalidDelegateToError, gafaelfawr.exceptions.InvalidExpiresError, gafaelfawr.exceptions.InvalidGrantError, gafaelfawr.exceptions.InvalidIPAddressError, gafaelfawr.exceptions.InvalidMinimumLifetimeError, gafaelfawr.exceptions.InvalidRequestError, gafaelfawr.exceptions.InvalidReturnURLError, gafaelfawr.exceptions.InvalidScopesError, gafaelfawr.exceptions.InvalidServiceError, gafaelfawr.exceptions.InvalidTokenClaimsError, gafaelfawr.exceptions.InvalidTokenError, gafaelfawr.exceptions.KubernetesError, gafaelfawr.exceptions.KubernetesIngressError, gafaelfawr.exceptions.KubernetesObjectError, gafaelfawr.exceptions.LDAPError, gafaelfawr.exceptions.MissingGIDClaimError, gafaelfawr.exceptions.MissingUIDClaimError, gafaelfawr.exceptions.MissingUsernameClaimError, gafaelfawr.exceptions.NoAvailableGidError, gafaelfawr.exceptions.NoAvailableUidError, gafaelfawr.exceptions.NoScopesError, gafaelfawr.exceptions.NotConfiguredError, gafaelfawr.exceptions.NotFoundError, gafaelfawr.exceptions.OAuthBearerError, gafaelfawr.exceptions.OAuthError, gafaelfawr.exceptions.OIDCError, gafaelfawr.exceptions.OIDCNotEnrolledError, gafaelfawr.exceptions.OIDCWebError, gafaelfawr.exceptions.OptionsNotSupportedError, gafaelfawr.exceptions.PermissionDeniedError, gafaelfawr.exceptions.ProviderError, gafaelfawr.exceptions.ProviderWebError, gafaelfawr.exceptions.ReturnUriMismatchError, gafaelfawr.exceptions.UnknownAlgorithmError, gafaelfawr.exceptions.UnknownKeyIdError, gafaelfawr.exceptions.UnsupportedGrantTypeError, gafaelfawr.exceptions.VerifyTokenError

gafaelfawr.factory Module#

Create Gafaelfawr components.

Classes#

Factory(context, session, logger)

Build Gafaelfawr components.

ProcessContext(config, firestore, ...)

Per-process application context.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.factory.Factory, gafaelfawr.factory.ProcessContext

gafaelfawr.keypair Module#

RSA key pair handling.

Classes#

RSAKeyPair(private_key)

An RSA key pair with some simple helper functions.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.keypair.RSAKeyPair

gafaelfawr.middleware.state Module#

State cookie management.

Classes#

BaseState()

Base class for state information stored in a cookie.

StateMiddleware(app, *, cookie_name, ...)

Middleware to read and update an encrypted state cookie.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.middleware.state.BaseState, gafaelfawr.middleware.state.StateMiddleware

gafaelfawr.models.admin Module#

Representation of a token administrator.

Classes#

Admin(**data)

A token administrator.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.models.admin.Admin

gafaelfawr.models.auth Module#

Representation of authentication-related data.

Classes#

APIConfig(**data)

Configuration information for the API.

APILoginResponse(**data)

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(**data)

A known token scope.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.models.auth.APIConfig, gafaelfawr.models.auth.APILoginResponse, gafaelfawr.models.auth.AuthChallenge, gafaelfawr.models.auth.AuthError, gafaelfawr.models.auth.AuthErrorChallenge, gafaelfawr.models.auth.AuthType, gafaelfawr.models.auth.Satisfy, gafaelfawr.models.auth.Scope

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#

Inheritance diagram of gafaelfawr.models.enums.AdminChange, gafaelfawr.models.enums.TokenChange, gafaelfawr.models.enums.TokenType

gafaelfawr.models.history Module#

Representation of a token or admin history event.

Classes#

AdminHistoryEntry(**data)

A record of a change to the token administrators.

TokenChangeHistoryCursor(previous, time, id)

Pagination cursor for token history entries.

TokenChangeHistoryEntry(**data)

A record of a change to a token.

TokenChangeHistoryRecord(**data)

A token change history entry populated from the database.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.models.history.AdminHistoryEntry, gafaelfawr.models.history.TokenChangeHistoryCursor, gafaelfawr.models.history.TokenChangeHistoryEntry, gafaelfawr.models.history.TokenChangeHistoryRecord

gafaelfawr.models.kubernetes Module#

Models for Kubernetes operators.

Classes#

GafaelfawrIngress(**data)

Representation of a GafaelfawrIngress resource.

GafaelfawrIngressConfig(**data)

Configuration settings for an ingress using Gafaelfawr for auth.

GafaelfawrIngressDelegate(**data)

Configuration for delegated tokens requested for a service.

GafaelfawrIngressDelegateInternal(**data)

Configuration for a delegated internal token.

GafaelfawrIngressDelegateNotebook(**data)

Configuration for a delegated notebook token.

GafaelfawrIngressMetadata(**data)

Metadata used to create an Ingress object.

GafaelfawrIngressPath(**data)

A path routing rule for an ingress.

GafaelfawrIngressPathBackend(**data)

Backend that serves a given path.

GafaelfawrIngressPathService(**data)

Service that serves a given path.

GafaelfawrIngressRule(**data)

A routing rule for an ingress.

GafaelfawrIngressRuleHTTP(**data)

Routing rules for HTTP access.

GafaelfawrIngressScopesAll(**data)

Represents scopes where all scopes are required.

GafaelfawrIngressScopesAnonymous(**data)

Represents anonymous access.

GafaelfawrIngressScopesAny(**data)

Represents scopes where any scope is sufficient.

GafaelfawrIngressScopesBase(**data)

Base class for specifying the required scopes.

GafaelfawrIngressSpec(**data)

Template for spec portion of Ingress resource.

GafaelfawrIngressTLS(**data)

A TLS certificate rule for an ingress.

GafaelfawrIngressTemplate(**data)

Template for Ingress created from GafaelfawrIngress resource.

GafaelfawrServicePortName(**data)

Port for a service.

GafaelfawrServicePortNumber(**data)

Port for a service.

GafaelfawrServiceToken(**data)

Representation of a GafaelfawrServiceToken resource.

GafaelfawrServiceTokenSpec(**data)

Holds the spec section of a GafaelfawrServiceToken resource.

KubernetesMetadata(**data)

The metadata section of a Kubernetes resource.

KubernetesResource(**data)

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#

Inheritance diagram of gafaelfawr.models.kubernetes.GafaelfawrIngress, gafaelfawr.models.kubernetes.GafaelfawrIngressConfig, gafaelfawr.models.kubernetes.GafaelfawrIngressDelegate, gafaelfawr.models.kubernetes.GafaelfawrIngressDelegateInternal, gafaelfawr.models.kubernetes.GafaelfawrIngressDelegateNotebook, gafaelfawr.models.kubernetes.GafaelfawrIngressMetadata, gafaelfawr.models.kubernetes.GafaelfawrIngressPath, gafaelfawr.models.kubernetes.GafaelfawrIngressPathBackend, gafaelfawr.models.kubernetes.GafaelfawrIngressPathService, gafaelfawr.models.kubernetes.GafaelfawrIngressRule, gafaelfawr.models.kubernetes.GafaelfawrIngressRuleHTTP, gafaelfawr.models.kubernetes.GafaelfawrIngressScopesAll, gafaelfawr.models.kubernetes.GafaelfawrIngressScopesAnonymous, gafaelfawr.models.kubernetes.GafaelfawrIngressScopesAny, gafaelfawr.models.kubernetes.GafaelfawrIngressScopesBase, gafaelfawr.models.kubernetes.GafaelfawrIngressSpec, gafaelfawr.models.kubernetes.GafaelfawrIngressTLS, gafaelfawr.models.kubernetes.GafaelfawrIngressTemplate, gafaelfawr.models.kubernetes.GafaelfawrServicePortName, gafaelfawr.models.kubernetes.GafaelfawrServicePortNumber, gafaelfawr.models.kubernetes.GafaelfawrServiceToken, gafaelfawr.models.kubernetes.GafaelfawrServiceTokenSpec, gafaelfawr.models.kubernetes.KubernetesMetadata, gafaelfawr.models.kubernetes.KubernetesResource, gafaelfawr.models.kubernetes.KubernetesResourceStatus, gafaelfawr.models.kubernetes.PathType, gafaelfawr.models.kubernetes.StatusReason

gafaelfawr.models.ldap Module#

Data models for LDAP.

Classes#

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

Data for a user from LDAP.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.models.ldap.LDAPUserData

gafaelfawr.models.oidc Module#

Representation of data for OpenID Connect support.

Classes#

JWK(**data)

The schema for a JSON Web Key (RFCs 7517 and 7518).

JWKS(**data)

Schema for the /.well-known/jwks.json endpoint.

OIDCAuthorization(**data)

Represents an authorization for an OpenID Connect client.

OIDCAuthorizationCode(**data)

An OpenID Connect authorization code.

OIDCConfig(**data)

Schema for the /.well-known/openid-configuration endpoint.

OIDCScope(value[, names, module, qualname, ...])

A recognized OpenID Connect scope.

OIDCToken(**data)

Holds an encoded JWT.

OIDCTokenReply(**data)

A reply to a successful OpenID Connect token request.

OIDCVerifiedToken(**data)

Holds a verified JWT.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.models.oidc.JWK, gafaelfawr.models.oidc.JWKS, gafaelfawr.models.oidc.OIDCAuthorization, gafaelfawr.models.oidc.OIDCAuthorizationCode, gafaelfawr.models.oidc.OIDCConfig, gafaelfawr.models.oidc.OIDCScope, gafaelfawr.models.oidc.OIDCToken, gafaelfawr.models.oidc.OIDCTokenReply, gafaelfawr.models.oidc.OIDCVerifiedToken

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(**data)

State information stored in a cookie.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.models.state.State

gafaelfawr.models.token Module#

Representation of an authentication token and associated data.

Classes#

AdminTokenRequest(**data)

A request to create a new token via the admin interface.

NewToken(**data)

Response to a token creation request.

Token(**data)

An opaque token.

TokenBase(**data)

Base information about a token common to several representations.

TokenData(**data)

Data about a token stored in Redis.

TokenInfo(**data)

Information about a token.

TokenUserInfo(**data)

User metadata stored with the token.

UserTokenModifyRequest(**data)

The parameters of a user token that can be changed.

UserTokenRequest(**data)

The parameters of a user token that are under the user's control.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.models.token.AdminTokenRequest, gafaelfawr.models.token.NewToken, gafaelfawr.models.token.Token, gafaelfawr.models.token.TokenBase, gafaelfawr.models.token.TokenData, gafaelfawr.models.token.TokenInfo, gafaelfawr.models.token.TokenUserInfo, gafaelfawr.models.token.UserTokenModifyRequest, gafaelfawr.models.token.UserTokenRequest

gafaelfawr.models.userinfo Module#

Models for user metadata.

Classes#

Group(**data)

Information about a single group.

Quota(**data)

Quota information for a user.

RateLimitStatus(limit, used, remaining, ...)

Current status of rate limiting for a user for one API.

UserInfo(**data)

Metadata about a user.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.models.userinfo.Group, gafaelfawr.models.quota.Quota, gafaelfawr.models.userinfo.RateLimitStatus, gafaelfawr.models.userinfo.UserInfo

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#

Inheritance diagram of gafaelfawr.providers.base.Provider

gafaelfawr.providers.github Module#

GitHub authentication provider.

Classes#

GitHubProvider(*, config, http_client, logger)

Authenticate a user with GitHub.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.providers.github.GitHubProvider

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#

Inheritance diagram of gafaelfawr.providers.oidc.OIDCProvider, gafaelfawr.providers.oidc.OIDCTokenVerifier

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#

Inheritance diagram of gafaelfawr.services.admin.AdminService

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#

Inheritance diagram of gafaelfawr.services.firestore.FirestoreService

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#

Inheritance diagram of gafaelfawr.services.health.HealthCheckService

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#

Inheritance diagram of gafaelfawr.services.kubernetes.KubernetesIngressService, gafaelfawr.services.kubernetes.KubernetesTokenService

gafaelfawr.services.ldap Module#

LDAP lookups for user information.

Classes#

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

Perform LDAP lookups for user information.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.services.ldap.LDAPService

gafaelfawr.services.oidc Module#

OpenID Connect identity provider support.

Classes#

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

Minimalist OpenID Connect identity provider.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.services.oidc.OIDCService

gafaelfawr.services.token Module#

Manage tokens.

Classes#

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

Manage tokens.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.services.token.TokenService

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#

Inheritance diagram of gafaelfawr.services.token_cache.TokenCacheService

gafaelfawr.services.userinfo Module#

Service layer for user metadata.

Classes#

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

Retrieve user metadata from external systems.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.services.userinfo.UserInfoService

gafaelfawr.storage.admin Module#

Storage for token administrators.

Classes#

AdminStore(session)

Stores and retrieves token administrators.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.storage.admin.AdminStore

gafaelfawr.storage.firestore Module#

Firestore storage layer for Gafaelfawr.

Classes#

FirestoreStorage(client, logger)

Google Firestore storage layer.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.storage.firestore.FirestoreStorage

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#

Inheritance diagram of gafaelfawr.storage.history.AdminHistoryStore, gafaelfawr.storage.history.TokenChangeHistoryStore

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#

Inheritance diagram of gafaelfawr.storage.kubernetes.KubernetesIngressStorage, gafaelfawr.storage.kubernetes.KubernetesTokenStorage

gafaelfawr.storage.ldap Module#

LDAP storage layer for Gafaelfawr.

Classes#

LDAPStorage(config, pool, logger)

LDAP storage layer.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.storage.ldap.LDAPStorage

gafaelfawr.storage.oidc Module#

Storage for OpenID Connect authorizations.

Classes#

OIDCAuthorizationStore(storage)

Stores and retrieves OpenID Connect authorizations.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.storage.oidc.OIDCAuthorizationStore

gafaelfawr.storage.quota Module#

Storage layer for quota overrides.

Classes#

QuotaOverridesStore(storage, slack_client, ...)

Stores and retrieves quota overrides in Redis.

Class Inheritance Diagram#

Inheritance diagram of gafaelfawr.storage.quota.QuotaOverridesStore

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#

Inheritance diagram of gafaelfawr.storage.token.TokenDatabaseStore, gafaelfawr.storage.token.TokenRedisStore

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.types Module#

Pydantic data types for Gafaelfawr models.

Variables#

IpAddress

Type alias.

Scopes

Type alias.

Timestamp

Type alias.

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.