add --use-oidc flag

Author: philross

AUTHENTICATION.md

@@ -114,7 +114,14 @@ Using this flow is less secure since the token is long-lived. You can provide th
    - Navigate to `Service Accounts` → Select account → `Federated Identity Providers`
    - [Configure a Federated Identity Provider](https://docs.stackit.cloud/platform/access-and-identity/service-accounts/how-tos/manage-service-account-federations/#create-a-federated-identity-provider) and the required assertions. For detailed assertion configuration per platform, see the [Terraform provider WIF guide](https://github.com/stackitcloud/terraform-provider-stackit/blob/main/docs/guides/workload_identity_federation.md).
 
-2. Configure authentication using environment variables:
+2. Configure authentication for `stackit auth activate-service-account` using one of the options below:
+
+   - Explicit flag: `--use-oidc` (takes precedence)
+   - Environment variable: `STACKIT_USE_OIDC=1`
+
+   If both are provided, the explicit flag value is used.
+
+   Example using environment variables:
 
    ```bash
    STACKIT_USE_OIDC=1

docs/stackit_auth_activate-service-account.md

@@ -27,8 +27,8 @@ stackit auth activate-service-account [flags]
   Only print the corresponding access token by using the service account token. This access token can be stored as environment variable (STACKIT_ACCESS_TOKEN) in order to be used for all subsequent commands.
   $ stackit auth activate-service-account --service-account-token my-service-account-token --only-print-access-token
 
-  Authenticate via Workload Identity Federation (OIDC) and print the short-lived access token. Set STACKIT_USE_OIDC=1 and STACKIT_SERVICE_ACCOUNT_EMAIL; no service account key file is required.
-  $ STACKIT_USE_OIDC=1 STACKIT_SERVICE_ACCOUNT_EMAIL=ci@sa.stackit.cloud stackit auth activate-service-account --only-print-access-token
+  Authenticate via Workload Identity Federation (OIDC) and print the short-lived access token. Use --use-oidc to explicitly enable OIDC (takes precedence over STACKIT_USE_OIDC); no service account key file is required.
+  $ STACKIT_SERVICE_ACCOUNT_EMAIL=ci@sa.stackit.cloud stackit auth activate-service-account --use-oidc --only-print-access-token
 ```
 
 ### Options
@@ -39,6 +39,7 @@ stackit auth activate-service-account [flags]
       --private-key-path string           RSA private key path. It takes precedence over the private key included in the service account key, if present
       --service-account-key-path string   Service account key path
       --service-account-token string      Service account long-lived access token
+      --use-oidc                          Use Workload Identity Federation (OIDC). If set, this takes precedence over STACKIT_USE_OIDC
 ```
 
 ### Options inherited from parent commands

internal/cmd/auth/activate-service-account/activate_service_account.go

@@ -25,13 +25,15 @@ const (
 	serviceAccountTokenFlag   = "service-account-token"
 	serviceAccountKeyPathFlag = "service-account-key-path"
 	privateKeyPathFlag        = "private-key-path"
+	useOIDCFlag               = "use-oidc"
 	onlyPrintAccessTokenFlag  = "only-print-access-token" // #nosec G101
 )
 
 type inputModel struct {
 	ServiceAccountToken   string
 	ServiceAccountKeyPath string
 	PrivateKeyPath        string
+	UseOIDC               *bool
 	OnlyPrintAccessToken  bool
 }
 
@@ -60,8 +62,8 @@ func NewCmd(params *types.CmdParams) *cobra.Command {
 				"$ stackit auth activate-service-account --service-account-token my-service-account-token --only-print-access-token",
 			),
 			examples.NewExample(
-				`Authenticate via Workload Identity Federation (OIDC) and print the short-lived access token. Set STACKIT_USE_OIDC=1 and STACKIT_SERVICE_ACCOUNT_EMAIL; no service account key file is required.`,
-				"$ STACKIT_USE_OIDC=1 STACKIT_SERVICE_ACCOUNT_EMAIL=ci@sa.stackit.cloud stackit auth activate-service-account --only-print-access-token",
+				`Authenticate via Workload Identity Federation (OIDC) and print the short-lived access token. Use --use-oidc to explicitly enable OIDC (takes precedence over STACKIT_USE_OIDC); no service account key file is required.`,
+				"$ STACKIT_SERVICE_ACCOUNT_EMAIL=ci@sa.stackit.cloud stackit auth activate-service-account --use-oidc --only-print-access-token",
 			),
 		),
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -71,7 +73,7 @@ func NewCmd(params *types.CmdParams) *cobra.Command {
 			}
 
 			// use workload identity federation (OIDC) if enabled; no key file required
-			if auth.IsOIDCEnabled() {
+			if auth.IsOIDCEnabledWithOverride(model.UseOIDC) {
 				return runOIDCMode(params, model)
 			}
 
@@ -124,6 +126,7 @@ func configureFlags(cmd *cobra.Command) {
 	cmd.Flags().String(serviceAccountTokenFlag, "", "Service account long-lived access token")
 	cmd.Flags().String(serviceAccountKeyPathFlag, "", "Service account key path")
 	cmd.Flags().String(privateKeyPathFlag, "", "RSA private key path. It takes precedence over the private key included in the service account key, if present")
+	cmd.Flags().Bool(useOIDCFlag, false, "Use Workload Identity Federation (OIDC). If set, this takes precedence over STACKIT_USE_OIDC")
 	cmd.Flags().Bool(onlyPrintAccessTokenFlag, false, "If this is set to true the credentials are not stored in either the keyring or a file")
 }
 
@@ -134,6 +137,10 @@ func parseInput(p *print.Printer, cmd *cobra.Command, _ []string) (*inputModel,
 		PrivateKeyPath:        flags.FlagToStringValue(p, cmd, privateKeyPathFlag),
 		OnlyPrintAccessToken:  flags.FlagToBoolValue(p, cmd, onlyPrintAccessTokenFlag),
 	}
+	if cmd.Flags().Changed(useOIDCFlag) {
+		useOIDC := flags.FlagToBoolValue(p, cmd, useOIDCFlag)
+		model.UseOIDC = &useOIDC
+	}
 
 	p.DebugInputModel(model)
 	return &model, nil

internal/cmd/auth/activate-service-account/activate_service_account_test.go

@@ -14,11 +14,16 @@ import (
 
 var testTokenCustomEndpoint = "token_url"
 
+func boolPtr(v bool) *bool {
+	return &v
+}
+
 func fixtureFlagValues(mods ...func(flagValues map[string]string)) map[string]string {
 	flagValues := map[string]string{
 		serviceAccountTokenFlag:   "token",
 		serviceAccountKeyPathFlag: "sa_key",
 		privateKeyPathFlag:        "private_key",
+		useOIDCFlag:               "true",
 		onlyPrintAccessTokenFlag:  "true",
 	}
 	for _, mod := range mods {
@@ -32,6 +37,7 @@ func fixtureInputModel(mods ...func(model *inputModel)) *inputModel {
 		ServiceAccountToken:   "token",
 		ServiceAccountKeyPath: "sa_key",
 		PrivateKeyPath:        "private_key",
+		UseOIDC:               boolPtr(true),
 		OnlyPrintAccessToken:  true,
 	}
 	for _, mod := range mods {
@@ -65,6 +71,7 @@ func TestParseInput(t *testing.T) {
 				ServiceAccountToken:   "",
 				ServiceAccountKeyPath: "",
 				PrivateKeyPath:        "",
+				UseOIDC:               nil,
 			},
 		},
 		{
@@ -80,8 +87,29 @@ func TestParseInput(t *testing.T) {
 				ServiceAccountToken:   "",
 				ServiceAccountKeyPath: "",
 				PrivateKeyPath:        "",
+				UseOIDC:               nil,
 			},
 		},
+		{
+			description: "use_oidc_true",
+			flagValues: fixtureFlagValues(func(flagValues map[string]string) {
+				flagValues[useOIDCFlag] = "true"
+			}),
+			isValid: true,
+			expectedModel: fixtureInputModel(func(model *inputModel) {
+				model.UseOIDC = boolPtr(true)
+			}),
+		},
+		{
+			description: "use_oidc_false",
+			flagValues: fixtureFlagValues(func(flagValues map[string]string) {
+				flagValues[useOIDCFlag] = "false"
+			}),
+			isValid: true,
+			expectedModel: fixtureInputModel(func(model *inputModel) {
+				model.UseOIDC = boolPtr(false)
+			}),
+		},
 		{
 			description: "invalid_flag",
 			flagValues: fixtureFlagValues(func(flagValues map[string]string) {
@@ -101,6 +129,18 @@ func TestParseInput(t *testing.T) {
 				model.OnlyPrintAccessToken = false
 			}),
 		},
+		{
+			description: "default value UseOIDC",
+			flagValues: fixtureFlagValues(
+				func(flagValues map[string]string) {
+					delete(flagValues, useOIDCFlag)
+				},
+			),
+			isValid: true,
+			expectedModel: fixtureInputModel(func(model *inputModel) {
+				model.UseOIDC = nil
+			}),
+		},
 	}
 
 	for _, tt := range tests {
@@ -164,3 +204,4 @@ func TestStoreCustomEndpointFlags(t *testing.T) {
 		})
 	}
 }
+

internal/pkg/auth/oidc.go

@@ -22,6 +22,16 @@ func IsOIDCEnabled() bool {
 	return os.Getenv(EnvUseOIDC) == "1"
 }
 
+// IsOIDCEnabledWithOverride resolves OIDC mode using explicit input first and env fallback.
+// If useOIDC is not nil, its value is used directly; otherwise STACKIT_USE_OIDC is evaluated.
+func IsOIDCEnabledWithOverride(useOIDC *bool) bool {
+	if useOIDC != nil {
+		return *useOIDC
+	}
+
+	return IsOIDCEnabled()
+}
+
 func OIDCServiceAccountEmail() string {
 	return os.Getenv(EnvServiceAccountEmail)
 }

internal/pkg/auth/oidc_test.go

@@ -10,6 +10,10 @@ import (
 	"github.com/stackitcloud/stackit-cli/internal/pkg/auth"
 )
 
+func boolPtr(v bool) *bool {
+	return &v
+}
+
 func TestIsEnabled(t *testing.T) {
 	tests := []struct {
 		value    string
@@ -41,6 +45,45 @@ func TestIsEnabled_Unset(t *testing.T) {
 	}
 }
 
+func TestIsOIDCEnabledWithOverride(t *testing.T) {
+	tests := []struct {
+		description string
+		envUseOIDC  string
+		override    *bool
+		expected    bool
+	}{
+		{
+			description: "uses env when override is nil",
+			envUseOIDC:  "1",
+			override:    nil,
+			expected:    true,
+		},
+		{
+			description: "override true wins over env false",
+			envUseOIDC:  "0",
+			override:    boolPtr(true),
+			expected:    true,
+		},
+		{
+			description: "override false wins over env true",
+			envUseOIDC:  "1",
+			override:    boolPtr(false),
+			expected:    false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.description, func(t *testing.T) {
+			t.Setenv(auth.EnvUseOIDC, tt.envUseOIDC)
+
+			got := auth.IsOIDCEnabledWithOverride(tt.override)
+			if got != tt.expected {
+				t.Errorf("IsOIDCEnabledWithOverride() = %v, want %v", got, tt.expected)
+			}
+		})
+	}
+}
+
 func TestServiceAccountEmail(t *testing.T) {
 	const want = "ci@sa.stackit.cloud"
 	t.Setenv(auth.EnvServiceAccountEmail, want)