feat: add OIDC credential auto-discovery for CI/CD environments

Add a new OIDC credential provider to the credential chain that
automatically detects CI/CD environments, retrieves a vendor OIDC JWT,
and exchanges it for a short-lived Cloudsmith API token.

Key changes:
- New OidcProvider in the credential provider chain (lowest priority)
- AWS environment detector using boto3/STS (optional `aws` extra)
- OIDC token exchange with retry and exponential backoff
- Token caching via system keyring with filesystem fallback
- Keyring helpers for OIDC token storage/retrieval
- `whoami` command updated to display OIDC auth source
- README updated with optional dependency install instructions

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: cloudsmith-iduffy

README.md

@@ -136,6 +136,30 @@ Or you can get the latest pre-release version from Cloudsmith:
 pip install --upgrade cloudsmith-cli --extra-index-url=https://dl.cloudsmith.io/public/cloudsmith/cli/python/index/
 ```
 
+### Optional Dependencies
+
+The CLI supports optional extras for additional functionality:
+
+#### AWS OIDC Support
+
+For AWS environments (ECS, EKS, EC2), install with `aws` extra to enable automatic credential discovery:
+
+```
+pip install cloudsmith-cli[aws]
+```
+
+This installs `boto3[crt]` for AWS credential chain support, STS token generation, and AWS SSO compatibility.
+
+#### All Optional Features
+
+To install all optional dependencies:
+
+```
+pip install cloudsmith-cli[all]
+```
+
+**Note:** If you don't install the AWS extra, the AWS OIDC detector will gracefully skip itself with no errors.
+
 ## Configuration
 
 There are two configuration files used by the CLI:

cloudsmith_cli/cli/commands/whoami.py

@@ -7,6 +7,7 @@
 from ...core import keyring
 from ...core.api.exceptions import ApiException
 from ...core.api.user import get_token_metadata, get_user_brief
+from ...core.config_resolver import ConfigResolver
 from .. import decorators, utils
 from ..config import CredentialsReader
 from ..exceptions import handle_api_exceptions
@@ -29,6 +30,14 @@ def _get_api_key_source(opts):
     Checks in priority order matching actual resolution:
     CLI --api-key flag > CLOUDSMITH_API_KEY env var > credentials.ini.
     """
+    credential = getattr(opts, "credential", None)
+    if credential:
+        return {
+            "configured": True,
+            "source": credential.source_detail or credential.source_name,
+            "source_key": credential.source_name,
+        }
+
     if not opts.api_key:
         return {"configured": False, "source": None, "source_key": None}
 
@@ -42,12 +51,40 @@ def _get_api_key_source(opts):
         source, key = f"CLOUDSMITH_API_KEY env var (ends with ...{suffix})", "env_var"
     elif creds := CredentialsReader.find_existing_files():
         source, key = f"credentials.ini ({creds[0]})", "credentials_file"
+    elif _is_oidc_configured():
+        config = ConfigResolver().resolve()
+        detector_name = _get_oidc_detector_name(debug=opts.debug)
+        if detector_name:
+            source = f"OIDC auto-discovery: {detector_name} (org: {config.oidc_org})"
+        else:
+            source = f"OIDC auto-discovery (org: {config.oidc_org})"
+        key = "oidc"
     else:
         source, key = "CLI --api-key flag", "cli_flag"
 
     return {"configured": True, "source": source, "source_key": key}
 
 
+def _get_oidc_detector_name(debug=False):
+    """Get the name of the OIDC detector that would be used."""
+    try:
+        from cloudsmith_cli.core.credentials.oidc.detectors import detect_environment
+
+        config = ConfigResolver().resolve()
+        detector = detect_environment(config=config, debug=debug)
+        if detector:
+            return detector.name
+    except Exception:  # pylint: disable=broad-exception-caught
+        pass
+    return None
+
+
+def _is_oidc_configured():
+    """Check if OIDC org and service slug are configured."""
+    config = ConfigResolver().resolve()
+    return bool(config.oidc_org and config.oidc_service_slug)
+
+
 def _get_sso_status(api_host):
     """Return SSO token status from the system keyring."""
     enabled = keyring.should_use_keyring()
@@ -120,7 +157,12 @@ def _print_verbose_text(data):
                 click.echo(f"  Source: {ak['source']}")
             click.echo("  Note: SSO token is being used instead")
     elif active == "api_key":
-        click.secho("Authentication Method: API Key", fg="cyan", bold=True)
+        if ak.get("source_key") == "oidc":
+            click.secho(
+                "Authentication Method: OIDC Auto-Discovery", fg="cyan", bold=True
+            )
+        else:
+            click.secho("Authentication Method: API Key", fg="cyan", bold=True)
         for label, field in [
             ("Source", "source"),
             ("Token Slug", "slug"),

cloudsmith_cli/cli/config.py

@@ -247,7 +247,7 @@ def update_api_key(cls, path, api_key):
         cls._set_api_key(path, api_key)
 
 
-class Options:
+class Options:  # pylint: disable=too-many-public-methods
     """Options object that holds config for the application."""
 
     def __init__(self, *args, **kwargs):
@@ -277,6 +277,16 @@ def load_creds_file(self, path, profile=None):
         config_cls = self.get_creds_reader()
         return config_cls.load_config(self, path, profile=profile)
 
+    @property
+    def credential(self):
+        """Get the resolved credential result from the provider chain."""
+        return self._get_option("credential")
+
+    @credential.setter
+    def credential(self, value):
+        """Set the resolved credential result."""
+        self._set_option("credential", value)
+
     @property
     def api_config(self):
         """Get value for API config dictionary."""

cloudsmith_cli/cli/decorators.py

@@ -337,6 +337,7 @@ def _set_boolean(name, invert=False):
         chain = CredentialProviderChain()
 
         credential = chain.resolve(credential_context)
+        opts.credential = credential
 
         if credential_context.keyring_refresh_failed:
             click.secho(

cloudsmith_cli/core/config_resolver.py

@@ -183,6 +183,12 @@ class ClientConfig:  # pylint: disable=too-many-instance-attributes
 
     # Feature flags
     no_keyring: bool = False
+    oidc_discovery_disabled: bool = False
+
+    # OIDC-specific
+    oidc_org: str | None = None
+    oidc_service_slug: str | None = None
+    oidc_audience: str = "cloudsmith"
 
     def create_session(self, api_key: str | None = None, retry=_SENTINEL):
         """Create an HTTP session with this config applied.
@@ -246,6 +252,10 @@ def resolve(self, **overrides: Any) -> ClientConfig:
             headers=self._resolve_headers(overrides, profile),
             debug=bool(overrides.get("debug", False)),
             no_keyring=self._resolve_no_keyring(overrides),
+            oidc_discovery_disabled=self._resolve_oidc_discovery_disabled(overrides),
+            oidc_org=self._resolve_oidc_org(overrides),
+            oidc_service_slug=self._resolve_oidc_service_slug(overrides),
+            oidc_audience=self._resolve_oidc_audience(overrides),
         )
 
     # -- individual resolvers ------------------------------------------------
@@ -328,3 +338,45 @@ def _resolve_no_keyring(overrides: dict) -> bool:
             ],
             default=False,
         ).resolve()
+
+    @staticmethod
+    def _resolve_oidc_discovery_disabled(overrides: dict) -> bool:
+        override = overrides.get("oidc_discovery_disabled")
+        if override is not None:
+            return bool(override)
+        return ChainProvider(
+            [
+                EnvironmentProvider(
+                    "CLOUDSMITH_OIDC_DISCOVERY_DISABLED", cast=_cast_bool_truthy
+                ),
+            ],
+            default=False,
+        ).resolve()
+
+    @staticmethod
+    def _resolve_oidc_org(overrides: dict) -> str | None:
+        return ChainProvider(
+            [
+                InstanceProvider(overrides.get("oidc_org")),
+                EnvironmentProvider("CLOUDSMITH_ORG"),
+            ],
+        ).resolve()
+
+    @staticmethod
+    def _resolve_oidc_service_slug(overrides: dict) -> str | None:
+        return ChainProvider(
+            [
+                InstanceProvider(overrides.get("oidc_service_slug")),
+                EnvironmentProvider("CLOUDSMITH_SERVICE_SLUG"),
+            ],
+        ).resolve()
+
+    @staticmethod
+    def _resolve_oidc_audience(overrides: dict) -> str:
+        return ChainProvider(
+            [
+                InstanceProvider(overrides.get("oidc_audience")),
+                EnvironmentProvider("CLOUDSMITH_OIDC_AUDIENCE"),
+            ],
+            default="cloudsmith",
+        ).resolve()

cloudsmith_cli/core/credentials/__init__.py

@@ -79,7 +79,7 @@ class CredentialProviderChain:
     """Evaluates credential providers in order, returning the first valid result.
 
     If no providers are given, uses the default chain:
-    Keyring → CLIFlag → EnvironmentVariable → ConfigFile.
+    Keyring → CLIFlag → EnvironmentVariable → ConfigFile → OIDC.
     """
 
     def __init__(self, providers: list[CredentialProvider] | None = None):
@@ -91,13 +91,15 @@ def __init__(self, providers: list[CredentialProvider] | None = None):
                 ConfigFileProvider,
                 EnvironmentVariableProvider,
                 KeyringProvider,
+                OidcProvider,
             )
 
             self.providers = [
                 KeyringProvider(),
                 CLIFlagProvider(),
                 EnvironmentVariableProvider(),
                 ConfigFileProvider(),
+                OidcProvider(),
             ]
 
     def resolve(self, context: CredentialContext) -> CredentialResult | None:

cloudsmith_cli/core/credentials/oidc/__init__.py

@@ -0,0 +1,6 @@
+"""OIDC support for the Cloudsmith CLI credential chain.
+
+References:
+    https://help.cloudsmith.io/docs/openid-connect
+    https://cloudsmith.com/blog/securely-connect-cloudsmith-to-your-cicd-using-oidc-authentication
+"""