Add stackit-cli compatible authentication to the SDK

[franklouwers]

CLI Provider Authentication Support for STACKIT SDK

Summary

This PR adds comprehensive support for using STACKIT CLI provider credentials directly in the SDK, enabling seamless authentication across CLI and SDK-based tools without requiring re-authentication. (requires stackitcloud/stackit-cli#1130)

Key Features

• CLI Credential Integration: New cliauth package enables SDK applications to read and use credentials stored by the STACKIT CLI
• Automatic Token Refresh: Built-in OAuth2 token refresh with bidirectional sync (tokens refreshed by SDK are written back to storage)
• Multi-Profile Support: Full support for CLI profiles with automatic resolution from explicit parameters, environment variables, or config files
• Cross-Platform Storage: Credentials stored in system keyring (macOS Keychain, Linux Secret Service, Windows Credential Manager) with automatic file fallback
• Thread-Safe: Concurrent request handling with automatic token refresh coordination
• Background Refresh: Optional background goroutine for proactive token refresh before expiration

Architecture

The implementation consists of four logical commits:

1. Core Authentication Package (core/cliauth):

   • credentials.go: Credential reading from keyring/file with profile resolution
   • token_refresh.go: OAuth2 token refresh with configurable endpoints
   • flow.go: Thread-safe http.RoundTripper implementation for automatic auth injection
   • background_refresh.go: Background token refresh with context-based lifecycle
   • doc.go: Comprehensive package documentation with usage examples

2. SDK Configuration Integration (core/config/cli_auth.go):

   • WithCLIProviderAuth(profile): Configure SDK clients to use CLI credentials
   • WithCLIBackgroundTokenRefresh(ctx): Enable background token refresh

Usage Example

// Basic usage with default profile
client, err := dns.NewAPIClient(
    config.WithCLIProviderAuth(""),
)

// With custom profile
client, err := dns.NewAPIClient(
    config.WithCLIProviderAuth("production"),
)

// With background token refresh
ctx, cancel := context.WithCancel(context.Background())
defer cancel()

client, err := dns.NewAPIClient(
    config.WithCLIBackgroundTokenRefresh(ctx),
    config.WithCLIProviderAuth(""),
)

Storage Locations

System Keyring (preferred):

• Service name: stackit-cli-api (default) or stackit-cli-api/{profile}
• Platforms: macOS Keychain, Linux Secret Service, Windows Credential Manager

File Fallback:

• Default profile: ~/.stackit/cli-api-auth-storage.txt
• Custom profiles: ~/.stackit/profiles/{profile}/cli-api-auth-storage.txt
• Format: Base64-encoded JSON

Profile Resolution Order

1. Explicit profile parameter
2. STACKIT_CLI_PROFILE environment variable
3. ~/.config/stackit/cli-profile.txt config file
4. "default" fallback

Backward Compatibility

• compatible with credentials created by existing STACKIT CLI versions
• All file paths, formats, and keyring service names match CLI exactly
• Users can seamlessly switch between CLI and SDK-based tools

Related Issues

• requires: Refactor to support separate auth for the SDK (and thus terraform) + small bugfixes stackit-cli#1130 for cli-support
• Partially fixes: Feature Request: Support CLI Authentication Fallback in the STACKIT Terraform Provider terraform-provider-stackit#719
• RFC: RFC 1: CLI Authentication in other STACKIT applications (SDKs, Terraform Provider) terraform-provider-stackit#880

Checklist

• Issue was linked above
• No generated code was adjusted manually (check comments in file header)
• Changelogs
  • Changelog in the root directory was adjusted (see here)
  • Changelog(s) of the service(s) were adjusted (see e.g. here)
• VERSION file(s) of the service(s) were adjusted
• Code format was applied: make fmt
• Examples were added / adjusted (see examples/ directory)
• Unit tests got implemented or updated
• Unit tests are passing: make test (will be checked by CI)
• No linter issues: make lint (will be checked by CI)

[franklouwers]

Please advise on versioning. Do you have conventions you use?

[marceljk]

Please advise on versioning. Do you have conventions you use?

@franklouwers Thanks for your contribution across the CLI, SDK and Terraform provider! I created internal tickets to review them soon.

Regarding versioning we do a minor bump, when something is added, like the CLI Authentication. Please adjust the version file to v0.21.0

stackit-sdk-go/core/VERSION

Line 1 in 2b4b998

v0.20.0

Create a new entry in core/CHANGELOG.md and in the global CHANGELOG.md, there you can define the changes you made.