Add HeaderAuth authentication mechanism

It uses an arbitrary HTTP header for authentication, where the user can
specify both its name and value.

Synopsis::

    from grafana_client import GrafanaApi, HeaderAuth

    grafana = GrafanaApi.from_url(
        url="https://daq.example.org/grafana/",
        credential=HeaderAuth(name="X-WEBAUTH-USER", value="foobar"),
    )

Author: amotl

CHANGELOG.md

@@ -5,6 +5,8 @@
 * Update the `update_folder` method of the folder API to allow changing
   the UID of the folder. Thanks, @iNoahNothing.
 * Add `update_datasource_by_uid` to the datasource API. Thanks, @mgreen-sm.
+* Add `HeaderAuth` authentication mechanism, using an arbitrary HTTP header for
+  authentication, where the user can specify both its name and value. Thanks, @l0tzi.
 
 
 ## 3.0.0 (2022-07-02)

README.md

@@ -84,22 +84,31 @@ exercises could be useful for others, don't hesitate to share them back.
 
 ## Authentication
 
-There are two ways to authenticate to the Grafana API. Either use an API token,
-or HTTP basic auth.
+There are several ways to authenticate to the Grafana HTTP API.
 
-To use the admin API, you need to use HTTP Basic Authentication, as stated at
-the [Grafana Admin API documentation].
+1. Anonymous access
+2. Grafana API token
+3. HTTP Basic Authentication
+4. HTTP Header Authentication
+
+The [Grafana Admin API] is a subset of the Grafana API. For accessing those API
+resources, you will need to use HTTP Basic Authentication.
 
 ```python
-from grafana_client import GrafanaApi
+from grafana_client import GrafanaApi, HeaderAuth, TokenAuth
+
+# 1. Anonymous access
+grafana = GrafanaApi.from_url(
+    url="https://daq.example.org/grafana/",
+)
 
-# Use Grafana API token.
+# 2. Use Grafana API token.
 grafana = GrafanaApi.from_url(
     url="https://daq.example.org/grafana/",
-    credential="eyJrIjoiWHg...dGJpZCI6MX0=",
+    credential=TokenAuth(token="eyJrIjoiWHg...dGJpZCI6MX0="),
 )
 
-# Use HTTP basic authentication.
+# 3. Use HTTP basic authentication.
 grafana = GrafanaApi.from_url(
     url="https://username:[email protected]/grafana/",
 )
@@ -108,6 +117,12 @@ grafana = GrafanaApi.from_url(
     credential=("username", "password")
 )
 
+# 4. Use HTTP Header authentication.
+grafana = GrafanaApi.from_url(
+    url="https://daq.example.org/grafana/",
+    credential=HeaderAuth(name="X-WEBAUTH-USER", value="foobar"),
+)
+
 # Optionally turn off TLS certificate verification.
 grafana = GrafanaApi.from_url(
     url="https://username:[email protected]/grafana/?verify=false",
@@ -117,6 +132,10 @@ grafana = GrafanaApi.from_url(
 grafana = GrafanaApi.from_env()
 ```
 
+Please note that, on top of the specific examples above, the object obtained by
+`credential` can be an arbitrary `requests.auth.AuthBase` instance.
+
+
 ## Proxy
 
 The underlying `requests` library honors the `HTTP_PROXY` and `HTTPS_PROXY`
@@ -265,6 +284,6 @@ poe test
 [examples folder]: https://github.com/panodata/grafana-client/tree/main/examples
 [future maintenance of `grafana_api`]: https://github.com/m0nhawk/grafana_api/issues/88
 [grafana_api]: https://github.com/m0nhawk/grafana_api
-[Grafana Admin API documentation]: https://grafana.com/docs/grafana/latest/http_api/admin/
+[Grafana Admin API]: https://grafana.com/docs/grafana/latest/http_api/admin/
 [Grafana HTTP API reference]: https://grafana.com/docs/grafana/latest/http_api/
 [LICENSE]: https://github.com/panodata/grafana-client/blob/main/LICENSE

grafana_client/__init__.py

@@ -7,6 +7,7 @@
 
 warnings.filterwarnings("ignore", category=Warning, message="distutils Version classes are deprecated")
 from .api import GrafanaApi  # noqa:F401
+from .client import HeaderAuth, TokenAuth  # noqa:F401
 
 __appname__ = "grafana-client"
 

grafana_client/api.py

@@ -6,6 +6,7 @@
 from urllib.parse import parse_qs, urlparse
 
 import requests
+import requests.auth
 from urllib3.exceptions import InsecureRequestWarning
 
 from .client import GrafanaClient
@@ -88,7 +89,7 @@ def version(self):
         return version
 
     @classmethod
-    def from_url(cls, url: str = None, credential: Union[str, Tuple[str, str]] = None):
+    def from_url(cls, url: str = None, credential: Union[str, Tuple[str, str], requests.auth.AuthBase] = None):
         """
         Factory method to create a `GrafanaApi` instance from a URL.
 
@@ -100,7 +101,7 @@ def from_url(cls, url: str = None, credential: Union[str, Tuple[str, str]] = Non
         if url is None:
             url = "http://admin:admin@localhost:3000"
 
-        if credential is not None and not isinstance(credential, (str, Tuple)):
+        if credential is not None and not isinstance(credential, (str, Tuple, requests.auth.AuthBase)):
             raise TypeError(f"Argument 'credential' has wrong type: {type(credential)}")
 
         original_url = url

grafana_client/client.py

@@ -54,6 +54,16 @@ def __call__(self, request):
         return request
 
 
+class HeaderAuth(requests.auth.AuthBase):
+    def __init__(self, name, value):
+        self.name = name
+        self.value = value
+
+    def __call__(self, request):
+        request.headers.update({self.name: self.value})
+        return request
+
+
 class GrafanaClient:
     def __init__(
         self,
@@ -98,10 +108,12 @@ def construct_api_url():
         self.s = requests.Session()
         self.s.headers["User-Agent"] = self.user_agent
         if self.auth is not None:
-            if not isinstance(self.auth, tuple):
-                self.auth = TokenAuth(self.auth)
-            else:
+            if isinstance(self.auth, requests.auth.AuthBase):
+                pass
+            elif isinstance(self.auth, tuple):
                 self.auth = requests.auth.HTTPBasicAuth(*self.auth)
+            else:
+                self.auth = TokenAuth(self.auth)
 
     def __getattr__(self, item):
         def __request_runner(url, json=None, data=None, headers=None):

test/test_grafana_api.py

@@ -4,8 +4,7 @@
 
 import requests
 
-from grafana_client import GrafanaApi
-from grafana_client.client import TokenAuth
+from grafana_client import GrafanaApi, HeaderAuth, TokenAuth
 
 
 class TestGrafanaApiFactories(unittest.TestCase):
@@ -41,6 +40,12 @@ def test_from_url_tokenauth(self):
         self.assertIsInstance(grafana.client.auth, TokenAuth)
         self.assertEqual(grafana.client.auth.token, "VerySecretToken")
 
+    def test_from_url_headerauth(self):
+        grafana = GrafanaApi.from_url(credential=HeaderAuth(name="X-WEBAUTH-USER", value="foobar"))
+        self.assertIsInstance(grafana.client.auth, HeaderAuth)
+        self.assertEqual(grafana.client.auth.name, "X-WEBAUTH-USER")
+        self.assertEqual(grafana.client.auth.value, "foobar")
+
     def test_from_url_auth_precedence(self):
         grafana = GrafanaApi.from_url("http://foo:bar@localhost:3000", credential="VerySecretToken")
         self.assertIsInstance(grafana.client.auth, TokenAuth)

test/test_grafana_client.py

@@ -9,7 +9,7 @@
 import requests
 
 from grafana_client.api import GrafanaApi
-from grafana_client.client import GrafanaClientError, TokenAuth
+from grafana_client.client import GrafanaClientError, HeaderAuth, TokenAuth
 
 
 class MockResponse:
@@ -118,6 +118,12 @@ def test_tokenauth(self):
         tokenauth(request)
         self.assertEqual(request.headers["Authorization"], "Bearer VerySecretToken")
 
+    def test_headerauth(self):
+        headerauth = HeaderAuth(name="X-WEBAUTH-USER", value="foobar")
+        request = requests.Request()
+        headerauth(request)
+        self.assertEqual(request.headers["X-WEBAUTH-USER"], "foobar")
+
     @patch("grafana_client.client.GrafanaClient.__getattr__")
     def test_grafana_client_connect_success(self, mock_get):
         payload = {"commit": "14e988bd22", "database": "ok", "version": "9.0.1"}