auth_proxy¶

Interface library for providing OAuth2 Proxy with downstream charms’ auth-proxy information.

It is required to integrate a charm into an Identity and Access Proxy (IAP).

Getting Started¶

To install, add charmlibs-interfaces-auth-proxy to your Python dependencies. Then in your Python code, import as:

from charmlibs.interfaces import auth_proxy

Note that you also need to add ``jsonschema`` to your charm’s ``requirements.txt``.

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

requires:
  auth-proxy:
    interface: auth_proxy
    limit: 1

Then, to initialise the library:

from charmlibs.interfaces.auth_proxy import AuthProxyConfig, AuthProxyRequirer

AUTH_PROXY_ALLOWED_ENDPOINTS = ["welcome", "about/app"]
AUTH_PROXY_HEADERS = ["X-Auth-Request-User", "X-Auth-Request-Email"]
AUTH_PROXY_AUTHENTICATED_EMAILS = ["test@example.com", "test@canonical.com"]
AUTH_PROXY_AUTHENTICATED_EMAIL_DOMAINS = ["canonical.com"]

class SomeCharm(CharmBase):
    def __init__(self, *args):
        # ...
        self.auth_proxy = AuthProxyRequirer(self, self._auth_proxy_config)

    @property
    def external_urls(self) -> list:
        # Get ingress-per-unit or externally-configured web urls
        # ...
        return ["https://example.com/unit-0", "https://example.com/unit-1"]

    @property
    def _auth_proxy_config(self) -> AuthProxyConfig:
        return AuthProxyConfig(
            protected_urls=self.external_urls,
            allowed_endpoints=AUTH_PROXY_ALLOWED_ENDPOINTS,
            headers=AUTH_PROXY_HEADERS,
            authenticated_emails=AUTH_PROXY_AUTHENTICATED_EMAILS,
            authenticated_email_domains=AUTH_PROXY_AUTHENTICATED_EMAIL_DOMAINS
        )

    def _on_ingress_ready(self, event):
        self._configure_auth_proxy()

    def _configure_auth_proxy(self):
        self.auth_proxy.update_auth_proxy_config(auth_proxy_config=self._auth_proxy_config)

class AuthProxyConfig(protected_urls: list[str], headers: list[str] = <factory>, allowed_endpoints: list[str] = <factory>, authenticated_emails: list[str] = <factory>, authenticated_email_domains: list[str] = <factory>, app_name: str | None = None)¶

Bases: object

Helper class containing a configuration for the charm related with OAuth2 Proxy.

protected_urls: list[str]¶

headers: list[str]¶

allowed_endpoints: list[str]¶

authenticated_emails: list[str]¶

authenticated_email_domains: list[str]¶

app_name: str | None = None¶

validate() → None¶: Validate the auth proxy configuration.

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

class AuthProxyConfigChangedEvent( handle: Handle, protected_urls: list[str], headers: list[str], allowed_endpoints: list[str], authenticated_emails: list[str], authenticated_email_domains: list[str], relation_id: int, relation_app_name: str, )¶

Bases: EventBase

Event to notify the Provider charm that the auth proxy config has changed.

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

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

to_auth_proxy_config() → AuthProxyConfig¶: Convert the event information to an AuthProxyConfig object.

exception AuthProxyConfigError¶

Bases: Exception

Emitted when invalid auth proxy config is provided.

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

Bases: EventBase

Event to notify the provider charm that the auth proxy config was removed.

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

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

class AuthProxyProvider( charm: CharmBase, relation_name: str = 'auth-proxy', )¶

Bases: AuthProxyRelation

Provider side of the auth-proxy relation.

on¶: Event descriptor for events raised by AuthProxyProvider.

get_app_names() → list[str]¶: Returns the list of all related app names.

get_decoded_relations_data() → list[dict[str, Any]]¶: Return decoded app databags for all auth-proxy relations.

get_relations_data(key: str) → list[str] | None¶: Returns a list of key values from all auth-proxy relations or None.

class AuthProxyRelationRemovedEvent(handle: Handle)¶

Bases: EventBase

Custom 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 AuthProxyRequirer( charm: CharmBase, auth_proxy_config: AuthProxyConfig | None = None, relation_name: str = 'auth-proxy', )¶

Bases: AuthProxyRelation

Requirer side of the auth-proxy relation.

on¶: Event descriptor for events raised by AuthProxyRequirer.

update_auth_proxy_config( auth_proxy_config: AuthProxyConfig, relation_id: int | None = None, ) → None¶: Update the auth proxy config stored in the object.

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

Bases: EventBase

Event to notify the charm that the auth proxy configuration is invalid.

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

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