forward_auth¶

Interface library for providing API Gateways with Identity and Access Proxy information.

It is required to integrate with OAuth2 Proxy - a reverse proxy and static file server that provides authentication using Identity Platform’s built-in identity management system and integrated identity providers (Google, GitHub, and others).

Getting Started¶

To use the library from the requirer side, add the following to the metadata.yaml of the charm:

requires:
  forward-auth:
    interface: forward_auth
    limit: 1

Then, to initialise the library:

from charmlibs.interfaces.forward_auth import AuthConfigChangedEvent, ForwardAuthRequirer

class ApiGatewayCharm(CharmBase):
    def __init__(self, *args):
        # ...
        self.forward_auth = ForwardAuthRequirer(self)
        self.framework.observe(
            self.forward_auth.on.auth_config_changed,
            self.some_event_function
            )

    def some_event_function(self, event: AuthConfigChangedEvent):
        if self.forward_auth.is_ready():
            # Fetch the relation info
            forward_auth_data = self.forward_auth.get_provider_info()
            # update ingress configuration
            # ...

class AuthConfigChangedEvent( handle: Handle, decisions_address: str, app_names: list[str], headers: list[str], relation_id: int, relation_app_name: str, )¶

Bases: EventBase

Event to notify the requirer charm that the forward-auth config has changed.

snapshot() → dict[str, Any]¶: Save event.

restore(snapshot: dict[str, Any]) → None¶: Restore event.

class AuthConfigRemovedEvent(handle: Handle, relation_id: int)¶

Bases: EventBase

Event to notify the requirer charm that the forward-auth config was removed.

snapshot() → dict[str, Any]¶: Save event.

restore(snapshot: dict[str, Any]) → None¶: Restore event.

class ForwardAuthConfig(decisions_address: str, app_names: list[str], headers: list[str] = <factory>)¶

Bases: object

Helper class containing configuration required by API Gateway to set up the proxy.

decisions_address: str¶

app_names: list[str]¶

headers: list[str]¶

classmethod from_dict( dic: dict[str, Any], ) → ForwardAuthConfig¶: Generate ForwardAuthConfig instance from dict.

to_dict() → dict[str, Any]¶: Convert object to dict.

exception ForwardAuthConfigError¶

Bases: Exception

Emitted when invalid forward auth config is provided.

class ForwardAuthProvider( charm: CharmBase, relation_name: str = 'forward-auth', forward_auth_config: ForwardAuthConfig | None = None, )¶

Bases: ForwardAuthRelation

Provider side of the forward-auth relation.

on¶: Event descriptor for events raised by ForwardAuthProvider.

update_forward_auth_config( forward_auth_config: ForwardAuthConfig | None, relation_id: int | None = None, ) → None¶: Update the forward-auth config stored in the object.

class ForwardAuthProxySet(handle: Handle)¶

Bases: EventBase

Event to notify the charm that the proxy was set successfully.

snapshot() → dict[str, Any]¶: Save event.

restore(snapshot: dict[str, Any]) → None¶: Restore event.

class ForwardAuthRelationRemovedEvent(handle: Handle, relation_id: int)¶

Bases: EventBase

Event to notify the charm that the relation was removed.

snapshot() → dict[str, Any]¶: Save event.

restore( snapshot: dict[str, Any], ) → None¶: Restore event.

class ForwardAuthRequirer( charm: CharmBase, *, relation_name: str = 'forward-auth', ingress_app_names: ForwardAuthRequirerConfig | None = None, )¶

Bases: ForwardAuthRelation

Requirer side of the forward-auth relation.

on¶: Event descriptor for events raised by ForwardAuthRequirer.

update_requirer_relation_data( ingress_app_names: ForwardAuthRequirerConfig | None, relation_id: int | None = None, ) → None¶: Update the relation databag with app names that can get IAP protection.

get_provider_info( relation_id: int | None = None, ) → ForwardAuthConfig | None¶: Get the provider information from the databag.

get_remote_app_name( relation_id: int | None = None, ) → str | None¶: Get the remote app name.

is_ready(relation_id: int | None = None) → bool | None¶

Checks whether ForwardAuth is ready on this relation.

Returns True when OAuth2 Proxy shared the config; False otherwise.

is_protected_app(app: str | None) → bool¶: Checks whether a given app requested to be protected by IAP.

class ForwardAuthRequirerConfig(ingress_app_names: list[str] = <factory>)¶

Bases: object

Helper class containing configuration required by OAuth2 Proxy.

Its purpose is to evaluate whether apps can be protected by IAP.

ingress_app_names: list[str]¶

__post_init__() → None¶

to_dict() → dict[str, Any]¶

class InvalidForwardAuthConfigEvent(handle: Handle, error: str)¶

Bases: EventBase

Event to notify the charm that the forward-auth configuration is invalid.

snapshot() → dict[str, Any]¶: Save event.

restore(snapshot: dict[str, Any]) → None¶: Restore event.