--- title: Charmhub | Deploy Synapse using Charmhub - The Open Operator Collection description: Deploy the latest version of Synapse as a Kubernetes Operator on any cloud. url: https://charmhub.io/synapse/libraries/matrix_auth --- # Synapse [Canonical IS DevOps](https://charmhub.io/publisher/canonical-is-devops "View all packages from Canonical IS DevOps") * [Canonical IS DevOps](https://charmhub.io/publisher/canonical-is-devops "View all packages from Canonical IS DevOps") Platform: stable 426 ``` juju deploy synapse ``` [Learn to deploy on juju >](https://juju.is/docs/juju/manage-applications) [Toggle side navigation](https://charmhub.io/synapse/libraries/matrix_auth#drawer) ## charms.synapse.v1.matrix\_auth * [*Docstrings*Docstrings](https://charmhub.io/synapse/libraries/matrix_auth) [*Code*Source code](https://charmhub.io/synapse/libraries/matrix_auth/source-code) * + Download Fetch library ``` charmcraft fetch-lib charms.synapse.v1.matrix_auth ``` [Download matrix\_auth.py](https://charmhub.io/synapse/libraries/matrix_auth/download) + *Last updated* 14 Feb 2025 + *Revision* Library version 1.6 Library to manage the plugin integrations with the Synapse charm. This library contains the Requires and Provides classes for handling the integration between an application and a charm providing the `matrix_plugin` integration. ###### Summary ###### Provider Handles requests from requirers. * Observes: relation\_changed → Triggers workload reconciliation. relation\_departed → Triggers workload reconciliation. * During reconciliation: If the unit is the leader, update\_relation\_data is called. If registration\_secrets (IRC registration encrypted content) are present, the required files are created, and Synapse configuration is updated. ###### Requirer (IRC Bridge, Bidirectional) Requests data (uses homeserver URL, registration shared secret and encryption key) from the provider and updates its configuration accordingly. * Observes: matrix\_auth\_request\_processed (emitted after valid relation\_changed) → Triggers workload reconciliation. * During reconciliation: Configures IRC using data from get\_remote\_relation\_data. Updates relation data with IRC registration, calling update\_relation\_data. ###### Requirer (Maubot, Unidirectional) Requests data (uses homeserver URL) from the provider but does not send registration data back. Observes: matrix\_auth\_request\_processed (emitted after valid relation\_changed) → Triggers workload reconciliation. ###### Why setting a encryption key? In a CMR (Cross-Model Relation), the provider cannot read a secret created by the requirer. To securely share the IRC appservice configuration, the provider generates an encryption key that both sides use: the requirer encrypts the content, and the provider decrypts it. This key is generated once by the provider and stored as a secret. The same applies to the registration shared secret, as both remain unchanged throughout Synapse's lifecycle. When the relation is removed, if there are no observers for the secret, it is deleted. ###### Requirer Charm ``` from charms.synapse.v0.matrix_auth import MatrixAuthRequires class MatrixAuthRequirerCharm(ops.CharmBase): def __init__(self, *args): super().__init__(*args) self.plugin_auth = MatrixAuthRequires(self) self.framework.observe(self.matrix_auth.on.matrix_auth_request_processed, self._handler) ... def _handler(self, events: MatrixAuthRequestProcessed) -> None: ... ``` As shown above, the library provides a custom event to handle the scenario in which a matrix authentication (homeserver and shared secret) has been added or updated. The MatrixAuthRequires provides an `update_relation_data` method to update the relation data by passing a `MatrixAuthRequirerData` data object, requesting a new authentication. ###### Provider Charm Following the previous example, this is an example of the provider charm. ``` from charms.synapse.v0.matrix_auth import MatrixAuthProvides class MatrixAuthProviderCharm(ops.CharmBase): def __init__(self, *args): super().__init__(*args) self.plugin_auth = MatrixAuthProvides(self) ... ``` The MatrixAuthProvides 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 `MatrixAuthRelationData` data object. ``` class MatrixAuthProviderCharm(ops.CharmBase): ... def _on_config_changed(self, _) -> None: for relation in self.model.relations[self.plugin_auth.relation_name]: self.plugin_auth.update_relation_data(relation, self._get_matrix_auth_data()) ``` --- Index * [def encrypt\_string( key, plaintext )](https://charmhub.io/synapse/libraries/matrix_auth#encrypt_string) * [def decrypt\_string( key, ciphertext )](https://charmhub.io/synapse/libraries/matrix_auth#decrypt_string) * [class MatrixAuthProviderData](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthproviderdata) * + [def set\_shared\_secret\_id( self, model, relation)](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthproviderdata-set_shared_secret_id) * + [def set\_encryption\_key\_secret\_id( self, model, relation)](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthproviderdata-set_encryption_key_secret_id) * + [def get\_shared\_secret( cls, model, shared\_secret\_id)](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthproviderdata-get_shared_secret) * + [def to\_relation\_data( self, model, relation)](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthproviderdata-to_relation_data) * + [def from\_relation( cls, model, relation)](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthproviderdata-from_relation) * [class MatrixAuthRequirerData](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthrequirerdata) * + [def get\_encryption\_key\_secret( cls, model, encryption\_key\_secret\_id)](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthrequirerdata-get_encryption_key_secret) * + [def to\_relation\_data( self, model, relation)](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthrequirerdata-to_relation_data) * + [def from\_relation( cls, model, relation)](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthrequirerdata-from_relation) * [class MatrixAuthRequestProcessed](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthrequestprocessed) * + [def get\_matrix\_auth\_provider\_relation\_data( self)](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthrequestprocessed-get_matrix_auth_provider_relation_data) * [class MatrixAuthRequestReceived](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthrequestreceived) * [class MatrixAuthRequiresEvents](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthrequiresevents) * [class MatrixAuthProvidesEvents](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthprovidesevents) * [class MatrixAuthProvides](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthprovides) * + [def \_\_init\_\_( self, charm, relation\_name)](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthprovides-__init__) * + [def get\_remote\_relation\_data( self)](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthprovides-get_remote_relation_data) * + [def update\_relation\_data( self, relation, matrix\_auth\_provider\_data)](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthprovides-update_relation_data) * [class MatrixAuthRequires](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthrequires) * + [def \_\_init\_\_( self, charm, relation\_name)](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthrequires-__init__) * + [def get\_remote\_relation\_data( self)](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthrequires-get_remote_relation_data) * + [def update\_relation\_data( self, relation, matrix\_auth\_requirer\_data)](https://charmhub.io/synapse/libraries/matrix_auth#matrixauthrequires-update_relation_data) #### def encrypt\_string(     key: bytes,     plaintext: SecretStr ) Encrypt a string using Fernet. Arguments key encryption key in bytes. plaintext text to encrypt. Returns encrypted text. #### def decrypt\_string(     key: bytes,     ciphertext: str ) Decrypt a string using Fernet. Arguments key encryption key in bytes. ciphertext encrypted text. Returns decrypted text. #### class MatrixAuthProviderData Represent the MatrixAuth provider data. Attributes homeserver the homeserver URL. shared\_secret the Matrix shared secret. shared\_secret\_id the shared secret Juju secret ID. encryption\_key\_secret\_id encryption key secret ID. Methods MatrixAuthProviderData. set\_shared\_secret\_id( *self* , model , relation ) Store the Matrix shared secret as a Juju secret. Arguments model the Juju model relation relation to grant access to the secrets to. Description If the secret exists, grant access to the relation. If not found, create one. MatrixAuthProviderData. set\_encryption\_key\_secret\_id( *self* , model , relation ) Store the encryption key to encrypt/decrypt appservice registrations. Arguments model the Juju model relation relation to grant access to the secrets to. MatrixAuthProviderData. get\_shared\_secret( cls , model , shared\_secret\_id ) Retrieve the shared secret corresponding to the shared\_secret\_id. Arguments model the Juju model. shared\_secret\_id the secret ID for the shared secret. Returns the shared secret or None if not found. MatrixAuthProviderData. to\_relation\_data( *self* , model , relation ) Convert an instance of MatrixAuthProviderData to the relation representation. Arguments model the Juju model. relation relation to grant access to the secrets to. Returns Dict containing the representation. MatrixAuthProviderData. from\_relation( cls , model , relation ) Initialize a new instance of the MatrixAuthProviderData class from the relation. Arguments relation the relation. Returns A MatrixAuthProviderData instance. #### class MatrixAuthRequirerData Represent the MatrixAuth requirer data. Attributes registration a generated app registration file. Methods MatrixAuthRequirerData. get\_encryption\_key\_secret( cls , model , encryption\_key\_secret\_id ) Retrieve the encryption key secret corresponding to the encryption\_key\_secret\_id. Arguments model the Juju model. encryption\_key\_secret\_id the secret ID for the encryption key secret. Returns the encryption key secret as bytes or None if not found. MatrixAuthRequirerData. to\_relation\_data( *self* , model , relation ) Convert an instance of MatrixAuthRequirerData to the relation representation. Description Args: model: the Juju model. relation: relation to grant access to the secrets to. Returns: Dict containing the representation. Raises: ValueError if encryption key not found. MatrixAuthRequirerData. from\_relation( cls , model , relation ) Get a MatrixAuthRequirerData from the relation data. Arguments model the Juju model. relation the relation. Returns the relation data and the processed entries for it. #### class MatrixAuthRequestProcessed Description MatrixAuth event emitted when a new request is processed. None Methods MatrixAuthRequestProcessed. get\_matrix\_auth\_provider\_relation\_data( *self* ) Get a MatrixAuthProviderData for the relation data. Returns the MatrixAuthProviderData for the relation data. #### class MatrixAuthRequestReceived Description MatrixAuth event emitted when a new request is made. None #### class MatrixAuthRequiresEvents MatrixAuth requirer events. Attributes matrix\_auth\_request\_processed the MatrixAuthRequestProcessed. Description This class defines the events that a MatrixAuth requirer can emit. #### class MatrixAuthProvidesEvents MatrixAuth provider events. Attributes matrix\_auth\_request\_received the MatrixAuthRequestReceived. Description This class defines the events that a MatrixAuth provider can emit. #### class MatrixAuthProvides Provider side of the MatrixAuth relation. Attributes on events the provider can emit. Methods MatrixAuthProvides. \_\_init\_\_( *self* , charm , relation\_name: str ) Construct. Arguments charm the provider charm. relation\_name the relation name. MatrixAuthProvides. get\_remote\_relation\_data( *self* ) Retrieve the remote relation data. Returns MatrixAuthRequirerData the relation data. MatrixAuthProvides. update\_relation\_data( *self* , relation , matrix\_auth\_provider\_data: MatrixAuthProviderData ) Arguments relation the relation for which to update the data. matrix\_auth\_provider\_data a MatrixAuthProviderData instance wrapping the data to be updated. Description Update the relation data. Since provider values should not be changed while instance exists, this method updates relation data only if invalid or empty. #### class MatrixAuthRequires Requirer side of the MatrixAuth requires relation. Attributes on events the provider can emit. Methods MatrixAuthRequires. \_\_init\_\_( *self* , charm , relation\_name: str ) Construct. Arguments charm the provider charm. relation\_name the relation name. MatrixAuthRequires. get\_remote\_relation\_data( *self* ) Retrieve the remote relation data. Returns MatrixAuthProviderData the relation data. MatrixAuthRequires. update\_relation\_data( *self* , relation , matrix\_auth\_requirer\_data: MatrixAuthRequirerData ) Update the relation data. Arguments relation the relation for which to update the data. matrix\_auth\_requirer\_data MatrixAuthRequirerData wrapping the data to be updated.