[Feat] API Key and custom headers as an alternative method of authorisation (#1062)

Co-authored-by: Andrew Sumner <andrew.sumner@datatorque.com>
Co-authored-by: Gullapalli Akhil Sai <akhilsai.gullapalli@nutanix.com>

Author: 3 people

.env.example

@@ -18,5 +18,10 @@ NDB_ENDPOINT="x.x.x.x"
 NDB_USERNAME="x.x.x.x"
 NDB_PASSWORD="x.x.x.x"
 
+# API Key (the `X-Ntnx-Api-Key` header will be used instead of Basic Authentication) and Custom Headers (eg for Cloudflare Access)
+# NUTANIX_API_KEY="xxx" 
+# NUTANIX_HEADER_CF_ACCESS_CLIENT_ID="xxx.access"
+# NUTANIX_HEADER_CF_ACCESS_CLIENT_SECRET="xxx"
+
 # Terraform / test log level
 TF_LOG=ERROR

CONTRIBUTING.md

@@ -81,50 +81,67 @@ under:
    Local Nutanix provider plugin will be used after `terraform init`
    command execution in Terraform template directory
 
-
 ### Running tests of provider
 
 For running unit tests:
+
 ```sh
 make test
 ```
 
 For running integration tests:
 
 1. Add environment variables for setup related details:
-```ssh
-export NUTANIX_USERNAME="<username>"
-export NUTANIX_PASSWORD="<password>"
-export NUTANIX_INSECURE=true
-export NUTANIX_PORT=9440
-export NUTANIX_ENDPOINT="<pc-ip>"
-export NUTANIX_STORAGE_CONTAINER="<storage-container-uuid-for-vm-tests>"
-export FOUNDATION_ENDPOINT="<foundation-vm-ip-for-foundation-related-tests>"
-export FOUNDATION_PORT=8000
-export NOS_IMAGE_TEST_URL="<test-image-url>"
-export NDB_ENDPOINT="<ndb-ip>"
-export NDB_USERNAME="<username>"
-export NDB_PASSWORD="<password>"
-```
+
+    ```sh
+    export NUTANIX_USERNAME="<username>"
+    export NUTANIX_PASSWORD="<password>"
+    export NUTANIX_INSECURE=true
+    export NUTANIX_PORT=9440
+    export NUTANIX_ENDPOINT="<pc-ip>"
+    export NUTANIX_STORAGE_CONTAINER="<storage-container-uuid-for-vm-tests>"
+    export FOUNDATION_ENDPOINT="<foundation-vm-ip-for-foundation-related-tests>"
+    export FOUNDATION_PORT=8000
+    export NOS_IMAGE_TEST_URL="<test-image-url>"
+    export NDB_ENDPOINT="<ndb-ip>"
+    export NDB_USERNAME="<username>"
+    export NDB_PASSWORD="<password>"
+    ```
+
+    Alternatively, you can authenticate using an API key instead of username/password:
+
+    ```sh
+    export NUTANIX_API_KEY="<api-key>"
+    ```
+
+    Custom HTTP headers (e.g. for Cloudflare Access) can be injected via environment variables with the `NUTANIX_HEADER_` prefix:
+
+    ```sh
+    export NUTANIX_HEADER_CF_ACCESS_CLIENT_ID="<client-id>"
+    export NUTANIX_HEADER_CF_ACCESS_CLIENT_SECRET="<client-secret>"
+    ```
 
 2. Some tests need setup related constants for resource creation. So add/replace details in test_config.json (for pc tests) and test_foundation_config.json (for foundation and foundation central tests and NDB)
 
 3. To run all tests:
-```ssh
-make testacc
-```
+
+    ```sh
+    make testacc
+    ```
 
 4. To run specific tests:
-```ssh 
-export TESTARGS='-run=TestAccNutanixPbr_WithSourceExternalDestinationNetwork'
-make testacc
-```
+
+    ```sh
+    export TESTARGS='-run=TestAccNutanixPbr_WithSourceExternalDestinationNetwork'
+    make testacc
+    ```
 
 5. To run collection of tests:
-``` ssh
-export TESTARGS='-run=TestAccNutanixPbr*'
-make testacc
-```
+
+    ```sh
+    export TESTARGS='-run=TestAccNutanixPbr*'
+    make testacc
+    ```
 
 ### Common Issues using the development binary.
 

README.md

@@ -108,13 +108,16 @@ Long term, once this is upstream, no pre-compiled binaries will be needed, as te
 The following keys can be used to configure the provider.
 
 * **endpoint** - (Required) IP address for the Nutanix Prism Central.
-* **username** - (Required) Username for Nutanix Prism Central. Could be local cluster auth (e.g. `auth`) or directory auth.
-* **password** - (Required) Password for the provided username.
-* **port** - (Optional) Port for the Nutanix Prism Central. Default port is 9440.
+* **username** - (Optional) Username for Nutanix Prism Central. Could be local cluster auth (e.g. `auth`) or directory auth. Required if `api_key` is not set.
+* **password** - (Optional) Password for the provided username. Required if `api_key` is not set.
+* **api_key** - (Optional) API key for Prism Central authentication. Can be used as an alternative to `username`/`password` when connecting to a Prism Central instance. **Not supported by Prism Elements**, which requires `username` and `password`. When set, the `X-Ntnx-Api-Key` header is used instead of Basic Authentication.
+* **port** - (Optional) Port for the Nutanix Prism Central. Default port is 9440. Can also be set via the `NUTANIX_PORT` environment variable.
 * **insecure** - (Optional) Explicitly allow the provider to perform insecure SSL requests. If omitted, default value is false.
-* **wait_timeout** - (optional) Set if you know that the creation o update of a resource may take long time (minutes).
+* **wait_timeout** - (Optional) Set if you know that the creation or update of a resource may take long time (minutes).
+* **custom_headers** - (Optional) Map of custom HTTP headers to add to all API requests. Useful for environments that require additional headers such as Cloudflare Access service tokens. Headers can also be set via environment variables with the `NUTANIX_HEADER_` prefix (e.g. `NUTANIX_HEADER_CF_ACCESS_CLIENT_ID` becomes `Cf-Access-Client-Id`). Values defined in config take precedence over environment variables.
 
 ```hcl
+# Basic authentication
 provider "nutanix" {
   username     = "admin"
   password     = "myPassword"
@@ -123,9 +126,22 @@ provider "nutanix" {
   insecure     = true
   wait_timeout = 10
 }
+
+# API key authentication with custom headers (e.g. Cloudflare Access)
+provider "nutanix" {
+  api_key      = "my-api-key"
+  port         = 443
+  endpoint     = "10.36.7.201"
+  insecure     = true
+  wait_timeout = 10
+  custom_headers = {
+    "Cf-Access-Client-Id"     = "my-client-id"
+    "Cf-Access-Client-Secret" = "my-client-secret"
+  }
+}
 ```
 
-## From terraform-provider-nutanix v1.5.0-beta :
+## From terraform-provider-nutanix v1.5.0-beta
 
 The following keys can be used to configure the provider.
 
@@ -151,7 +167,7 @@ provider "nutanix" {
 }
 ```
 
-## Additional fields for using Nutanix Database Service:
+## Additional fields for using Nutanix Database Service
 
 * **ndb_username** - (Optional) Username of Nutanix Database Service server
 * **ndb_password** - (Optional) Password of Nutanix Database Service server
@@ -166,10 +182,10 @@ provider "nutanix" {
 ```
 
 ### Provider Configuration Requirements & Warnings
-From foundation getting released in 1.5.0-beta, provider configuration will accomodate prism central and foundation apis connection details. **It will show warnings for disabled api connections as per the attributes given in provider configuration in above mentioned format**. The below are the required attributes for corresponding provider componenets :
-* endpoint, username and password are required fields for using Prism Central & Karbon based resources and data sources
-* foundation_endpoint is required field for using Foundation based resources and data sources
-* ndb_username, ndb_password and ndb_endpoint are required fields for using NDB based resources and data sources
+From foundation getting released in 1.5.0-beta, provider configuration will accommodate Prism Central and foundation API connection details. **It will show warnings for disabled API connections as per the attributes given in provider configuration in above mentioned format**. The below are the required attributes for corresponding provider components:
+* `endpoint` and either (`username` + `password`) or `api_key` are required for using Prism Central & Karbon based resources and data sources.
+* `foundation_endpoint` is required field for using Foundation based resources and data sources
+* `ndb_username`, `ndb_password` and `ndb_endpoint` are required fields for using NDB based resources and data sources
 
 
 ## Resources

nutanix/acctest/acctest.go

@@ -36,13 +36,29 @@ func TestProviderImpl(t *testing.T) {
 }
 
 func TestAccPreCheck(t *testing.T) {
-	if os.Getenv("NUTANIX_USERNAME") == "" ||
-		os.Getenv("NUTANIX_PASSWORD") == "" ||
-		os.Getenv("NUTANIX_INSECURE") == "" ||
+	// Check common required variables
+	if os.Getenv("NUTANIX_INSECURE") == "" ||
 		os.Getenv("NUTANIX_PORT") == "" ||
 		os.Getenv("NUTANIX_ENDPOINT") == "" ||
 		os.Getenv("NUTANIX_STORAGE_CONTAINER") == "" {
-		t.Fatal("`NUTANIX_USERNAME`,`NUTANIX_PASSWORD`,`NUTANIX_INSECURE`,`NUTANIX_PORT`,`NUTANIX_ENDPOINT`, `NUTANIX_STORAGE_CONTAINER` must be set for acceptance testing")
+		t.Fatal("`NUTANIX_INSECURE`,`NUTANIX_PORT`,`NUTANIX_ENDPOINT`,`NUTANIX_STORAGE_CONTAINER` must be set for acceptance testing")
+	}
+
+	// Check authentication - either username/password OR api_key must be set
+	hasBasicAuth := os.Getenv("NUTANIX_USERNAME") != "" && os.Getenv("NUTANIX_PASSWORD") != ""
+	hasAPIKey := os.Getenv("NUTANIX_API_KEY") != ""
+
+	if !hasBasicAuth && !hasAPIKey {
+		t.Fatal("Either `NUTANIX_USERNAME` and `NUTANIX_PASSWORD`, or `NUTANIX_API_KEY` must be set for acceptance testing")
+	}
+}
+
+// TestAccPreCheckStorageContainer checks for storage container requirement
+// Use this in addition to TestAccPreCheck for tests that create VMs with disks
+func TestAccPreCheckStorageContainer(t *testing.T) {
+	TestAccPreCheck(t)
+	if os.Getenv("NUTANIX_STORAGE_CONTAINER") == "" {
+		t.Fatal("`NUTANIX_STORAGE_CONTAINER` must be set for VM creation tests")
 	}
 }
 

nutanix/client/client.go

@@ -59,7 +59,7 @@ type Client struct {
 // RequestCompletionCallback defines the type of the request callback function
 type RequestCompletionCallback func(*http.Request, *http.Response, interface{})
 
-// Credentials needed username and password
+// Credentials needed username and password (or API key)
 type Credentials struct {
 	URL                string
 	Username           string
@@ -75,6 +75,8 @@ type Credentials struct {
 	NdbEndpoint        string              // Required field for connecting to Era VM APIs.
 	NdbUsername        string
 	NdbPassword        string
+	APIKey             string            // API key for authentication (alternative to username/password)
+	CustomHeaders      map[string]string // Custom headers to add to all requests (e.g., for Cloudflare Access)
 }
 
 // AdditionalFilter specification for client side filters
@@ -83,6 +85,31 @@ type AdditionalFilter struct {
 	Values []string
 }
 
+// applyAuthHeaders adds the appropriate authentication header to the request
+// Priority: Cookies (session auth) > API Key > Basic Auth
+func (c *Client) applyAuthHeaders(req *http.Request) {
+	if c.Cookies != nil {
+		// Session-based authentication using cookies
+		for _, cookie := range c.Cookies {
+			req.AddCookie(cookie)
+		}
+	} else if c.Credentials.APIKey != "" {
+		// API key authentication
+		req.Header.Add("X-Ntnx-Api-Key", c.Credentials.APIKey)
+	} else {
+		// Basic authentication (username/password)
+		req.Header.Add("Authorization", "Basic "+
+			base64.StdEncoding.EncodeToString([]byte(c.Credentials.Username+":"+c.Credentials.Password)))
+	}
+}
+
+// applyCustomHeaders adds any custom headers from credentials to the request
+func (c *Client) applyCustomHeaders(req *http.Request) {
+	for key, value := range c.Credentials.CustomHeaders {
+		req.Header.Add(key, value)
+	}
+}
+
 // NewClient returns a wrapper around http/https (as per isHTTP flag) client with additions of proxy & session_auth if given
 func NewClient(credentials *Credentials, userAgent string, absolutePath string, isHTTP bool) (*Client, error) {
 	if userAgent == "" {
@@ -204,18 +231,12 @@ func (c *Client) NewRequest(ctx context.Context, method, urlStr string, body int
 	req.Header.Add("Content-Type", mediaType)
 	req.Header.Add("Accept", mediaType)
 	req.Header.Add("User-Agent", c.UserAgent)
-	if c.Cookies != nil {
-		for _, i := range c.Cookies {
-			req.AddCookie(i)
-		}
-	} else {
-		req.Header.Add("Authorization", "Basic "+
-			base64.StdEncoding.EncodeToString([]byte(c.Credentials.Username+":"+c.Credentials.Password)))
-	}
+	c.applyAuthHeaders(req)
+	c.applyCustomHeaders(req)
 	return req, nil
 }
 
-// NewRequest creates a request without authorisation headers
+// NewUnAuthRequest creates a request without authorisation headers
 func (c *Client) NewUnAuthRequest(ctx context.Context, method, urlStr string, body interface{}) (*http.Request, error) {
 	// check if client exists or not
 	if c.client == nil {
@@ -312,13 +333,13 @@ func (c *Client) NewUploadRequest(ctx context.Context, method, urlStr string, fi
 	req.Header.Add("Content-Type", octetStreamType)
 	req.Header.Add("Accept", mediaType)
 	req.Header.Add("User-Agent", c.UserAgent)
-	req.Header.Add("Authorization", "Basic "+
-		base64.StdEncoding.EncodeToString([]byte(c.Credentials.Username+":"+c.Credentials.Password)))
+	c.applyAuthHeaders(req)
+	c.applyCustomHeaders(req)
 
 	return req, nil
 }
 
-// NewUploadRequest handles image uploads for image service
+// NewUnAuthUploadRequest handles image uploads for image service without auth
 func (c *Client) NewUnAuthUploadRequest(ctx context.Context, method, urlStr string, fileReader *os.File) (*http.Request, error) {
 	// check if client exists or not
 	if c.client == nil {