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

@@ -29,6 +29,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 +50,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():
+        org = os.environ.get("CLOUDSMITH_ORG", "")
+        detector_name = _get_oidc_detector_name(debug=opts.debug)
+        if detector_name:
+            source = f"OIDC auto-discovery: {detector_name} (org: {org})"
+        else:
+            source = f"OIDC auto-discovery (org: {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
+
+        detector = detect_environment(debug=debug)
+        if detector:
+            return detector.name
+    except Exception:  # pylint: disable=broad-exception-caught
+        pass
+    return None
+
+
+def _is_oidc_configured():
+    """Check if OIDC environment variables are set."""
+    org = os.environ.get("CLOUDSMITH_ORG", "").strip()
+    service = os.environ.get("CLOUDSMITH_SERVICE_SLUG", "").strip()
+    return bool(org and service)
+
+
 def _get_sso_status(api_host):
     """Return SSO token status from the system keyring."""
     enabled = keyring.should_use_keyring()
@@ -120,7 +156,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

@@ -336,6 +336,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/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
+"""

cloudsmith_cli/core/credentials/oidc/cache.py

@@ -0,0 +1,219 @@
+"""OIDC token cache.
+
+Caches Cloudsmith API tokens obtained via OIDC exchange to avoid unnecessary
+re-exchanges. Uses system keyring when available (respecting CLOUDSMITH_NO_KEYRING),
+with automatic fallback to filesystem storage when keyring is unavailable.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import time
+
+logger = logging.getLogger(__name__)
+
+EXPIRY_MARGIN_SECONDS = 60
+
+_CACHE_DIR_NAME = "oidc_token_cache"
+
+
+def _get_cache_dir() -> str:
+    """Return the cache directory path, creating it if needed."""
+    from ....cli.config import get_default_config_path
+
+    base = get_default_config_path()
+    cache_dir = os.path.join(base, _CACHE_DIR_NAME)
+    if not os.path.isdir(cache_dir):
+        os.makedirs(cache_dir, mode=0o700, exist_ok=True)
+    return cache_dir
+
+
+def _cache_key(api_host: str, org: str, service_slug: str) -> str:
+    """Compute a deterministic cache filename from the exchange parameters."""
+    raw = f"{api_host}|{org}|{service_slug}"
+    digest = hashlib.sha256(raw.encode()).hexdigest()[:32]
+    return f"oidc_{digest}.json"
+
+
+def _decode_jwt_exp(token: str) -> float | None:
+    """Decode the exp claim from a JWT without verification."""
+    try:
+        import jwt
+
+        payload = jwt.decode(
+            token,
+            options={"verify_signature": False},
+            algorithms=["RS256", "ES256", "HS256"],
+        )
+        exp = payload.get("exp")
+        if exp is not None:
+            return float(exp)
+    except Exception:  # pylint: disable=broad-exception-caught
+        logger.debug("Failed to decode JWT expiry", exc_info=True)
+    return None
+
+
+def get_cached_token(api_host: str, org: str, service_slug: str) -> str | None:
+    """Return a cached token if it exists and is not expired."""
+    token = _get_from_keyring(api_host, org, service_slug)
+    if token:
+        return token
+    return _get_from_disk(api_host, org, service_slug)
+
+
+def _get_from_keyring(api_host: str, org: str, service_slug: str) -> str | None:
+    """Try to get token from keyring."""
+    try:
+        from ...keyring import get_oidc_token
+
+        token_data = get_oidc_token(api_host, org, service_slug)
+        if not token_data:
+            return None
+
+        data = json.loads(token_data)
+        token = data.get("token")
+        expires_at = data.get("expires_at")
+
+        if not token:
+            return None
+
+        if expires_at is not None:
+            remaining = expires_at - time.time()
+            if remaining < EXPIRY_MARGIN_SECONDS:
+                logger.debug(
+                    "Keyring OIDC token expired or expiring soon "
+                    "(%.0fs remaining, margin=%ds)",
+                    remaining,
+                    EXPIRY_MARGIN_SECONDS,
+                )
+                from ...keyring import delete_oidc_token
+
+                delete_oidc_token(api_host, org, service_slug)
+                return None
+            logger.debug("Using keyring OIDC token (expires in %.0fs)", remaining)
+        else:
+            logger.debug("Using keyring OIDC token (no expiry information)")
+
+        return token
+
+    except Exception:  # pylint: disable=broad-exception-caught
+        logger.debug("Failed to read OIDC token from keyring", exc_info=True)
+        return None
+
+
+def _get_from_disk(api_host: str, org: str, service_slug: str) -> str | None:
+    """Try to get token from disk cache."""
+    cache_dir = _get_cache_dir()
+    cache_file = os.path.join(cache_dir, _cache_key(api_host, org, service_slug))
+
+    if not os.path.isfile(cache_file):
+        return None
+
+    try:
+        with open(cache_file) as f:
+            data = json.load(f)
+
+        token = data.get("token")
+        expires_at = data.get("expires_at")
+
+        if not token:
+            return None
+
+        if expires_at is not None:
+            remaining = expires_at - time.time()
+            if remaining < EXPIRY_MARGIN_SECONDS:
+                logger.debug(
+                    "Disk cached OIDC token expired or expiring soon "
+                    "(%.0fs remaining, margin=%ds)",
+                    remaining,
+                    EXPIRY_MARGIN_SECONDS,
+                )
+                _remove_cache_file(cache_file)
+                return None
+            logger.debug("Using disk cached OIDC token (expires in %.0fs)", remaining)
+        else:
+            logger.debug("Using disk cached OIDC token (no expiry information)")
+
+        return token
+
+    except (json.JSONDecodeError, OSError, KeyError):
+        logger.debug("Failed to read OIDC token from disk cache", exc_info=True)
+        _remove_cache_file(cache_file)
+        return None
+
+
+def store_cached_token(api_host: str, org: str, service_slug: str, token: str) -> None:
+    """Cache a token in keyring (if available) or filesystem."""
+    expires_at = _decode_jwt_exp(token)
+
+    data = {
+        "token": token,
+        "expires_at": expires_at,
+        "api_host": api_host,
+        "org": org,
+        "service_slug": service_slug,
+        "cached_at": time.time(),
+    }
+
+    if _store_in_keyring(api_host, org, service_slug, data):
+        return
+
+    _store_on_disk(api_host, org, service_slug, data)
+
+
+def _store_in_keyring(api_host: str, org: str, service_slug: str, data: dict) -> bool:
+    """Try to store token in keyring."""
+    try:
+        from ...keyring import store_oidc_token
+
+        token_data = json.dumps(data)
+        success = store_oidc_token(api_host, org, service_slug, token_data)
+        if success:
+            logger.debug(
+                "Stored OIDC token in keyring (expires_at=%s)", data.get("expires_at")
+            )
+        return success
+    except Exception:  # pylint: disable=broad-exception-caught
+        logger.debug("Failed to store OIDC token in keyring", exc_info=True)
+        return False
+
+
+def _store_on_disk(api_host: str, org: str, service_slug: str, data: dict) -> None:
+    """Store token on disk."""
+    cache_dir = _get_cache_dir()
+    cache_file = os.path.join(cache_dir, _cache_key(api_host, org, service_slug))
+
+    try:
+        fd = os.open(cache_file, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w") as f:
+            json.dump(data, f)
+        logger.debug(
+            "Stored OIDC token on disk (expires_at=%s)", data.get("expires_at")
+        )
+    except OSError:
+        logger.debug("Failed to write OIDC token to disk cache", exc_info=True)
+
+
+def invalidate_cached_token(api_host: str, org: str, service_slug: str) -> None:
+    """Remove a cached token from both keyring and disk."""
+    try:
+        from ...keyring import delete_oidc_token
+
+        delete_oidc_token(api_host, org, service_slug)
+    except Exception:  # pylint: disable=broad-exception-caught
+        logger.debug("Failed to delete OIDC token from keyring", exc_info=True)
+
+    cache_dir = _get_cache_dir()
+    cache_file = os.path.join(cache_dir, _cache_key(api_host, org, service_slug))
+    _remove_cache_file(cache_file)
+
+
+def _remove_cache_file(path: str) -> None:
+    """Safely remove a cache file."""
+    try:
+        os.unlink(path)
+    except (OSError, TypeError):
+        pass