add CLI authentication support for provider configuration

[franklouwers]

Add CLI Authentication Support

Overview

This PR implements CLI-based authentication for the Terraform provider, enabling users to authenticate using credentials from the STACKIT CLI without managing separate service account credentials. This addresses a longstanding user request for seamless authentication across STACKIT tools.

Related Issues & PRs

Closes: #719
Related Discussion: #880

Dependencies:

• SDK PR: Add stackit-cli compatible authentication to the SDK stackit-sdk-go#3865 (adds core/cliauth package and config.WithCLIProviderAuth())
• CLI PR: Refactor to support separate auth for the SDK (and thus terraform) + small bugfixes stackit-cli#1130 (adds stackit auth provider login command)

Motivation

Users currently need to create service accounts and manage credentials separately for Terraform, even when already authenticated with the STACKIT CLI. This creates friction and complexity, especially for personal development workflows.

As highlighted in issue #719:

• Manual token extraction is cumbersome and error-prone
• Short token lifetimes make the current workaround barely usable for long operations
• Personal CLI sessions provide better audit logs than shared service accounts
• Other cloud providers (AWS, Azure, GCP) offer seamless CLI-to-Terraform authentication

Implementation

User-Facing Changes

Two new optional provider attributes:

provider "stackit" {
  cli_auth    = true          # Enable CLI authentication (default: false)
  cli_profile = "production"  # Optional: specify CLI profile (default: auto-detected)
}

Authentication Priority

The provider now follows this precedence:

1. Explicit credentials (service_account_key, service_account_key_path, token)
2. CLI authentication (when cli_auth = true and CLI is authenticated)
3. Environment variables / credentials file (existing behavior via sdkauth.SetupAuth())

This ensures backward compatibility while providing a convenient default for interactive use.

Profile Resolution

When cli_profile is not specified, the provider uses:

1. STACKIT_CLI_PROFILE environment variable
2. ~/.config/stackit/cli-profile.txt
3. "default" profile

Technical Details

The implementation leverages the SDK's new config.WithCLIProviderAuth() function, which:

• Reads credentials from system keyring (or file fallback)
• Automatically refreshes expired tokens
• Writes refreshed tokens back to storage (bidirectional sync with CLI)
• Handles OAuth2 token refresh flow transparently

Cross-platform credential storage:

• macOS: Keychain
• Linux: Secret Service (gnome-keyring, KWallet)
• Windows: Credential Manager
• **Fallback:**File at ~/.stackit/cli-provider-auth-storage.txt

Usage Example

Before (Current Workflow)

# Create service account
stackit service-account create --project-id=<project>

# Download credentials (long-lived token)
stackit service-account key create --service-account-email=<email> > credentials.json

# Configure Terraform
export STACKIT_SERVICE_ACCOUNT_KEY_PATH=credentials.json
terraform apply

After (With CLI Auth)

# Authenticate once
stackit auth provider login

# Configure Terraform
cat > main.tf <<EOF
provider "stackit" {
  cli_auth = true
}
EOF

terraform apply

Design Decisions

Explicit Opt-In (RFC #880 Requirement)

The feature requires cli_auth = true to avoid confusion about authentication behavior. Users must consciously enable CLI authentication, making it clear where credentials originate.

Minimal Coupling

The provider only depends on the SDK's configuration interface. All credential management, token refresh, and storage logic resides in the SDK's core/cliauth package, maintaining clean separation of concerns.

Backward Compatibility

Existing authentication methods continue to work unchanged. The new feature is purely additive, with no breaking changes to provider configuration or behavior.

Documentation Updates Needed

• Add CLI authentication section to provider documentation
• Update authentication guide with CLI auth workflow
• Add troubleshooting section for CLI auth issues
• Update examples to show CLI auth usage

Migration Path

1. SDK PR #3865 must be merged and released
2. CLI PR #1130 must be merged and released
3. Update provider's go.mod to use SDK version with CLI auth support
4. This PR can then be merged
5. Documentation updates published
6. Announce feature availability

---

Checklist

• Issue was linked above
• Code format was applied: make fmt
• Examples were added / adjusted (see examples/ directory)
• Docs are up-to-date: make generate-docs (will be checked by CI)
• Unit tests got implemented or updated
• Acceptance tests got implemented or updated (see e.g. here)
• Unit tests are passing: make test (will be checked by CI)
• No linter issues: make lint (will be checked by CI)