Add SAML integration (#19)

.woke.yaml

@@ -0,0 +1,8 @@
+ignore_files:
+  - lib/charms/nginx_ingress_integrator/v0/nginx_route.py
+  - pyproject.toml
+  - src/grafana_dashboards/synapse.json
+  - tests/unit/test_synapse_workload.py
+rules:
+  # Ignore "grandfathered" used by SAML configuration.
+  - name: grandfathered

.wokeignore

@@ -1,3 +1,4 @@
 lib/charms/nginx_ingress_integrator/v0/nginx_route.py
 pyproject.toml
 src/grafana_dashboards/synapse.json
+tests/unit/test_synapse_workload.py

config.yaml

@@ -13,3 +13,9 @@ options:
       Configures whether to report statistics.
     default: false
     type: boolean
+  public_baseurl:
+    type: string
+    description: |
+      The public-facing base URL that clients use to access this Homeserver.
+      Defaults to https://<server_name>/. Only used if there is integration with
+      SAML integrator charm.

lib/charms/grafana_k8s/v0/grafana_dashboard.py

@@ -219,7 +219,7 @@ def __init__(self, *args):
 # Increment this PATCH version before using `charmcraft publish-lib` or reset
 # to 0 if you are raising the major API version
 
-LIBPATCH = 34
+LIBPATCH = 33
 
 logger = logging.getLogger(__name__)
 

lib/charms/prometheus_k8s/v0/prometheus_scrape.py

@@ -369,9 +369,7 @@ def _on_scrape_targets_changed(self, event):
 
 # Increment this PATCH version before using `charmcraft publish-lib` or reset
 # to 0 if you are raising the major API version
-LIBPATCH = 40
-
-PYDEPS = ["cosl"]
+LIBPATCH = 39
 
 logger = logging.getLogger(__name__)
 

lib/charms/saml_integrator/v0/saml.py

@@ -0,0 +1,303 @@
+#!/usr/bin/env python3
+
+# Copyright 2023 Canonical Ltd.
+# Licensed under the Apache2.0. See LICENSE file in charm source for details.
+
+"""Library to manage the relation data for the SAML Integrator charm.
+
+This library contains the Requires and Provides classes for handling the relation
+between an application and a charm providing the `saml`relation.
+It also contains a `SamlRelationData` class to wrap the SAML data that will
+be shared via the relation.
+
+### Requirer Charm
+
+```python
+
+from charms.saml_integrator.v0 import SamlDataAvailableEvent, SamlRequires
+
+class SamlRequirerCharm(ops.CharmBase):
+    def __init__(self, *args):
+        super().__init__(*args)
+        self.saml = saml.SamlRequires(self)
+        self.framework.observe(self.saml.on.saml_data_available, self._handler)
+        ...
+
+    def _handler(self, events: SamlDataAvailableEvent) -> None:
+        ...
+
+```
+
+As shown above, the library provides a custom event to handle the sceneario in
+which new SAML data has been added or updated.
+
+### Provider Charm
+
+Following the previous example, this is an example of the provider charm.
+
+```python
+from charms.saml_integrator.v0 import SamlDataAvailableEvent, SamlRequires
+
+class SamlRequirerCharm(ops.CharmBase):
+    def __init__(self, *args):
+        super().__init__(*args)
+        self.saml = SamlRequires(self)
+        self.framework.observe(self.saml.on.saml_data_available, self._on_saml_data_available)
+        ...
+
+    def _on_saml_data_available(self, events: SamlDataAvailableEvent) -> None:
+        ...
+
+    def __init__(self, *args):
+        super().__init__(*args)
+        self.saml = SamlProvides(self)
+
+```
+The SamlProvides object wraps the list of relations into a `relations` property
+and provides an `update_relation_data` method to update the relation data by passing
+a `SamlRelationData` data object.
+"""
+
+# The unique Charmhub library identifier, never change it
+LIBID = "511cdfa7de3d43568bf9b512f9c9f89d"
+
+# Increment this major API version when introducing breaking changes
+LIBAPI = 0
+
+# Increment this PATCH version before using `charmcraft publish-lib` or reset
+# to 0 if you are raising the major API version
+LIBPATCH = 3
+
+# pylint: disable=wrong-import-position
+import re
+from typing import Optional
+
+import ops
+from pydantic import AnyHttpUrl, BaseModel, Field
+from pydantic.tools import parse_obj_as
+
+DEFAULT_RELATION_NAME = "saml"
+
+
+class SamlEndpoint(BaseModel):
+    """Represent a SAML endpoint.
+
+    Attrs:
+        name: Endpoint name.
+        url: Endpoint URL.
+        binding: Endpoint binding.
+        response_url: URL to address the response to.
+    """
+
+    name: str = Field(..., min_length=1)
+    url: AnyHttpUrl
+    binding: str = Field(..., min_length=1)
+    response_url: Optional[AnyHttpUrl]
+
+    def to_relation_data(self) -> dict[str, str]:
+        """Convert an instance of SamlEndpoint to the relation representation.
+
+        Returns:
+            Dict containing the representation.
+        """
+        result: dict[str, str] = {}
+        # Get the HTTP method from the SAML binding
+        http_method = self.binding.split(":")[-1].split("-")[-1].lower()
+        # Transform name into snakecase
+        lowercase_name = re.sub(r"(?<!^)(?=[A-Z])", "_", self.name).lower()
+        prefix = f"{lowercase_name}_{http_method}_"
+        result[f"{prefix}url"] = str(self.url)
+        result[f"{prefix}binding"] = self.binding
+        if self.response_url:
+            result[f"{prefix}response_url"] = str(self.response_url)
+        return result
+
+    @classmethod
+    def from_relation_data(cls, relation_data: dict[str, str]) -> "SamlEndpoint":
+        """Initialize a new instance of the SamlEndpoint class from the relation data.
+
+        Args:
+            relation_data: the relation data.
+
+        Returns:
+            A SamlEndpoint instance.
+        """
+        url_key = ""
+        for key in relation_data:
+            # A key per method and entpoint type that is always present
+            if key.endswith("_redirect_url") or key.endswith("_post_url"):
+                url_key = key
+        # Get endpoint name from the relation data key
+        lowercase_name = "_".join(url_key.split("_")[:-2])
+        name = "".join(x.capitalize() for x in lowercase_name.split("_"))
+        # Get HTTP method from the relation data key
+        http_method = url_key.split("_")[-2]
+        prefix = f"{lowercase_name}_{http_method}_"
+        return cls(
+            name=name,
+            url=parse_obj_as(AnyHttpUrl, relation_data[f"{prefix}url"]),
+            binding=relation_data[f"{prefix}binding"],
+            response_url=parse_obj_as(AnyHttpUrl, relation_data[f"{prefix}response_url"])
+            if f"{prefix}response_url" in relation_data
+            else None,
+        )
+
+
+class SamlRelationData(BaseModel):
+    """Represent the relation data.
+
+    Attrs:
+        entity_id: SAML entity ID.
+        metadata_url: URL to the metadata.
+        certificates: List of SAML certificates.
+        endpoints: List of SAML endpoints.
+    """
+
+    entity_id: str = Field(..., min_length=1)
+    metadata_url: AnyHttpUrl
+    certificates: list[str]
+    endpoints: list[SamlEndpoint]
+
+    def to_relation_data(self) -> dict[str, str]:
+        """Convert an instance of SamlDataAvailableEvent to the relation representation.
+
+        Returns:
+            Dict containing the representation.
+        """
+        result = {
+            "entity_id": self.entity_id,
+            "metadata_url": str(self.metadata_url),
+            "x509certs": ",".join(self.certificates),
+        }
+        for endpoint in self.endpoints:
+            result.update(endpoint.to_relation_data())
+        return result
+
+
+class SamlDataAvailableEvent(ops.RelationEvent):
+    """Saml event emitted when relation data has changed.
+
+    Attrs:
+        entity_id: SAML entity ID.
+        metadata_url: URL to the metadata.
+        certificates: Tuple containing the SAML certificates.
+        endpoints: Tuple containing the SAML endpoints.
+    """
+
+    @property
+    def entity_id(self) -> str:
+        """Fetch the SAML entity ID from the relation."""
+        assert self.relation.app
+        return self.relation.data[self.relation.app].get("entity_id")
+
+    @property
+    def metadata_url(self) -> str:
+        """Fetch the SAML metadata URL from the relation."""
+        assert self.relation.app
+        return parse_obj_as(AnyHttpUrl, self.relation.data[self.relation.app].get("metadata_url"))
+
+    @property
+    def certificates(self) -> tuple[str, ...]:
+        """Fetch the SAML certificates from the relation."""
+        assert self.relation.app
+        return tuple(self.relation.data[self.relation.app].get("x509certs").split(","))
+
+    @property
+    def endpoints(self) -> tuple[SamlEndpoint, ...]:
+        """Fetch the SAML endpoints from the relation."""
+        assert self.relation.app
+        relation_data = self.relation.data[self.relation.app]
+        endpoints = [
+            SamlEndpoint.from_relation_data(
+                {
+                    key2: relation_data.get(key2)
+                    for key2 in relation_data
+                    if key2.startswith("_".join(key.split("_")[:-1]))
+                }
+            )
+            for key in relation_data
+            if key.endswith("_redirect_url") or key.endswith("_post_url")
+        ]
+        endpoints.sort(key=lambda ep: ep.name)
+        return tuple(endpoints)
+
+
+class SamlRequiresEvents(ops.CharmEvents):
+    """SAML events.
+
+    This class defines the events that a SAML requirer can emit.
+
+    Attrs:
+        saml_data_available: the SamlDataAvailableEvent.
+    """
+
+    saml_data_available = ops.EventSource(SamlDataAvailableEvent)
+
+
+class SamlRequires(ops.Object):
+    """Requirer side of the SAML relation.
+
+    Attrs:
+        on: events the provider can emit.
+    """
+
+    on = SamlRequiresEvents()
+
+    def __init__(self, charm: ops.CharmBase, relation_name: str = DEFAULT_RELATION_NAME) -> None:
+        """Construct.
+
+        Args:
+            charm: the provider charm.
+            relation_name: the relation name.
+        """
+        super().__init__(charm, relation_name)
+        self.charm = charm
+        self.relation_name = relation_name
+        self.framework.observe(charm.on[relation_name].relation_changed, self._on_relation_changed)
+
+    def _on_relation_changed(self, event: ops.RelationChangedEvent) -> None:
+        """Event emitted when the relation has changed.
+
+        Args:
+            event: event triggering this handler.
+        """
+        assert event.relation.app
+        if event.relation.data[event.relation.app]:
+            self.on.saml_data_available.emit(event.relation, app=event.app, unit=event.unit)
+
+
+class SamlProvides(ops.Object):
+    """Provider side of the SAML relation.
+
+    Attrs:
+        relations: list of charm relations.
+    """
+
+    def __init__(self, charm: ops.CharmBase, relation_name: str = DEFAULT_RELATION_NAME) -> None:
+        """Construct.
+
+        Args:
+            charm: the provider charm.
+            relation_name: the relation name.
+        """
+        super().__init__(charm, relation_name)
+        self.charm = charm
+        self.relation_name = relation_name
+
+    @property
+    def relations(self) -> list[ops.Relation]:
+        """The list of Relation instances associated with this relation_name.
+
+        Returns:
+            List of relations to this charm.
+        """
+        return list(self.model.relations[self.relation_name])
+
+    def update_relation_data(self, relation: ops.Relation, saml_data: SamlRelationData) -> None:
+        """Update the relation data.
+
+        Args:
+            relation: the relation for which to update the data.
+            saml_data: a SamlRelationData instance wrapping the data to be updated.
+        """
+        relation.data[self.charm.model.app].update(saml_data.to_relation_data())

metadata.yaml

@@ -22,11 +22,16 @@ containers:
     mounts:
       - storage: data
         location: /data
+  synapse-nginx:
+    resource: synapse-nginx-image
 
 resources:
   synapse-image:
     type: oci-image
     description: OCI image for Synapse
+  synapse-nginx-image:
+    type: oci-image
+    description: OCI image for Synapse NGINX
 
 storage:
   data:
@@ -42,7 +47,7 @@ provides:
 requires:
     ingress:
         interface: ingress
-        limit: 1
+        limit: 2
         optional: true
     database:
         interface: postgresql_client
@@ -52,3 +57,7 @@ requires:
         interface: nginx-route
         limit: 1
         optional: true
+    saml:
+        interface: saml
+        limit: 1
+        optional: true