Revoke OAuth token on logout; report default status on login

const-cloudinary · claude · const-cloudinary · commit 9827027a5268 · 2026-06-25T13:46:04.000+03:00
logout now revokes the refresh token at the authorization server (RFC 7009)
before removing the saved configuration; the local entry is removed even if
revocation fails. login reports whether the new login became the default and,
when it did not, prints the command to make it the default.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -25,7 +25,7 @@ Python 3.8 or later.  You can install Python from [https://www.python.org/](http
     cld login
     ```
 
-    This opens your browser to authorize the CLI, then saves the login as a configuration (named after the cloud) and sets it as the default. No API secret is stored on disk &mdash; the saved login holds a short-lived token that the CLI refreshes automatically.
+    This opens your browser to authorize the CLI, then saves the login as a configuration (named after the cloud) and sets it as the default. The CLI refreshes the token automatically, and you can remove the login at any time with `cld logout`.
 
     **Option B &mdash; Set your CLOUDINARY\_URL environment variable.** For example:
     * On Mac or Linux:<br>`export CLOUDINARY_URL=cloudinary://123456789012345:abcdefghijklmnopqrstuvwxyzA@cloud_name`
@@ -58,7 +58,7 @@ Usage: cld [cli options] [command] [command options] [method] [method parameters
 ```
 cld --help         # Lists available commands.
 cld login          # Logs in to a Cloudinary account via OAuth in your browser.
-cld logout         # Removes a saved OAuth login.
+cld logout         # Revokes and removes a saved OAuth login.
 cld search --help  # Shows usage for the Search API.
 cld admin          # Lists Admin API methods.
 cld uploader       # Lists Upload API methods.
@@ -255,7 +255,7 @@ Whereas using the saved configuration "accountx":
 cld -C accountx admin usage
 ```
 
-_**Caution:** A saved API-key configuration stores your API secret in a local file. An OAuth login (see below) avoids this by storing a short-lived, auto-refreshed token instead._
+_**Caution:** Creating a saved configuration may put your credentials at risk as they are stored in a local plain text file. This applies to both API-key configurations and OAuth logins._
 
 You can create, delete and list saved configurations using the `config` command.
 
@@ -272,11 +272,13 @@ Instead of saving an API key and secret, you can log in to a Cloudinary account
 ```
 cld login                  # Log in and save the configuration (named after the cloud).
 cld login my-account       # Save the login under a specific name.
-cld logout                 # Choose a saved OAuth login to remove.
-cld logout my-account      # Remove a specific saved OAuth login.
+cld logout                 # Choose a saved OAuth login to log out of.
+cld logout my-account      # Log out of a specific saved OAuth login.
 ```
 
-Once saved, an OAuth login is selected with `-C <name>` just like any other saved configuration.
+The first login becomes the default automatically. When other configurations already exist, the new login is saved but not made the default; `cld login` tells you so and prints the command to make it the default. Once saved, an OAuth login is selected with `-C <name>` just like any other saved configuration.
+
+`cld logout` revokes the login's token at the server and removes the saved configuration. If the token cannot be revoked (for example, you are offline), the saved configuration is still removed.
 
 ### Choosing a default configuration
 
diff --git a/cloudinary_cli/auth/__init__.py b/cloudinary_cli/auth/__init__.py
@@ -37,7 +37,8 @@ def login(region=None, name=None, set_default=False):
     """
     Run the interactive browser login and persist the resulting session as a named config entry.
 
-    Returns the saved config name, or None on failure.
+    Returns (config_name, is_default), where is_default is True when this login was made the default
+    configuration (explicitly with set_default, or automatically as the sole login).
     """
     if name and is_reserved_config_name(name):
         raise RuntimeError(f"'{name}' is a reserved configuration name.")
@@ -48,9 +49,10 @@ def login(region=None, name=None, set_default=False):
     config_name = name or _derive_config_name(session.cloud_name, region)
     update_config({config_name: to_cloudinary_url(session)})
 
-    if set_default or _should_auto_default(config_name):
+    is_default = bool(set_default or _should_auto_default(config_name))
+    if is_default:
         set_default_config(config_name)
-    return config_name
+    return config_name, is_default
 
 
 def _should_auto_default(name):
@@ -71,14 +73,37 @@ def _should_auto_default(name):
 
 
 def logout(name):
-    """Remove a saved OAuth login by name. Returns "removed", "not_found", or "not_oauth"."""
+    """
+    Log out of a saved OAuth login by name: revoke its refresh token at the authorization server,
+    then remove the saved configuration. The local entry is always removed even if revocation fails
+    (offline, server error), so logout never leaves a stale entry behind.
+
+    Returns "removed" (revoked and removed), "revoke_failed" (removed locally but the token could not
+    be revoked), "not_found", or "not_oauth".
+    """
     saved = load_config()
     if name not in saved:
         return "not_found"
     if not is_oauth_url(saved[name]):
         return "not_oauth"
+
+    revoked = _revoke_login(name, saved[name])
     remove_config_keys(name)
-    return "removed"
+    return "removed" if revoked else "revoke_failed"
+
+
+def _revoke_login(name, url):
+    """Best-effort revocation of a saved login's refresh token. Returns True on success (or when
+    there is nothing to revoke), False if the revoke request failed."""
+    session = from_cloudinary_url(url)
+    if not session.refresh_token:
+        return True
+    try:
+        flow.revoke(session.refresh_token, session.region)
+        return True
+    except requests.RequestException as e:
+        log_exception(e, debug_message=f"Could not revoke the OAuth token for '{name}'")
+        return False
 
 
 def refresh_url_if_stale(name, url, force=False):
diff --git a/cloudinary_cli/auth/flow.py b/cloudinary_cli/auth/flow.py
@@ -10,6 +10,7 @@
 from cloudinary_cli.defaults import (
     oauth_authorize_url_for_region,
     oauth_token_url_for_region,
+    oauth_revoke_url_for_region,
     OAUTH_CLIENT_ID,
     OAUTH_SCOPES,
     OAUTH_HTTP_TIMEOUT_SECONDS,
@@ -58,3 +59,14 @@ def refresh(refresh_token, region):
     }, timeout=OAUTH_HTTP_TIMEOUT_SECONDS)
     resp.raise_for_status()
     return resp.json()
+
+
+def revoke(token, region, token_type_hint="refresh_token"):
+    """Revoke a token at the authorization server (RFC 7009). Revoking the refresh token ends the
+    offline-access grant so it can no longer mint new access tokens."""
+    resp = requests.post(oauth_revoke_url_for_region(region), data={
+        "token": token,
+        "token_type_hint": token_type_hint,
+        "client_id": OAUTH_CLIENT_ID,
+    }, timeout=OAUTH_HTTP_TIMEOUT_SECONDS)
+    resp.raise_for_status()
diff --git a/cloudinary_cli/core/auth.py b/cloudinary_cli/core/auth.py
@@ -16,17 +16,22 @@
              "config is given.")
 def login(name, region, set_default):
     try:
-        config_name = run_login(region=region, name=name, set_default=set_default)
+        config_name, is_default = run_login(region=region, name=name, set_default=set_default)
     except Exception as e:
         log_exception(e, "Login failed")
         return False
 
     logger.info(f"Logged in. Saved as '{config_name}'.")
-    logger.info(f"Example usage: cld -C {config_name} <command>")
+    if is_default:
+        logger.info(f"This is now the default configuration. Run `cld <command>` to use it, "
+                    f"or `cld -C {config_name} <command>` to select it explicitly.")
+    else:
+        logger.info(f"Run `cld -C {config_name} <command>` to use it, "
+                    f"or make it the default with `cld config -d {config_name}`.")
     return True
 
 
-@command("logout", help="Log out by removing a saved OAuth configuration. "
+@command("logout", help="Log out: revoke a saved OAuth login's token and remove its configuration. "
                         "Run without a name to choose from the saved logins.")
 @argument("name", required=False)
 def logout(name):
@@ -39,7 +44,10 @@ def logout(name):
 
     status = run_logout(name)
     if status == "removed":
-        logger.info(f"Logged out of '{name}'.")
+        logger.info(f"Logged out of '{name}'. Its token was revoked and the saved login removed.")
+    elif status == "revoke_failed":
+        logger.warning(f"Removed '{name}', but could not revoke its token at the server "
+                       f"(it may still be valid until it expires).")
     elif status == "not_oauth":
         logger.error(f"'{name}' is not an OAuth login; refusing to remove it. "
                      f"Use `config -rm {name}` to delete a saved configuration.")
diff --git a/cloudinary_cli/defaults.py b/cloudinary_cli/defaults.py
@@ -61,6 +61,10 @@ def oauth_token_url_for_region(region):
     return f'{oauth_base_url_for_region(region)}/oauth2/token'
 
 
+def oauth_revoke_url_for_region(region):
+    return f'{oauth_base_url_for_region(region)}/oauth2/revoke'
+
+
 CLOUDINARY_REGION = normalize_region(os.environ.get('CLOUDINARY_REGION'))
 
 # Public PKCE client (no secret). Overridable for testing against a non-prod authorization server
diff --git a/test/test_auth_flow.py b/test/test_auth_flow.py
@@ -55,3 +55,15 @@ def test_refresh_posts_refresh_token(self):
         self.assertEqual("refresh_token", data["grant_type"])
         self.assertEqual("rt_abc", data["refresh_token"])
         self.assertIn("timeout", post.call_args.kwargs)
+
+    def test_revoke_posts_token_to_revoke_endpoint(self):
+        resp = MagicMock()
+        with patch("cloudinary_cli.auth.flow.requests.post", return_value=resp) as post:
+            flow.revoke("rt_abc", "api-eu")
+        self.assertEqual("https://oauth.cloudinary.com/oauth2/revoke", post.call_args.args[0])
+        data = post.call_args.kwargs["data"]
+        self.assertEqual("rt_abc", data["token"])
+        self.assertEqual("refresh_token", data["token_type_hint"])
+        self.assertIn("client_id", data)
+        self.assertIn("timeout", post.call_args.kwargs)
+        resp.raise_for_status.assert_called_once()
diff --git a/test/test_cli_config_oauth.py b/test/test_cli_config_oauth.py
@@ -42,9 +42,21 @@ def test_removes_oauth_login(self):
         from cloudinary_cli.auth import logout
         saved = {"eu-cloud": _oauth_url()}
         with patch("cloudinary_cli.auth.load_config", return_value=saved), \
-                patch("cloudinary_cli.auth.remove_config_keys") as remove:
+                patch("cloudinary_cli.auth.remove_config_keys") as remove, \
+                patch("cloudinary_cli.auth.flow.revoke") as revoke:
             self.assertEqual("removed", logout("eu-cloud"))
             remove.assert_called_once_with("eu-cloud")
+            revoke.assert_called_once_with("rt_secret_value", "api-eu")
+
+    def test_revoke_failure_still_removes_locally(self):
+        import requests
+        from cloudinary_cli.auth import logout
+        saved = {"eu-cloud": _oauth_url()}
+        with patch("cloudinary_cli.auth.load_config", return_value=saved), \
+                patch("cloudinary_cli.auth.remove_config_keys") as remove, \
+                patch("cloudinary_cli.auth.flow.revoke", side_effect=requests.ConnectionError()):
+            self.assertEqual("revoke_failed", logout("eu-cloud"))
+            remove.assert_called_once_with("eu-cloud")  # local entry removed despite revoke failure
 
     def test_refuses_non_oauth_config(self):
         from cloudinary_cli.auth import logout
@@ -71,7 +83,8 @@ def test_lists_only_oauth_and_removes_selected(self):
         saved = {"mykey": "cloudinary://key:secret@cloud",
                  "cloud-a": _oauth_url("cloud-a"), "cloud-b": _oauth_url("cloud-b")}
         with patch("cloudinary_cli.auth.load_config", return_value=saved), \
-                patch("cloudinary_cli.auth.remove_config_keys") as remove:
+                patch("cloudinary_cli.auth.remove_config_keys") as remove, \
+                patch("cloudinary_cli.auth.flow.revoke"):
             result = self.runner.invoke(cli, ["logout"], input="2\n")
         self.assertIn("cloud-a", result.output)
         self.assertIn("cloud-b", result.output)
@@ -150,8 +163,17 @@ def test_auto_default_when_sole_config_no_env_no_default(self):
         with self._patches({"eu-cloud": _oauth_url()}), \
                 patch("cloudinary_cli.auth.set_default_config") as set_default, \
                 patch("cloudinary_cli.auth.get_default_config_name", return_value=None):
-            auth.login(region="eu", name="eu-cloud")
+            name, is_default = auth.login(region="eu", name="eu-cloud")
         set_default.assert_called_once_with("eu-cloud")
+        self.assertEqual(("eu-cloud", True), (name, is_default))
+
+    def test_returns_not_default_when_other_configs_exist(self):
+        from cloudinary_cli import auth
+        with self._patches({"eu-cloud": _oauth_url(), "other": _oauth_url("other")}), \
+                patch("cloudinary_cli.auth.set_default_config"), \
+                patch("cloudinary_cli.auth.get_default_config_name", return_value=None):
+            name, is_default = auth.login(region="eu", name="eu-cloud")
+        self.assertEqual(("eu-cloud", False), (name, is_default))
 
     def test_no_auto_default_when_other_configs_exist(self):
         from cloudinary_cli import auth
@@ -184,6 +206,17 @@ def test_reserved_name_rejected(self):
             with self.assertRaises(RuntimeError):
                 auth.login(region="eu", name="__default__")
 
+    def test_cli_message_when_default(self):
+        with patch("cloudinary_cli.core.auth.run_login", return_value=("tttt", True)):
+            result = CliRunner().invoke(cli, ["login", "tttt"])
+        self.assertIn("default configuration", result.output)
+
+    def test_cli_message_when_not_default_shows_how_to_default(self):
+        with patch("cloudinary_cli.core.auth.run_login", return_value=("tttt", False)):
+            result = CliRunner().invoke(cli, ["login", "tttt"])
+        self.assertIn("cld -C tttt", result.output)
+        self.assertIn("cld config -d tttt", result.output)  # how to make it default
+
 
 class TestConfigSecretMasking(_RestoresSdkConfig):
     """show_cloudinary_config must never print a secret in the clear."""
