feat(auth): request broader default scopes on login

`ggshield auth login` now requests scan,
honeytokens:write, honeytokens:check, and nhi:send-inventory by
default. If any of these scopes are not granted, the command fails
with a message listing the missing permissions.

Author: GG-HH

changelog.d/20260526_hhubert_auth_login_default_scopes.md

@@ -0,0 +1,3 @@
+### Changed
+
+- `ggshield auth login` now requests broader default scopes (`scan`, `honeytokens:write`, `honeytokens:check`, `nhi:send-inventory`). If any scope is not granted, a warning is printed but login still succeeds.

ggshield/cmd/auth/login.py

@@ -3,15 +3,36 @@
 
 import click
 import requests
+from pygitguardian import GGClient
+from pygitguardian.models import APITokensResponse
 
 from ggshield.cmd.utils.common_options import add_common_options
 from ggshield.cmd.utils.context_obj import ContextObj
-from ggshield.core.client import create_client
+from ggshield.core.client import create_client, create_client_from_config
 from ggshield.core.config import Config
 from ggshield.core.constants import DEFAULT_INSTANCE_URL
 from ggshield.core.errors import UnexpectedError
 from ggshield.core.url_utils import clean_url
-from ggshield.verticals.auth import OAuthClient
+from ggshield.verticals.auth import DEFAULT_SCOPES, OAuthClient
+
+
+def _warn_missing_scopes(client: GGClient) -> None:
+    token_info = client.api_tokens()
+    granted = (
+        token_info.scopes
+        if isinstance(token_info, APITokensResponse) and token_info.scopes
+        else []
+    )
+    missing = [s for s in DEFAULT_SCOPES if s not in granted]
+    if missing:
+        click.echo(
+            "Warning: the following scopes were not granted: "
+            + ", ".join(missing)
+            + ".\n"
+            "Some features may require additional permissions at runtime.\n"
+            "Contact your workspace administrator if you need access.",
+            err=True,
+        )
 
 
 def validate_login_path(
@@ -91,7 +112,7 @@ def print_default_instance_message(config: Config) -> None:
     type=str,
     help=(
         "Space-separated list of extra scopes to request in addition to the default"
-        " `scan` scope."
+        " scopes (scan, honeytokens:write, honeytokens:check, nhi:send-inventory)."
     ),
     metavar="SCOPES",
 )
@@ -145,9 +166,10 @@ def login_cmd(
     Alternatively, you can use `--method token` to authenticate using an already existing token.
     The minimum required scope for the token is `scan`.
 
-    By default, the created token will have the `scan` scope. Use the `--scopes` option
-    to grant the token extra scopes. You can find the list of available scopes in
-    [GitGuardian API documentation][1].
+    By default, the created token will have the `scan`, `honeytokens:write`,
+    `honeytokens:check`, and `nhi:send-inventory` scopes.
+    Use the `--scopes` option to request extra scopes. You can find the list of
+    available scopes in [GitGuardian API documentation][1].
 
     If a valid personal access token is already configured, this command simply displays
     a success message indicating that ggshield is already ready to use.
@@ -232,6 +254,8 @@ def token_login(config: Config, instance: Optional[str]) -> None:
     click.echo("Authentication was successful.")
     print_default_instance_message(config)
 
+    _warn_missing_scopes(client)
+
 
 def web_login(
     config: Config,
@@ -262,4 +286,5 @@ def web_login(
         extra_scopes=extra_scopes,
         no_browser=no_browser,
     )
+    _warn_missing_scopes(create_client_from_config(config))
     print_default_instance_message(config)

ggshield/verticals/auth/__init__.py

@@ -1,7 +1,8 @@
-from .oauth import OAuthClient, OAuthError
+from .oauth import DEFAULT_SCOPES, OAuthClient, OAuthError
 
 
 __all__ = [
+    "DEFAULT_SCOPES",
     "OAuthClient",
     "OAuthError",
 ]

ggshield/verticals/auth/oauth.py

@@ -27,6 +27,12 @@
 
 CLIENT_ID = "ggshield_oauth"
 SCAN_SCOPE = "scan"
+DEFAULT_SCOPES = [
+    SCAN_SCOPE,
+    "honeytokens:write",
+    "honeytokens:check",
+    "nhi:send-inventory",
+]
 
 # Sentinel `redirect_uri` value used by the out-of-band (browser-less) OAuth
 # flow. Mirrors gcloud's `--no-launch-browser` and the historical Google
@@ -239,10 +245,11 @@ def _build_authorize_uri(self) -> str:
             "utm_medium": "login",
             "utm_campaign": "ggshield",
         }
+        unique_scopes = list(dict.fromkeys([*DEFAULT_SCOPES, *self._extra_scopes]))
         return self._oauth_client.prepare_request_uri(
             uri=urljoin(self.dashboard_url, self._login_path),
             redirect_uri=self.redirect_uri,
-            scope=[SCAN_SCOPE, *self._extra_scopes],
+            scope=unique_scopes,
             code_challenge=self.code_challenge,
             code_challenge_method="S256",
             state=self.state,

tests/unit/cmd/auth/test_login.py

@@ -43,7 +43,12 @@
         "type": "personal_access_token",
         "account_id": 17,
         "name": "key",
-        "scope": ["scan"],
+        "scope": [
+            "scan",
+            "honeytokens:write",
+            "honeytokens:check",
+            "nhi:send-inventory",
+        ],
         "expire_at": None,
     }
 )
@@ -59,6 +64,25 @@
     {"detail": "Invalid GitGuardian API key."}, 401
 )
 
+API_TOKENS_ENDPOINT = "/v1/api_tokens/self"
+
+VALID_API_TOKENS_RESPONSE = create_json_response(
+    {
+        "id": "00000000-0000-0000-0000-000000000001",
+        "name": "key",
+        "workspace_id": 17,
+        "type": "personal_access_token",
+        "status": "active",
+        "created_at": "2021-01-01T00:00:00+00:00",
+        "scopes": [
+            "scan",
+            "honeytokens:write",
+            "honeytokens:check",
+            "nhi:send-inventory",
+        ],
+    }
+)
+
 METADATA_ENDPOINT = "/v1/metadata"
 
 VALID_METADATA_RESPONSE = create_json_response(
@@ -92,6 +116,7 @@ def test_auth_login_token(self, monkeypatch, cli_fs_runner, test_case):
 
         if test_case == "valid":
             self._request_mock.add_GET(TOKEN_ENDPOINT, VALID_TOKEN_RESPONSE)
+            self._request_mock.add_GET("/v1/api_tokens/self", VALID_API_TOKENS_RESPONSE)
         elif test_case == "invalid_scope":
             self._request_mock.add_GET(
                 TOKEN_ENDPOINT, VALID_TOKEN_INVALID_SCOPE_RESPONSE
@@ -119,6 +144,53 @@ def test_auth_login_token(self, monkeypatch, cli_fs_runner, test_case):
 
         self._request_mock.assert_all_requests_happened()
 
+    def test_auth_login_token_missing_default_scopes(self, monkeypatch, cli_fs_runner):
+        """
+        GIVEN an API token that has scan but is missing other default scopes
+        WHEN the auth login command is called with --method=token
+        THEN login succeed with a message listing the missing permissions
+        AND the token is saved (scan still works)
+        AND a warning is displayed
+        """
+        token = "mysupertoken"
+        instance = "https://dashboard.gitguardian.com"
+        cmd = ["auth", "login", "--method=token", f"--instance={instance}"]
+
+        self._request_mock.add_GET(
+            TOKEN_ENDPOINT,
+            create_json_response(
+                {
+                    "type": "personal_access_token",
+                    "account_id": 17,
+                    "name": "key",
+                    "scope": ["scan"],
+                    "expire_at": None,
+                }
+            ),
+        )
+        self._request_mock.add_GET(
+            "/v1/api_tokens/self",
+            create_json_response(
+                {
+                    **VALID_API_TOKENS_RESPONSE.json(),
+                    "scopes": ["scan"],
+                }
+            ),
+        )
+
+        result = cli_fs_runner.invoke(cli, cmd, color=False, input=token + "\n")
+
+        assert result.exit_code == 0
+        assert "Warning: the following scopes were not granted:" in result.output
+        assert "honeytokens:write" in result.output
+        assert "nhi:send-inventory" in result.output
+        assert "Some features may require additional permissions" in result.output
+
+        config = Config()
+        assert config.auth_config.get_instance(instance).account.token == token
+
+        self._request_mock.assert_all_requests_happened()
+
     def test_auth_login_token_default_instance(self, monkeypatch, cli_fs_runner):
         """
         GIVEN a valid API token
@@ -130,6 +202,7 @@ def test_auth_login_token_default_instance(self, monkeypatch, cli_fs_runner):
         assert len(config.auth_config.instances) == 0
 
         self._request_mock.add_GET(TOKEN_ENDPOINT, VALID_TOKEN_RESPONSE)
+        self._request_mock.add_GET("/v1/api_tokens/self", VALID_API_TOKENS_RESPONSE)
 
         cmd = ["auth", "login", "--method=token"]
 
@@ -179,6 +252,7 @@ def test_api_instance_url(
         token = "mysupertoken"
         cmd = ["auth", "login", "--method=token", f"--instance={cmd_line_instance}"]
         self._request_mock.add_GET(TOKEN_ENDPOINT, VALID_TOKEN_RESPONSE)
+        self._request_mock.add_GET("/v1/api_tokens/self", VALID_API_TOKENS_RESPONSE)
         result = cli_fs_runner.invoke(cli, cmd, color=False, input=token + "\n")
         config = Config()
         config_instance_urls = [
@@ -208,6 +282,7 @@ def test_auth_login_token_suggests_set_instance(
         assert not Config().auth_config.instances
 
         self._request_mock.add_GET(TOKEN_ENDPOINT, VALID_TOKEN_RESPONSE)
+        self._request_mock.add_GET("/v1/api_tokens/self", VALID_API_TOKENS_RESPONSE)
 
         cmd = ["auth", "login", "--method=token"]
         if instance:
@@ -229,8 +304,11 @@ def test_auth_login_token_update_existing_config(self, monkeypatch, cli_fs_runne
         THEN the instance configuration is created if it doesn't exist, or updated otherwise
         """
         self._request_mock.add_GET(TOKEN_ENDPOINT, VALID_TOKEN_RESPONSE)
+        self._request_mock.add_GET("/v1/api_tokens/self", VALID_API_TOKENS_RESPONSE)
         self._request_mock.add_GET(TOKEN_ENDPOINT, VALID_TOKEN_RESPONSE)
+        self._request_mock.add_GET("/v1/api_tokens/self", VALID_API_TOKENS_RESPONSE)
         self._request_mock.add_GET(TOKEN_ENDPOINT, VALID_TOKEN_RESPONSE)
+        self._request_mock.add_GET("/v1/api_tokens/self", VALID_API_TOKENS_RESPONSE)
 
         instance = "https://dashboard.gitguardian.com"
         cmd = ["auth", "login", "--method=token", f"--instance={instance}"]
@@ -277,6 +355,7 @@ def test_auth_login_token_from_stdin(self, monkeypatch, cli_fs_runner):
         assert len(config.auth_config.instances) == 0
 
         self._request_mock.add_GET(TOKEN_ENDPOINT, VALID_TOKEN_RESPONSE)
+        self._request_mock.add_GET("/v1/api_tokens/self", VALID_API_TOKENS_RESPONSE)
 
         token = "mysupertoken"
 
@@ -619,7 +698,37 @@ def test_scopes(self, cli_fs_runner, monkeypatch):
         assert exit_code == ExitCode.SUCCESS, output
 
         self._webbrowser_open_mock.assert_called_once()
-        self._assert_open_url(scope_set={"scan", "honeytokens:write", "teams:read"})
+        self._assert_open_url(
+            scope_set={
+                "scan",
+                "honeytokens:write",
+                "honeytokens:check",
+                "nhi:send-inventory",
+                "teams:read",
+            }
+        )
+
+    def test_missing_default_scopes_fails_with_warning(
+        self, cli_fs_runner, monkeypatch
+    ):
+        """
+        GIVEN the backend grants only a subset of the default scopes
+        WHEN the web login flow completes
+        THEN the command succeed and lists the missing permissions
+        AND the token is still saved
+        """
+        self.prepare_mocks(
+            monkeypatch, missing_scopes=["honeytokens:write", "nhi:send-inventory"]
+        )
+        exit_code, output = self.run_cmd(cli_fs_runner)
+
+        assert exit_code == ExitCode.SUCCESS
+        assert "Warning: the following scopes were not granted:" in output
+        assert "honeytokens:write" in output
+        assert "nhi:send-inventory" in output
+        assert "Some features may require additional permissions" in output
+
+        self._assert_config("mysupertoken")
 
     def prepare_mocks(
         self,
@@ -632,6 +741,7 @@ def prepare_mocks(
         sso_url=None,
         downsized_token: Optional[bool] = False,
         scopes: Optional[str] = None,
+        missing_scopes: Optional[list] = None,
     ):
         """
         Configure self._request_mock to emulate HTTP requests
@@ -707,6 +817,12 @@ def prepare_mocks(
             if lifetime is not None:
                 expire_at = self._get_expiry_date().isoformat()
                 token_response_payload["expire_at"] = expire_at
+            if missing_scopes:
+                token_response_payload["scope"] = [
+                    s
+                    for s in token_response_payload["scope"]
+                    if s not in missing_scopes
+                ]
 
             # mock api call to exchange the code against a valid access token
             response = create_json_response({"key": token, **token_response_payload})
@@ -729,6 +845,19 @@ def prepare_mocks(
             ),
         )
 
+        if login_result == LoginResult.SUCCESS:
+            scopes = [
+                s
+                for s in VALID_API_TOKENS_RESPONSE.json()["scopes"]
+                if not missing_scopes or s not in missing_scopes
+            ]
+            self._request_mock.add_GET(
+                "/v1/api_tokens/self",
+                create_json_response(
+                    {**VALID_API_TOKENS_RESPONSE.json(), "scopes": scopes}
+                ),
+            )
+
     def run_cmd(self, cli_fs_runner, method="web"):
         """
         Run the auth login method within a virtual cli.
@@ -814,7 +943,12 @@ def _assert_open_url(
         also check if the port of the redirect url is the one expected depending on occupied ports
         """
         if scope_set is None:
-            scope_set = {"scan"}
+            scope_set = {
+                "scan",
+                "honeytokens:write",
+                "honeytokens:check",
+                "nhi:send-inventory",
+            }
 
         (url,), kwargs = self._webbrowser_open_mock.call_args_list[0]
         parsed_url = urlparse.urlparse(url)
@@ -1059,6 +1193,7 @@ def _add_token_endpoints(self, post_checker=None):
             post_checker,
         )
         self._request_mock.add_GET(TOKEN_ENDPOINT, create_json_response(token_payload))
+        self._request_mock.add_GET("/v1/api_tokens/self", VALID_API_TOKENS_RESPONSE)
         return token
 
     def test_oob_happy_path(self, cli_fs_runner, monkeypatch):