---
title: Charmhub | Deploy Grafana using Charmhub - The Open Operator Collection
description: Deploy the latest version of Grafana as a Kubernetes Operator on any
  cloud.
url: https://charmhub.io/grafana-k8s/libraries/grafana_auth
---

# Grafana

[Canonical Observability](https://charmhub.io/publisher/observability "View all packages from Canonical Observability")

* [Canonical Observability](https://charmhub.io/publisher/observability "View all packages from Canonical Observability")

Platform:

12.4/stable tf-12.4.3-2-g8187475

```
juju deploy grafana-k8s --channel 12.4/stable --trust
```

[Learn to deploy on juju >](https://juju.is/docs/juju/manage-applications)

[Toggle side navigation](https://charmhub.io/grafana-k8s/libraries/grafana_auth#drawer)

## charms.grafana\_k8s.v0.grafana\_auth

* [*Docstrings*Docstrings](https://charmhub.io/grafana-k8s/libraries/grafana_auth)
  [*Code*Source code](https://charmhub.io/grafana-k8s/libraries/grafana_auth/source-code)
* + Download

    Fetch library

    ```
    charmcraft fetch-lib charms.grafana_k8s.v0.grafana_auth
    ```

    [Download grafana\_auth.py](https://charmhub.io/grafana-k8s/libraries/grafana_auth/download)
  + *Last updated* 02 Oct 2025
  + *Revision* Library version 0.5

grafana-auth library.

This library implements the grafana-auth relation interface,
it contains the Requirer and Provider classes for handling
the interface.
With this library charms can to configure authentication to Grafana.
The provider will set the authentication mode that it needs,
and will pass the necessary configuration of that authentication mode.
The requirer will consume the authentication configuration to authenticate to Grafana.

##### Getting Started

From a charm directory, fetch the library using `charmcraft`:

```
charmcraft fetch-lib charms.grafana_k8s.v0.grafana_auth
```

You will also need to add the following library to the charm's `requirements.txt` file:

* jsonschema

###### Provider charm

Example:
An example on how to use the AuthProvider with proxy mode using default configuration options.
The default arguments are:
`charm : CharmBase`
`relation_name: str : grafana-auth`
`header_name: str : X-WEBAUTH-USER`
`header_property: str : username`
`auto_sign_up: bool : True`
`sync_ttl: int : None`
`whitelist: list[str] : None`
`headers: list[str] : None`
`headers_encoded: bool : None`
`enable_login_token: bool : None`

```
from charms.grafana_k8s.v0.grafana_auth import GrafanaAuthProxyProvider
from ops.charm import CharmBase
class ExampleProviderCharm(CharmBase):
    def __init__(self, *args):
        super().__init__(*args)
        ...
        self.grafana_auth_proxy_provider = GrafanaAuthProxyProvider(self)
        self.framework.observe(
            self.grafana_auth_proxy_provider.on.urls_available, self._on_urls_available
        )
        ...
```

Values different than defaults must be set from the class constructor.
The [official documentation](https://grafana.com/docs/grafana/latest/setup-grafana/configure-security/configure-authentication/auth-proxy/)
of Grafana provides further explanation on the values that can be assigned to the different variables.
Example:

```
from charms.grafana_k8s.v0.grafana_auth import GrafanaAuthProxyProvider
from ops.charm import CharmBase
class ExampleProviderCharm(CharmBase):
    def __init__(self, *args):
        super().__init__(*args)
        ...
        self.grafana_auth_proxy_provider = GrafanaAuthProxyProvider(
            self,
            header_property="email",
            auto_sign_up=False,
            whitelist=["localhost","canonical.com"],
        )
        self.framework.observe(
            self.grafana_auth_proxy_provider.on.urls_available, self._on_urls_available
        )
        ...
```

###### Requirer charm

Example:
An example on how to use the auth requirer.

```
from charms.grafana_k8s.v0.grafana_auth import AuthRequirer
from ops.charm import CharmBase
class ExampleRequirerCharm(CharmBase):
    def __init__(self, *args):
        super().__init__(*args)
        self.auth_requirer = AuthRequirer(
            self,
            auth_requirer=["https://example.com/"]
        )
        self.framework.observe(
            self.auth_requirer.on.auth_conf_available, self._on_auth_conf_available
        )
```

---

Index

* [class UrlsAvailableEvent](https://charmhub.io/grafana-k8s/libraries/grafana_auth#urlsavailableevent)
* + [def \_\_init\_\_(
    self,
    handle,
    urls,
    relation\_id)](https://charmhub.io/grafana-k8s/libraries/grafana_auth#urlsavailableevent-__init__)
* + [def snapshot(
    self)](https://charmhub.io/grafana-k8s/libraries/grafana_auth#urlsavailableevent-snapshot)
* + [def restore(
    self,
    snapshot)](https://charmhub.io/grafana-k8s/libraries/grafana_auth#urlsavailableevent-restore)
* [class AuthProviderCharmEvents](https://charmhub.io/grafana-k8s/libraries/grafana_auth#authprovidercharmevents)
* [class AuthProvider](https://charmhub.io/grafana-k8s/libraries/grafana_auth#authprovider)
* + [def \_\_init\_\_(
    self,
    charm,
    relation\_name,
    refresh\_event)](https://charmhub.io/grafana-k8s/libraries/grafana_auth#authprovider-__init__)
* [class AuthConfAvailableEvent](https://charmhub.io/grafana-k8s/libraries/grafana_auth#authconfavailableevent)
* + [def \_\_init\_\_(
    self,
    handle,
    auth,
    relation\_id)](https://charmhub.io/grafana-k8s/libraries/grafana_auth#authconfavailableevent-__init__)
* + [def snapshot(
    self)](https://charmhub.io/grafana-k8s/libraries/grafana_auth#authconfavailableevent-snapshot)
* + [def restore(
    self,
    snapshot)](https://charmhub.io/grafana-k8s/libraries/grafana_auth#authconfavailableevent-restore)
* [class AuthRequirerCharmEvents](https://charmhub.io/grafana-k8s/libraries/grafana_auth#authrequirercharmevents)
* [class AuthRequirer](https://charmhub.io/grafana-k8s/libraries/grafana_auth#authrequirer)
* + [def \_\_init\_\_(
    self,
    charm,
    urls,
    relation\_name,
    refresh\_event)](https://charmhub.io/grafana-k8s/libraries/grafana_auth#authrequirer-__init__)
* [class GrafanaAuthProxyProvider](https://charmhub.io/grafana-k8s/libraries/grafana_auth#grafanaauthproxyprovider)
* + [def \_\_init\_\_(
    self,
    charm,
    relation\_name,
    refresh\_event,
    header\_name,
    header\_property,
    auto\_sign\_up,
    sync\_ttl,
    whitelist,
    headers,
    headers\_encoded,
    enable\_login\_token)](https://charmhub.io/grafana-k8s/libraries/grafana_auth#grafanaauthproxyprovider-__init__)

#### class UrlsAvailableEvent

Description

Charm event triggered when provider charm extracts the urls from relation data. None

Methods

UrlsAvailableEvent.
\_\_init\_\_(

*self*

,
handle

,
urls: list

,
relation\_id: int
)

UrlsAvailableEvent.
snapshot(

*self*
)

Description

Returns snapshot. None

UrlsAvailableEvent.
restore(

*self*

,
snapshot: dict
)

Description

Restores snapshot. None

#### class AuthProviderCharmEvents

Description

List of events that the auth provider charm can leverage. None

#### class AuthProvider

Base class for authentication configuration provider classes.

Description

This class shouldn't be initialized,
Its children classes define the authentication mode and configuration to be used.

Methods

AuthProvider.
\_\_init\_\_(

*self*

,
charm: CharmBase

,
relation\_name: str

,
refresh\_event
)

#### class AuthConfAvailableEvent

Description

Charm Event triggered when authentication config is ready. None

Methods

AuthConfAvailableEvent.
\_\_init\_\_(

*self*

,
handle

,
auth: dict

,
relation\_id: int
)

AuthConfAvailableEvent.
snapshot(

*self*
)

Description

Returns snapshot. None

AuthConfAvailableEvent.
restore(

*self*

,
snapshot: dict
)

Description

Restores snapshot. None

#### class AuthRequirerCharmEvents

Description

List of events that the auth requirer charm can leverage. None

#### class AuthRequirer

Description

Authentication configuration requirer class. None

Methods

AuthRequirer.
\_\_init\_\_(

*self*

,
charm

,
urls

,
relation\_name: str

,
refresh\_event
)

Constructs an authentication requirer that consumes authentication configuration.

Arguments

charm

CharmBase: the charm which manages this object.

urls

List[str]: a list of urls to access the service the charm needs to authenticate to.

relation\_name

str: name of the relation in `metadata.yaml` that has the `grafana_auth` interface.

refresh\_event

an optional bound event which will be observed to re-set authentication configuration.

Description

The charm initializing this class requires authentication configuration,
and it's expected to provide a list of url(s) to the service it's authenticating to.
This class can be initialized as follows:

```
self.auth_requirer = AuthRequirer(
self,
auth_requirer=["https://example.com/"]
)
```

#### class GrafanaAuthProxyProvider

Authentication configuration provider class.

Description

Provides proxy mode for authentication to Grafana.

Methods

GrafanaAuthProxyProvider.
\_\_init\_\_(

*self*

,
charm: CharmBase

,
relation\_name: str

,
refresh\_event

,
header\_name: str

,
header\_property: str

,
auto\_sign\_up: bool

,
sync\_ttl

,
whitelist

,
headers

,
headers\_encoded

,
enable\_login\_token
)

Constructs GrafanaAuthProxyProvider.

Arguments

charm

CharmBase: the charm which manages this object.

relation\_name

str: name of the relation in `metadata.yaml` that has the `grafana_auth` interface.

refresh\_event

an optional bound event which will be observed to re-set urls.

header\_name

str: HTTP Header name that will contain the username or email

header\_property

str: HTTP Header property, defaults to username but can also be `email`.

auto\_sign\_up

bool: Set to `true` to enable auto sign-up of users who do not exist in Grafana DB.

sync\_ttl

int: Define cache time to live in minutes.

whitelist

list[str]: Limits where auth proxy requests come from by configuring a list of IP addresses.

headers

list[str]: Optionally define more headers to sync other user attributes.

headers\_encoded

bool: Non-ASCII strings in header values are encoded using quoted-printable encoding

enable\_login\_token

bool

Returns

None

Description

The charm initializing this object configures the authentication to grafana using proxy authentication mode.
This object can be initialized as follows:

```
self.grafana_auth_proxy_provider = GrafanaAuthProxyProvider(self)
```