Adding client credentials

Author: OleJoik

README.md

@@ -1,25 +1,69 @@
 # oidc-auth-client
 
+[![Build and Publish](https://github.com/norwegian-geotechnical-institute/oidc-auth-client/actions/workflows/release.yaml/badge.svg)](https://github.com/norwegian-geotechnical-institute/oidc-auth-client/actions/workflows/release.yaml)
+
 ## Installing
 
 `pip install oidc-auth-client`
 
 ## Example usage
 
+### Authorization Code Flow
+
+Use this flow when your application needs to **authenticate a real user**.
+
+It will:
+
+1. Open the user’s browser
+2. Redirect them to your identity provider’s login page
+3. Wait for the user to authenticate
+4. Receive an authorization code
+5. Exchange it for an access token
+
+Best for CLIs, desktop apps, and tools acting **on behalf of a user**.
+
 ```py
 from oidc_auth_client import Config, AuthorizationCode, OidcProvider
 
-access_token = AuthorizationCode(
-    config=Config(
-        client_id="<your-client-id>",
-        oidc_provider=OidcProvider(
-            openid_configuration_url="<auth-provider-url>/.well-known/openid-configuration"
-        ),
-        token_cache=TokenCache(),
+config = Config(
+    client_id="<your-client-id>",
+    oidc_provider=OidcProvider(
+        openid_configuration_url="<auth-provider-url>/.well-known/openid-configuration"
     )
-).get_token()
+)
+
+# Sign in with the identity provider in the opened browser!
+access_token = AuthorizationCode(config=config).get_token()
+```
+
+### Client Credentials Flow
+
+Use this flow when your application needs to authenticate **as itself, without user interaction**.
+The client exchanges its own `client_id` and `client_secret` directly for an access token.
+
+Ideal for:
+
+- Backend services
+- Server-to-server APIs
+- Cron jobs
+- Automated tasks
+
+```py
+import os
+from oidc_auth_client import ClientCredentials, OidcProvider, TokenCache
+from oidc_auth_client.client_credentials import ClientCredentialsConfig
+
+config = ClientCredentialsConfig(
+    client_id=CLIENT_ID,
+    client_secret=CLIENT_SECRET,
+    oidc_provider=OidcProvider(openid_configuration_url=OPENID_CONFIGURATION_URL),
+)
+
+access_token = ClientCredentials(config=config).get_token()
 ```
 
+#### Token caching between runs
+
 To allow the user to cache the token between usages, configure with a `TokenCache`. Will store the token in plaintext on the users system.
 
 ```py
@@ -31,4 +75,4 @@ config = Config(
 )
 ```
 
-see some example usage in the [examples folder](./examples/).
+see some example usage in the [examples folder](https://github.com/norwegian-geotechnical-institute/oidc-auth-client/tree/main/examples).

examples/client_credentials.py

@@ -0,0 +1,21 @@
+import os
+from oidc_auth_client import ClientCredentials, OidcProvider, TokenCache
+from oidc_auth_client.client_credentials import ClientCredentialsConfig
+
+CLIENT_ID = os.getenv("CLIENT_ID")
+CLIENT_SECRET = os.getenv("CLIENT_SECRET")
+OPENID_CONFIGURATION_URL = os.getenv("OPENID_CONFIGURATION_URL")
+
+if not CLIENT_ID or not CLIENT_SECRET or not OPENID_CONFIGURATION_URL:
+    raise Exception(
+        "Required env vars CLIENT_ID, CLIENT_SECRET and OPENID_CONFIGURATION_URL not supplied"
+    )
+
+config = ClientCredentialsConfig(
+    client_id=CLIENT_ID,
+    client_secret=CLIENT_SECRET,
+    oidc_provider=OidcProvider(openid_configuration_url=OPENID_CONFIGURATION_URL),
+    token_cache=TokenCache(),
+)
+
+print(ClientCredentials(config=config).get_token())

src/oidc_auth_client/client_credentials.py

@@ -1,42 +1,38 @@
-from oidc_auth_client.authentication_flow import AuthenticationFlow
-from oidc_auth_client.oidc import OidcProvider
-from oidc_auth_client.token_cache import TokenCache
+from dataclasses import dataclass
+from oidc_auth_client.authentication_flow import AuthenticationFlow, Config
+
+
+@dataclass(frozen=True, kw_only=True)
+class ClientCredentialsConfig(Config):
+    client_secret: str
 
 
 class ClientCredentials(AuthenticationFlow):
     def __init__(
         self,
-        client_id: str,
-        client_secret: str,
-        tokens_url: str,
-        timeout: int = 10,  # Seconds
-        app_name: str = "geohub_auth",
-        loglevel: str = "INFO",
-        oidc_provider: OidcProvider | None = None,
-        token_cache: TokenCache | None = None,
+        config: ClientCredentialsConfig,
     ) -> None:
-        self._client_id = client_id
-        self._client_secret = client_secret
-        self._tokens_url = tokens_url
-        self._timeout = timeout
-
-        super().__init__(app_name, loglevel, oidc_provider, token_cache)
+        self._client_secret = config.client_secret
+        super().__init__(config)
 
     def get_token(self) -> str:
-        token: str | None = self._token_cache.load_cached_token()
-        if token is not None:
-            return token
+        if self._token_cache is not None:
+            token: str | None = self._token_cache.load_cached_token()
+            if token is not None:
+                return token
 
         tokens = self._oidc_provider.tokens(
-            self._tokens_url,
             data={
-                "client_id": self._client_id,
-                "client_secret": self._client_secret,
                 "grant_type": "client_credentials",
+                "client_id": self._config.client_id,
+                "client_secret": self._client_secret,
             },
         )
+
         self._logger.debug("tokens successfully obtained")
 
-        self._token_cache.cache_tokens(tokens)
+        if self._token_cache is not None:
+            self._token_cache.cache_tokens(tokens)
+
         token = tokens["access_token"]
         return token

src/oidc_auth_client/token_cache.py

@@ -114,13 +114,16 @@ def cache_tokens(self, tokens: TokenResponseBody):
         cache_file_path = self._get_cache_file()
         self.logger.debug(f"Caching tokens at file path: {cache_file_path}")
 
-        tokens["expires_at"] = time.time() + tokens["expires_in"]
+        _tokens = {
+            "access_token": tokens["access_token"],
+            "expires_at": time.time() + tokens["expires_in"],
+        }
 
         with open(cache_file_path, "w") as f:
-            json.dump(tokens, f)
+            json.dump(_tokens, f)
 
         self.logger.debug(
-            f"Successfully cached tokens. Expires at {ts(tokens['expires_at'])}"
+            f"Successfully cached tokens. Expires at {ts(_tokens['expires_at'])}"
         )
 
     def load_cached_token(self) -> str | None:

tests/test_client_credentials.py

@@ -0,0 +1,31 @@
+from oidc_auth_client import ClientCredentials
+from oidc_auth_client.client_credentials import ClientCredentialsConfig
+from oidc_auth_client.oidc import TokenResponseBody
+from tests.mocks import MockOIDC
+
+
+def test_client_credentials_happypath():
+    expected_client_id = "EXPECTED_CLIENT_ID"
+    expected_client_secret = "EXPECTED_CLIENT_SECRET"
+    expected_access_token = "MOCK_ACCESS_TOKEN"
+
+    def tokens(data: dict) -> TokenResponseBody:
+        actual_client_id = data["client_id"]
+        actual_client_secret = data["client_secret"]
+
+        assert expected_client_id == actual_client_id
+        assert expected_client_secret == actual_client_secret
+
+        return {"access_token": expected_access_token, "expires_in": 600}
+
+    actual_access_token = ClientCredentials(
+        config=ClientCredentialsConfig(
+            client_id=expected_client_id,
+            client_secret=expected_client_secret,
+            oidc_provider=MockOIDC(tokens=tokens),
+        ),
+    ).get_token()
+
+    assert expected_access_token == actual_access_token
+
+    raise Exception(actual_access_token)