Python internal API#
gafaelfawr Package#
The Gafaelfawr service.
Variables#
The application version string (PEP 440 / SemVer compatible). |
gafaelfawr.auth Module#
Utility functions for manipulating authentication headers.
Functions#
|
Remove Gafaelfawr tokens from |
|
Remove Gafaelfawr cookies from cookie headers. |
|
Convert an exception into an HTTP error with |
|
Construct exception for a 401 response with AJAX handling. |
|
Find a handle or 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#
Base class for caches managed by a cache dependency. |
|
|
A cache of UIDs or GIDs. |
Cache for internal tokens. |
|
Base class for a cache with per-user locking. |
|
|
A cache of LDAP data. |
Cache for notebook tokens. |
|
Base class for a cache of internal or notebook tokens. |
|
|
Helper class for managing per-user locks. |
Variables#
Type of content stored in a cache. |
Class Inheritance Diagram#

gafaelfawr.config Module#
Configuration for Gafaelfawr.
There are two, mostly-parallel models defined here. The ones ending in
Settings
are the pydantic models used to read the configuration file from
disk, the root of which is Settings
. This is then processed and broken up
into configuration dataclasses for various components and then exposed to the
rest of Gafaelfawr as the Config
object.
Classes#
|
Configuration for Gafaelfawr. |
|
Configuration for Firestore-based UID/GID assignment. |
pydantic model of Firestore configuration. |
|
|
Configuration for ForgeRock Identity Management server. |
pydantic model of ForgeRock Identity Management configuration. |
|
|
Metadata for GitHub authentication. |
pydantic model of GitHub configuration. |
|
|
Configuration for LDAP support. |
pydantic model of LDAP configuration. |
|
|
Quota settings for the Notebook Aspect. |
Quota settings for the Notebook Aspect. |
|
|
Configuration for OpenID Connect authentication. |
|
Configuration for a single OpenID Connect client of our server. |
|
Configuration for the OpenID Connect server. |
pydantic model of issuer configuration. |
|
pydantic model of OpenID Connect configuration. |
|
|
Quota settings. |
|
One grant of quotas. |
One grant of quotas. |
|
Quota settings. |
|
pydantic model of Gafaelfawr configuration file. |
Class Inheritance Diagram#

gafaelfawr.constants Module#
Constants for Gafaelfawr.
Variables#
Regex matching all valid actors (including |
|
JWT algorithm to use for all tokens. |
|
Regex matching a valid username that is also a bot user. |
|
Retention of old token change history entries. |
|
Default configuration path. |
|
Name of the state cookie. |
|
Regex matching a valid cursor. |
|
Minimum GID for groups. |
|
Maximum gid for groups. |
|
Regex matching all valid group names. |
|
Timeout (in seconds) for outbound HTTP requests to auth providers. |
|
How many UID or GID values to cache in memory. |
|
Timeout (in seconds) for the Kubernetes operator watch operation. |
|
How long (in seconds) to delay timers after startup and changes. |
|
How frequently (in seconds) to validate service tokens stored in secrets. |
|
Maximum numbr of entries in LDAP caches. |
|
Lifetime of the LDAP caches in seconds. |
|
Timeout (in seconds) for LDAP queries. |
|
Minimum expiration lifetime for a token. |
|
Code snippet to put into NGINX configuration for each ingress. |
|
How long (in seconds) an authorization code is good for. |
|
How long (in seconds) to initially wait after a Redis failure. |
|
Maximum delay (in seconds) to wait after a Redis failure. |
|
Size of the Redis connection pool. |
|
How long to wait for a connection from the pool before giving up. |
|
How many times to try to connect to Redis before giving up. |
|
Regex matching a valid scope. |
|
How many internal or notebook tokens to cache in memory. |
|
Minimum UID for bot users. |
|
Maximum UID for bot users. |
|
Minimum UID for users. |
|
Regex matching all valid usernames. |
gafaelfawr.dependencies.auth Module#
Authentication dependencies for FastAPI.
Functions#
|
Require that a request be authenticated with an OpenID Connect token. |
Classes#
|
Dependency to verify user authentication. |
|
Authenticate a read API. |
|
Authenticate a write API. |
Class Inheritance Diagram#

gafaelfawr.dependencies.config Module#
Config dependency for FastAPI.
Classes#
Provides the configuration as a dependency. |
Variables#
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#
Provide a per-request context as a FastAPI dependency. |
|
|
Holds the incoming request and its surrounding context. |
Variables#
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#
|
Validate a return URL in a |
|
Validate a return URL in an |
|
Validate a return URL in an |
gafaelfawr.exceptions Module#
Exceptions for Gafaelfawr.
Classes#
|
The user tried to reuse the name of a token. |
|
Error in external user information source. |
|
Cannot retrieve the keys from an issuer. |
|
An error occurred while reading or updating Firestore data. |
|
Firestore has not been initialized. |
|
An error occurred querying ForgeRock Identity Management. |
|
An HTTP error occurred querying ForgeRock Identity Management. |
|
The response from GitHub for a request was invalid. |
|
A web request to GitHub failed. |
|
Represents an input validation error. |
The provided token does not have the right authorization scope. |
|
The provided client_id and client_secret could not be validated. |
|
|
Invalid or missing CSRF token. |
|
The provided cursor was invalid. |
|
The |
|
The provided token expiration time was invalid. |
The provided authorization code is not valid. |
|
|
The provided IP address has invalid syntax. |
|
The |
The provided Authorization header could not be parsed. |
|
|
Client specified an unsafe return URL. |
|
The provided token scopes are invalid or not available. |
|
One of the claims in the token is of an invalid format. |
The provided token was invalid. |
|
|
An error occurred during Kubernetes secret processing. |
|
A Kubernetes object could not be parsed. |
|
User or group information in LDAP was invalid or LDAP calls failed. |
|
The token is missing the required GID claim. |
|
The token is missing the required UID claim. |
|
The token is missing the required username claim. |
|
The assigned UID space has been exhausted. |
|
The assigned UID space has been exhausted. |
|
The requested operation was not configured. |
|
The named resource does not exist. |
An OAuth-related error occurred. |
|
An error that can be returned as a |
|
|
Response from the OpenID Connect provider was invalid or an error. |
|
The user is not enrolled in the upstream OpenID Connect provider. |
|
A web request to the OpenID Connect provider failed. |
|
The user does not have permission to perform this operation. |
|
Something failed while talking to an authentication provider. |
|
A web request to an authentication provider failed. |
The client is not authorized to request an authorization code. |
|
|
The issuer key was for an unsupported algorithm. |
|
The reqeusted key ID was not found for an issuer. |
The grant type is not supported. |
|
|
Base exception class for failure in verifying a token. |
Class Inheritance Diagram#

gafaelfawr.factory Module#
Create Gafaelfawr components.
Classes#
|
Build Gafaelfawr components. |
|
Per-process application context. |
Class Inheritance Diagram#

gafaelfawr.keypair Module#
RSA key pair handling.
Classes#
|
An RSA key pair with some simple helper functions. |
Class Inheritance Diagram#

gafaelfawr.middleware.state Module#
State cookie management.
Classes#
Base class for state information stored in a cookie. |
|
|
Middleware to read and update an encrypted state cookie. |
Variables#
Type of data stored in the state cookie. |
Class Inheritance Diagram#

gafaelfawr.models.admin Module#
Representation of a token administrator.
Classes#
A token administrator. |
Class Inheritance Diagram#

gafaelfawr.models.auth Module#
Representation of authentication-related data.
Classes#
Configuration information for the API. |
|
Response to an API login request. |
|
|
Represents a |
|
Valid authentication errors for a WWW-Authenticate header. |
|
Represents a |
|
Authentication types for the WWW-Authenticate header. |
|
Authorization strategies. |
A known token scope. |
Class Inheritance Diagram#

gafaelfawr.models.history Module#
Representation of a token or admin history event.
Classes#
|
Type of change made to a token admin. |
A record of a change to the token administrators. |
|
|
Pagination cursor for history entries. |
|
Encapsulates paginated history entries with pagination information. |
|
Type of change made to a token. |
A record of a change to a token. |
Variables#
Type of a history entry in a paginated list. |
Class Inheritance Diagram#

gafaelfawr.models.kubernetes Module#
Models for Kubernetes operators.
Classes#
Representation of a |
|
Configuration settings for an ingress using Gafaelfawr for auth. |
|
Configuration for delegated tokens requested for a service. |
|
Configuration for a delegated internal token. |
|
Configuration for a delegated notebook token. |
|
Metadata used to create an |
|
A path routing rule for an ingress. |
|
Backend that serves a given path. |
|
Service that serves a given path. |
|
A routing rule for an ingress. |
|
Routing rules for HTTP access. |
|
Represents scopes where all scopes are required. |
|
Represents anonymous access. |
|
Represents scopes where any scope is sufficient. |
|
Base class for specifying the required scopes. |
|
Template for |
|
A TLS certificate rule for an ingress. |
|
Template for |
|
Port for a service. |
|
Port for a service. |
|
Representation of a |
|
Holds the |
|
The metadata section of a Kubernetes resource. |
|
A Kubernetes resource being processed by an operator. |
|
|
Represents the processing status of a Kubernetes resource. |
|
Matching types for paths in ingress rules. |
|
Reason for the status update of a GafaelfawrServiceToken. |
Class Inheritance Diagram#

gafaelfawr.models.ldap Module#
Data models for LDAP.
Classes#
|
Data for a user from LDAP. |
Class Inheritance Diagram#

gafaelfawr.models.link Module#
Representation for a Link
HTTP header.
Classes#
|
Holds the data returned in an RFC 8288 |
Class Inheritance Diagram#

gafaelfawr.models.oidc Module#
Representation of data for OpenID Connect support.
Classes#
The schema for a JSON Web Key (RFCs 7517 and 7518). |
|
Schema for the |
|
Represents an authorization for an OpenID Connect client. |
|
An OpenID Connect authorization code. |
|
Schema for the |
|
Holds an encoded JWT. |
|
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 ~gafaelfawr.middleware.state.BaseState, used by the ~gafaelfawr.middleware.state.StateMiddleware middleware. It holds the data that Gafaelfawr stores in a session cookie.
Classes#
|
State information stored in a cookie. |
Class Inheritance Diagram#

gafaelfawr.models.token Module#
Representation of an authentication token and associated data.
Classes#
A request to create a new token via the admin interface. |
|
Response to a token creation request. |
|
Notebook Aspect quota information for a user. |
|
Quota information for a user. |
|
An opaque token. |
|
Base information about a token common to several representations. |
|
Data about a token stored in Redis. |
|
Information about a single group. |
|
Information about a token returned by the token-info endpoint. |
|
|
The class of token. |
The information about a user stored with their token. |
|
The parameters of a user token that are under the user's control. |
|
The parameters of a user token that can be changed. |
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.ingress Module#
Kubernetes operator handlers for GafaelfawrIngress.
Functions#
|
Handle creation or modiication of a GafaelfawrIngress object. |
gafaelfawr.operator.startup Module#
Kubernetes operator startup and shutdown.
Functions#
|
Initialize global data for Kubernetes operators. |
|
Shut down a running Kubernetes operator. |
gafaelfawr.operator.tokens Module#
Kubernetes operator handlers for GafaelfawrServiceTokens.
Functions#
|
Handle creation or modification of a GafaelfawrServiceToken object. |
|
Periodically re-check all GafaelfawrServiceToken objects. |
gafaelfawr.providers.base Module#
Base class for authentication providers.
Classes#
|
Abstract base class for authentication providers. |
Class Inheritance Diagram#

gafaelfawr.providers.github Module#
GitHub authentication provider.
Classes#
|
Authenticate a user with GitHub. |
Class Inheritance Diagram#

gafaelfawr.providers.oidc Module#
OpenID Connect authentication provider.
Classes#
|
Authenticate a user with GitHub. |
|
Verify a JWT issued by an OpenID Connect provider. |
Class Inheritance Diagram#

gafaelfawr.services.admin Module#
Manage the configured token administrators.
Classes#
|
Manage the token administrators. |
Class Inheritance Diagram#

gafaelfawr.services.firestore Module#
UID/GID assignment using Firestore.
Classes#
|
Manage UID and GID assignments using Firestore. |
Class Inheritance Diagram#

gafaelfawr.services.kubernetes Module#
Manage Kubernetes secrets.
Classes#
|
Manage |
|
Manage Gafaelfawr service tokens stored in Kubernetes secrets. |
Class Inheritance Diagram#

gafaelfawr.services.ldap Module#
LDAP lookups for user information.
Classes#
|
Perform LDAP lookups for user information. |
Class Inheritance Diagram#

gafaelfawr.services.oidc Module#
OpenID Connect identity provider support.
Classes#
|
Minimalist OpenID Connect identity provider. |
Class Inheritance Diagram#

gafaelfawr.services.token Module#
Manage tokens.
Classes#
|
Manage tokens. |
Class Inheritance Diagram#

gafaelfawr.services.token_cache Module#
Cache for internal and notebook tokens.
Classes#
|
Manage cache internal and notebook tokens. |
Class Inheritance Diagram#

gafaelfawr.services.userinfo Module#
Service and caching layer for user metadata.
Classes#
|
Retrieve user metadata from external systems for OIDC authentication. |
|
Retrieve user metadata from external systems. |
Class Inheritance Diagram#

gafaelfawr.storage.admin Module#
Storage for token administrators.
Classes#
|
Stores and retrieves token administrators. |
Class Inheritance Diagram#

gafaelfawr.storage.firestore Module#
Firestore storage layer for Gafaelfawr.
Classes#
|
Google Firestore storage layer. |
Class Inheritance Diagram#

gafaelfawr.storage.forgerock Module#
ForgeRock Identity Management storage layer for Gafaelfawr.
Classes#
|
Perform ForgeRock Identity Management lookups. |
Class Inheritance Diagram#

gafaelfawr.storage.history Module#
Storage for change and authentication history.
Classes#
|
Stores and retrieves the history of changes to token administrators. |
|
Stores and retrieves the history of changes to tokens. |
Class Inheritance Diagram#

gafaelfawr.storage.kubernetes Module#
Kubernetes storage layer for Gafaelfawr.
Classes#
|
Kubernetes storage layer for ingress objects. |
|
Kubernetes storage layer for service token objects. |
Class Inheritance Diagram#

gafaelfawr.storage.ldap Module#
LDAP storage layer for Gafaelfawr.
Classes#
|
LDAP storage layer. |
Class Inheritance Diagram#

gafaelfawr.storage.oidc Module#
Storage for OpenID Connect authorizations.
Classes#
|
Stores and retrieves OpenID Connect authorizations. |
Class Inheritance Diagram#

gafaelfawr.storage.token Module#
Storage for tokens.
Classes#
|
Stores and manipulates tokens in the database. |
|
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#
The template manager. |
gafaelfawr.util Module#
General utility functions.
Functions#
|
Add padding to base64 encoded bytes. |
|
Convert base64-encoded bytes to an integer. |
|
Return whether the given username is a bot user. |
Pydantic validator for IP address fields. |
|
Pydantic validator for scope fields. |
|
Pydantic validator for timedelta fields. |
|
|
Convert an integer to base64-encoded bytes in big endian order. |
Generate random 128 bits encoded in base64 without padding. |