[JorTurFer]

Description

Adds core/credentials, a package of modular token providers, and config.WithTokenProvider to use one of them with any service client. The existing authentication flows are not modified: this is an additive, opt-in way to authenticate.

Status: draft. The public SDK is a contract, so this is not to be merged until the integration of the package with the control plane SDK has been validated.

What is added

• One contract. TokenProvider returns an access token and nothing else. Each authentication flow is a provider:
  WorkloadIdentityFederationProvider, ServiceAccountKeyProvider, StaticTokenProvider, InstanceMetadataProvider and CLIProvider.
• Composition. ChainedProvider tries providers in order, and NewDefaultProvider builds the default chain: workload identity federation, service account key, static token, instance metadata and, only if enabled (EnableCLI or STACKIT_USE_CLI=true), the STACKIT CLI session. The CLI is opt-in because it authenticates as the person logged in, not as the application.
• Caching. A provider keeps one token per combination of scopes and resources, refreshes it shortly before it expires, and makes a single request when several goroutines ask at once. Resources become the aud of the token (RFC 8707).
• Configuration. Values are resolved from the config first, then from the environment, then (for some) from the credentials file, so anything explicit in code wins. The service account key and the private key can be given as content or as a path.
• config.WithTokenProvider. Makes auth.DefaultAuth authenticate through the provider. Options that explicitly choose how to authenticate (WithToken, WithServiceAccountKey, WithCustomAuth, ...) still take precedence over it.
• Docs. README for the package, a section in the main README, the authentication example and the changelogs.

Design notes

• Package name. credentials rather than identity, so it does not clash with the upcoming services/identity, and to follow the naming of other SDKs.
• Public surface. Only the contract, the providers with their configs and constructors, the chains and SetLogger are exported. Constants, file formats and helpers are private.
• Singleflight. The token cache has its own small singleflight instead of golang.org/x/sync/singleflight, to keep the dependencies of core to a minimum, since every service module inherits them. Using x/sync would replace it with a Group.DoChan call whose fetch runs on context.WithoutCancel.
• Versioning. The package lives in the core module and is versioned with it (core/VERSION is bumped to v0.27.0).

Out of scope

• The legacy authentication is neither modified nor deprecated; there is no replacement constructor yet to point to.
• STACKIT_TOKEN_BASEURL is not supported by the new package.
• A second builder in the generator and an end-to-end authentication test are tracked separately.

Checklist

• [x] Issue was linked above -> Internal dicussion
• No generated code was adjusted manually
• Changelogs
  • Changelog in the root directory was adjusted
  • Changelog of core was adjusted
• VERSION file of core was adjusted
• Code format was applied
• Examples were added / adjusted (see examples/ directory)
• Unit tests got implemented or updated
• Unit tests are passing: go test ./... in core
• No linter issues: golangci-lint run --config golang-ci.yaml ./... in core

🤖 Generated with Claude Code