feat(access-token): add ephemeral access-token resource (#1068)

* feat(access-token): add ephemeral access-token resource

Signed-off-by: Mauritz Uphoff <mauritz.uphoff@stackit.cloud>

Author: h3adex

docs/ephemeral-resources/access_token.md

@@ -0,0 +1,73 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "stackit_access_token Ephemeral Resource - stackit"
+subcategory: ""
+description: |-
+  Ephemeral resource that generates a short-lived STACKIT access token (JWT) using a service account key. A new token is generated each time the resource is evaluated, and it remains consistent for the duration of a Terraform operation. If a private key is not explicitly provided, the provider attempts to extract it from the service account key instead. Access tokens generated from service account keys expire after 60 minutes.
+  ~> Service account key credentials must be configured either in the STACKIT provider configuration or via environment variables (see example below). If any other authentication method is configured, this ephemeral resource will fail with an error.
+  ~> This ephemeral-resource is in beta and may be subject to breaking changes in the future. Use with caution. See our guide https://registry.terraform.io/providers/stackitcloud/stackit/latest/docs/guides/opting_into_beta_resources for how to opt-in to use beta resources.
+---
+
+# stackit_access_token (Ephemeral Resource)
+
+Ephemeral resource that generates a short-lived STACKIT access token (JWT) using a service account key. A new token is generated each time the resource is evaluated, and it remains consistent for the duration of a Terraform operation. If a private key is not explicitly provided, the provider attempts to extract it from the service account key instead. Access tokens generated from service account keys expire after 60 minutes.
+
+~> Service account key credentials must be configured either in the STACKIT provider configuration or via environment variables (see example below). If any other authentication method is configured, this ephemeral resource will fail with an error.
+
+~> This ephemeral-resource is in beta and may be subject to breaking changes in the future. Use with caution. See our [guide](https://registry.terraform.io/providers/stackitcloud/stackit/latest/docs/guides/opting_into_beta_resources) for how to opt-in to use beta resources.
+
+## Example Usage
+
+```terraform
+provider "stackit" {
+  default_region           = "eu01"
+  service_account_key_path = "/path/to/sa_key.json"
+  enable_beta_resources    = true
+}
+
+ephemeral "stackit_access_token" "example" {}
+
+locals {
+  stackit_api_base_url = "https://iaas.api.stackit.cloud"
+  public_ip_path       = "/v2/projects/${var.project_id}/regions/${var.region}/public-ips"
+
+  public_ip_payload = {
+    labels = {
+      key = "value"
+    }
+  }
+}
+
+# Docs: https://registry.terraform.io/providers/Mastercard/restapi/latest
+provider "restapi" {
+  uri                  = local.stackit_api_base_url
+  write_returns_object = true
+
+  headers = {
+    Authorization = "Bearer ${ephemeral.stackit_access_token.example.access_token}"
+    Content-Type  = "application/json"
+  }
+
+  create_method  = "POST"
+  update_method  = "PATCH"
+  destroy_method = "DELETE"
+}
+
+resource "restapi_object" "public_ip_restapi" {
+  path = local.public_ip_path
+  data = jsonencode(local.public_ip_payload)
+
+  id_attribute   = "id"
+  read_method    = "GET"
+  create_method  = "POST"
+  update_method  = "PATCH"
+  destroy_method = "DELETE"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Read-Only
+
+- `access_token` (String, Sensitive) JWT access token for STACKIT API authentication.

examples/ephemeral-resources/stackit_access_token/ephemeral-resource.tf

@@ -0,0 +1,44 @@
+provider "stackit" {
+  default_region           = "eu01"
+  service_account_key_path = "/path/to/sa_key.json"
+  enable_beta_resources    = true
+}
+
+ephemeral "stackit_access_token" "example" {}
+
+locals {
+  stackit_api_base_url = "https://iaas.api.stackit.cloud"
+  public_ip_path       = "/v2/projects/${var.project_id}/regions/${var.region}/public-ips"
+
+  public_ip_payload = {
+    labels = {
+      key = "value"
+    }
+  }
+}
+
+# Docs: https://registry.terraform.io/providers/Mastercard/restapi/latest
+provider "restapi" {
+  uri                  = local.stackit_api_base_url
+  write_returns_object = true
+
+  headers = {
+    Authorization = "Bearer ${ephemeral.stackit_access_token.example.access_token}"
+    Content-Type  = "application/json"
+  }
+
+  create_method  = "POST"
+  update_method  = "PATCH"
+  destroy_method = "DELETE"
+}
+
+resource "restapi_object" "public_ip_restapi" {
+  path = local.public_ip_path
+  data = jsonencode(local.public_ip_payload)
+
+  id_attribute   = "id"
+  read_method    = "GET"
+  create_method  = "POST"
+  update_method  = "PATCH"
+  destroy_method = "DELETE"
+}

stackit/internal/conversion/conversion.go

@@ -178,8 +178,22 @@ func ParseProviderData(ctx context.Context, providerData any, diags *diag.Diagno
 
 	stackitProviderData, ok := providerData.(core.ProviderData)
 	if !ok {
-		core.LogAndAddError(ctx, diags, "Error configuring API client", fmt.Sprintf("Expected configure type stackit.ProviderData, got %T", providerData))
+		core.LogAndAddError(ctx, diags, "Error configuring API client", fmt.Sprintf("Expected configure type core.ProviderData, got %T", providerData))
 		return core.ProviderData{}, false
 	}
 	return stackitProviderData, true
 }
+
+func ParseEphemeralProviderData(ctx context.Context, providerData any, diags *diag.Diagnostics) (core.EphemeralProviderData, bool) {
+	// Prevent panic if the provider has not been configured.
+	if providerData == nil {
+		return core.EphemeralProviderData{}, false
+	}
+
+	stackitProviderData, ok := providerData.(core.EphemeralProviderData)
+	if !ok {
+		core.LogAndAddError(ctx, diags, "Error configuring API client", "Expected configure type core.EphemeralProviderData")
+		return core.EphemeralProviderData{}, false
+	}
+	return stackitProviderData, true
+}

stackit/internal/conversion/conversion_test.go

@@ -304,3 +304,91 @@ func TestParseProviderData(t *testing.T) {
 		})
 	}
 }
+
+func TestParseEphemeralProviderData(t *testing.T) {
+	type args struct {
+		providerData any
+	}
+	type want struct {
+		ok           bool
+		providerData core.EphemeralProviderData
+	}
+	tests := []struct {
+		name    string
+		args    args
+		want    want
+		wantErr bool
+	}{
+		{
+			name: "provider has not been configured",
+			args: args{
+				providerData: nil,
+			},
+			want: want{
+				ok: false,
+			},
+			wantErr: false,
+		},
+		{
+			name: "invalid provider data",
+			args: args{
+				providerData: struct{}{},
+			},
+			want: want{
+				ok: false,
+			},
+			wantErr: true,
+		},
+		{
+			name: "valid provider data 1",
+			args: args{
+				providerData: core.EphemeralProviderData{},
+			},
+			want: want{
+				ok:           true,
+				providerData: core.EphemeralProviderData{},
+			},
+			wantErr: false,
+		},
+		{
+			name: "valid provider data 2",
+			args: args{
+				providerData: core.EphemeralProviderData{
+					PrivateKey:            "",
+					PrivateKeyPath:        "/home/dev/foo/private-key.json",
+					ServiceAccountKey:     "",
+					ServiceAccountKeyPath: "/home/dev/foo/key.json",
+					TokenCustomEndpoint:   "",
+				},
+			},
+			want: want{
+				ok: true,
+				providerData: core.EphemeralProviderData{
+					PrivateKey:            "",
+					PrivateKeyPath:        "/home/dev/foo/private-key.json",
+					ServiceAccountKey:     "",
+					ServiceAccountKeyPath: "/home/dev/foo/key.json",
+					TokenCustomEndpoint:   "",
+				},
+			},
+			wantErr: false,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ctx := context.Background()
+			diags := diag.Diagnostics{}
+
+			actual, ok := ParseEphemeralProviderData(ctx, tt.args.providerData, &diags)
+			if diags.HasError() != tt.wantErr {
+				t.Errorf("ConfigureClient() error = %v, want %v", diags.HasError(), tt.wantErr)
+			}
+			if ok != tt.want.ok {
+				t.Errorf("ParseProviderData() got = %v, want %v", ok, tt.want.ok)
+			}
+			if !reflect.DeepEqual(actual, tt.want.providerData) {
+				t.Errorf("ParseProviderData() got = %v, want %v", actual, tt.want)
+			}
+		})
+	}
+}

stackit/internal/core/core.go

@@ -16,8 +16,9 @@ import (
 type ResourceType string
 
 const (
-	Resource   ResourceType = "resource"
-	Datasource ResourceType = "datasource"
+	Resource          ResourceType = "resource"
+	Datasource        ResourceType = "datasource"
+	EphemeralResource ResourceType = "ephemeral-resource"
 
 	// Separator used for concatenation of TF-internal resource ID
 	Separator = ","
@@ -26,6 +27,16 @@ const (
 	DatasourceRegionFallbackDocstring = "Uses the `default_region` specified in the provider configuration as a fallback in case no `region` is defined on datasource level."
 )
 
+type EphemeralProviderData struct {
+	ProviderData
+
+	PrivateKey            string
+	PrivateKeyPath        string
+	ServiceAccountKey     string
+	ServiceAccountKeyPath string
+	TokenCustomEndpoint   string
+}
+
 type ProviderData struct {
 	RoundTripper        http.RoundTripper
 	ServiceAccountEmail string // Deprecated: ServiceAccountEmail is not required and will be removed after 12th June 2025.

stackit/internal/services/access_token/access_token_acc_test.go

@@ -0,0 +1,50 @@
+package access_token_test
+
+import (
+	_ "embed"
+	"regexp"
+	"testing"
+
+	"github.com/hashicorp/terraform-plugin-testing/config"
+	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
+	"github.com/hashicorp/terraform-plugin-testing/knownvalue"
+	"github.com/hashicorp/terraform-plugin-testing/statecheck"
+	"github.com/hashicorp/terraform-plugin-testing/tfjsonpath"
+	"github.com/hashicorp/terraform-plugin-testing/tfversion"
+	"github.com/stackitcloud/terraform-provider-stackit/stackit/internal/testutil"
+)
+
+//go:embed testdata/ephemeral_resource.tf
+var ephemeralResourceConfig string
+
+var testConfigVars = config.Variables{
+	"default_region": config.StringVariable(testutil.Region),
+}
+
+func TestAccEphemeralAccessToken(t *testing.T) {
+	resource.Test(t, resource.TestCase{
+		TerraformVersionChecks: []tfversion.TerraformVersionCheck{
+			tfversion.SkipBelow(tfversion.Version1_10_0),
+		},
+		ProtoV6ProviderFactories: testutil.TestEphemeralAccProtoV6ProviderFactories,
+		Steps: []resource.TestStep{
+			{
+				Config:          ephemeralResourceConfig,
+				ConfigVariables: testConfigVars,
+				ConfigStateChecks: []statecheck.StateCheck{
+					statecheck.ExpectKnownValue(
+						"echo.example",
+						tfjsonpath.New("data").AtMapKey("access_token"),
+						knownvalue.NotNull(),
+					),
+					// JWT access tokens start with "ey" because the first part is base64-encoded JSON that begins with "{".
+					statecheck.ExpectKnownValue(
+						"echo.example",
+						tfjsonpath.New("data").AtMapKey("access_token"),
+						knownvalue.StringRegexp(regexp.MustCompile(`^ey`)),
+					),
+				},
+			},
+		},
+	})
+}