api: add override mechanism for SOAP Header.Cookie

Sessions are consumed by API endpoints via one of:
- HTTP Cookie (vim25 for example)
- HTTP Header (vmodl2 /rest and /api)
- SOAP Header (pbm, vslm, sms for example)

The soap.Client had always set the SOAP Header cookie regardless if consumed by an API endpoint.
Clients can now opt-out of this behavior if they don't need it,
such as sts and ssoadmin, to avoid sending the SOAP Header.

This also allows clients to change the name of soap.Header.Cookie (default is still "vcSessionCookie")

vcsim: add override mechanism for session mapping

On the simulator side, API endpoints can specify where a session is sourced from.
Default is still the "vmware_soap_session" HTTP Cookie.
The pbm simulator now specifies the "vcSessionCookie" SOAP Header, behaving as real pbm/VC does.

Signed-off-by: Doug MacEachern <[email protected]>

Author: dougm

Diff for: pbm/client_test.go

@@ -18,6 +18,7 @@ package pbm_test
 
 import (
 	"context"
+	"encoding/xml"
 	"os"
 	"reflect"
 	"sort"
@@ -346,3 +347,35 @@ func TestSupportsEncryption(t *testing.T) {
 		})
 	})
 }
+
+func TestClientCookie(t *testing.T) {
+	simulator.Test(func(ctx context.Context, c *vim25.Client) {
+		pbmc, err := pbm.NewClient(ctx, c)
+		assert.NoError(t, err)
+		assert.NotNil(t, pbmc)
+
+		// Using expected Header.Cookie.XMLName = vcSessionCookie
+		pbmc.Client.Cookie = func() any {
+			return struct {
+				XMLName xml.Name `xml:"vcSessionCookie"`
+				Value   string   `xml:",chardata"`
+			}{Value: c.SessionCookie()}
+		}
+
+		ok, err := pbmc.SupportsEncryption(ctx, pbmsim.DefaultEncryptionProfileID)
+		assert.NoError(t, err)
+		assert.True(t, ok)
+
+		// Using invalid Header.Cookie.XMLName = myCookie
+		pbmc.Client.Cookie = func() any {
+			return struct {
+				XMLName xml.Name `xml:"myCookie"`
+				Value   string   `xml:",chardata"`
+			}{Value: c.SessionCookie()}
+		}
+
+		ok, err = pbmc.SupportsEncryption(ctx, pbmsim.DefaultEncryptionProfileID)
+		assert.EqualError(t, err, "ServerFaultCode: NotAuthenticated")
+		assert.False(t, ok)
+	})
+}

Diff for: pbm/simulator/simulator.go

@@ -56,6 +56,7 @@ func New() *simulator.Registry {
 	r := simulator.NewRegistry()
 	r.Namespace = pbm.Namespace
 	r.Path = pbm.Path
+	r.Cookie = simulator.SOAPCookie
 
 	r.Put(&ServiceInstance{
 		ManagedObjectReference: pbm.ServiceInstance,

Diff for: simulator/registry.go

@@ -78,6 +78,7 @@ type Registry struct {
 	Namespace string
 	Path      string
 	Handler   func(*Context, *Method) (mo.Reference, types.BaseMethodFault)
+	Cookie    func(*Context) string
 
 	tagManager tagManager
 }

Diff for: simulator/session_manager.go

@@ -329,12 +329,28 @@ type Context struct {
 	Map     *Registry
 }
 
+func SOAPCookie(ctx *Context) string {
+	var cookie string
+	_ = ctx.Header.Cookie.(*Element).Decode(&cookie)
+	return cookie
+}
+
+func HTTPCookie(ctx *Context) string {
+	if cookie, err := ctx.req.Cookie(soap.SessionCookieName); err == nil {
+		return cookie.Value
+	}
+	return ""
+}
+
 // mapSession maps an HTTP cookie to a Session.
 func (c *Context) mapSession() {
-	if cookie, err := c.req.Cookie(soap.SessionCookieName); err == nil {
-		if val, ok := c.svc.sm.getSession(cookie.Value); ok {
-			c.SetSession(val, false)
-		}
+	cookie := c.Map.Cookie
+	if cookie == nil {
+		cookie = HTTPCookie
+	}
+
+	if val, ok := c.svc.sm.getSession(cookie(c)); ok {
+		c.SetSession(val, false)
 	}
 }
 

Diff for: simulator/simulator.go

@@ -1,5 +1,5 @@
 /*
-Copyright (c) 2017-2023 VMware, Inc. All Rights Reserved.
+Copyright (c) 2017-2024 VMware, Inc. All Rights Reserved.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -497,7 +497,6 @@ func (s *Service) ServeSDK(w http.ResponseWriter, r *http.Request) {
 		Map:     s.sdk[r.URL.Path],
 		Context: context.Background(),
 	}
-	ctx.Map.WithLock(ctx, s.sm, ctx.mapSession)
 
 	var res soap.HasFault
 	var soapBody interface{}
@@ -511,6 +510,7 @@ func (s *Service) ServeSDK(w http.ResponseWriter, r *http.Request) {
 			// Redirect any Fetch method calls to the PropertyCollector singleton
 			method.This = ctx.Map.content().PropertyCollector
 		}
+		ctx.Map.WithLock(ctx, s.sm, ctx.mapSession)
 		res = s.call(ctx, method)
 	}
 
@@ -917,6 +917,10 @@ func (e *Element) decoder() *xml.Decoder {
 }
 
 func (e *Element) Decode(val interface{}) error {
+	if s, ok := val.(*string); ok {
+		*s = e.inner.Content
+		return nil
+	}
 	return e.decoder().DecodeElement(val, &e.start)
 }
 
@@ -926,6 +930,7 @@ func UnmarshalBody(typeFunc func(string) (reflect.Type, bool), data []byte) (*Me
 	req := soap.Envelope{
 		Header: &soap.Header{
 			Security: new(Element),
+			Cookie:   new(Element),
 		},
 		Body: body,
 	}

Diff for: ssoadmin/client.go

@@ -1,11 +1,11 @@
 /*
-Copyright (c) 2018-2023 VMware, Inc. All Rights Reserved.
+Copyright (c) 2018-2024 VMware, Inc. All Rights Reserved.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at
 
-    http://www.apache.org/licenses/LICENSE-2.0
+http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
@@ -95,6 +95,7 @@ func NewClient(ctx context.Context, c *vim25.Client) (*Client, error) {
 	url := getEndpointURL(ctx, c)
 	sc := c.NewServiceClient(url, Namespace)
 	sc.Version = Version
+	sc.Cookie = nil // No SOAP Header.Cookie needed
 
 	admin := &Client{
 		Client:       sc,

Diff for: sts/client.go

@@ -1,11 +1,11 @@
 /*
-Copyright (c) 2018-2023 VMware, Inc. All Rights Reserved.
+Copyright (c) 2018-2024 VMware, Inc. All Rights Reserved.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at
 
-    http://www.apache.org/licenses/LICENSE-2.0
+http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
@@ -78,6 +78,7 @@ func NewClient(ctx context.Context, c *vim25.Client) (*Client, error) {
 
 	url := getEndpointURL(ctx, c)
 	sc := c.Client.NewServiceClient(url, Namespace)
+	sc.Cookie = nil // No SOAP Header.Cookie needed
 
 	return &Client{sc, sc}, nil
 }

Diff for: vim25/soap/client.go

@@ -1,5 +1,5 @@
 /*
-Copyright (c) 2014-2023 VMware, Inc. All Rights Reserved.
+Copyright (c) 2014-2024 VMware, Inc. All Rights Reserved.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -86,7 +86,13 @@ type Client struct {
 	Types     types.Func `json:"types"`
 	UserAgent string     `json:"userAgent"`
 
-	cookie          string
+	// Cookie returns a value for the SOAP Header.Cookie.
+	// This SOAP request header is used for authentication by
+	// API endpoints such as pbm, vslm and sms.
+	// This field is set to Client.SessionCookie by default
+	// and uses "vcSessionCookie" for the Header.Cookie name.
+	// When set to nil, no SOAP Header.Cookie is set.
+	Cookie          func() any
 	insecureCookies bool
 
 	useJSON bool
@@ -210,6 +216,20 @@ func (c *Client) NewServiceClient(path string, namespace string) *Client {
 	return c.newServiceClientWithTransport(path, namespace, c.t)
 }
 
+// SessionCookie returns the value of the vmware_soap_session cookie.
+func (c *Client) SessionCookie() string {
+	for _, cookie := range c.Jar.Cookies(c.URL()) {
+		if cookie.Name == SessionCookieName {
+			return cookie.Value
+		}
+	}
+	return ""
+}
+
+func (c *Client) anySessionCookie() any {
+	return c.SessionCookie()
+}
+
 func (c *Client) newServiceClientWithTransport(path string, namespace string, t *http.Transport) *Client {
 	vc := c.URL()
 	u, err := url.Parse(path)
@@ -234,13 +254,7 @@ func (c *Client) newServiceClientWithTransport(path string, namespace string, t
 	// Copy the cookies
 	client.Client.Jar.SetCookies(u, c.Client.Jar.Cookies(u))
 
-	// Set SOAP Header cookie
-	for _, cookie := range client.Jar.Cookies(u) {
-		if cookie.Name == SessionCookieName {
-			client.cookie = cookie.Value
-			break
-		}
-	}
+	client.Cookie = c.anySessionCookie // Set SOAP Header.Cookie by default
 
 	// Copy any query params (e.g. GOVMOMI_TUNNEL_PROXY_PORT used in testing)
 	client.u.RawQuery = vc.RawQuery
@@ -718,8 +732,10 @@ func (c *Client) soapRoundTrip(ctx context.Context, reqBody, resBody HasFault) e
 		h.ID = id
 	}
 
-	h.Cookie = c.cookie
-	if h.Cookie != "" || h.ID != "" || h.Security != nil {
+	if c.Cookie != nil {
+		h.Cookie = c.Cookie()
+	}
+	if h.Cookie != nil || h.ID != "" || h.Security != nil {
 		reqEnv.Header = &h // XML marshal header only if a field is set
 	}
 

Diff for: vim25/soap/json_client.go

@@ -1,5 +1,5 @@
 /*
-Copyright (c) 2023-2023 VMware, Inc. All Rights Reserved.
+Copyright (c) 2023-2024 VMware, Inc. All Rights Reserved.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -71,8 +71,8 @@ func (c *Client) invoke(ctx context.Context, this types.ManagedObjectReference,
 		return err
 	}
 
-	if len(c.cookie) != 0 {
-		req.Header.Add(sessionHeader, c.cookie)
+	if c.Cookie != nil {
+		req.Header.Add(sessionHeader, c.Cookie().(string))
 	}
 
 	result, err := getSOAPResultPtr(res)
@@ -156,8 +156,8 @@ func isError(statusCode int) bool {
 // session header.
 func (c *Client) checkForSessionHeader(resp *http.Response) {
 	sessionKey := resp.Header.Get(sessionHeader)
-	if len(sessionKey) > 0 {
-		c.cookie = sessionKey
+	if sessionKey != "" {
+		c.Cookie = func() any { return sessionKey }
 	}
 }
 

Diff for: vim25/soap/json_client_test.go

@@ -1,5 +1,5 @@
 /*
-Copyright (c) 2023-2023 VMware, Inc. All Rights Reserved.
+Copyright (c) 2023-2024 VMware, Inc. All Rights Reserved.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -206,7 +206,7 @@ func TestFullRequestCycle(t *testing.T) {
 	c := NewClient(addr, true)
 	c.Namespace = "urn:vim25"
 	c.Version = "8.0.0.1"
-	c.cookie = "(original)"
+	c.Cookie = func() any { return "(original)" }
 	c.UseJSON(true)
 
 	c.Transport = &mockHTTP{

Diff for: vim25/soap/soap.go

@@ -1,11 +1,11 @@
 /*
-Copyright (c) 2014-2018 VMware, Inc. All Rights Reserved.
+Copyright (c) 2014-2024 VMware, Inc. All Rights Reserved.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at
 
-    http://www.apache.org/licenses/LICENSE-2.0
+http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
@@ -24,7 +24,7 @@ import (
 // Header includes optional soap Header fields.
 type Header struct {
 	Action   string      `xml:"-"`                         // Action is the 'SOAPAction' HTTP header value. Defaults to "Client.Namespace/Client.Version".
-	Cookie   string      `xml:"vcSessionCookie,omitempty"` // Cookie is a vCenter session cookie that can be used with other SDK endpoints (e.g. pbm).
+	Cookie   interface{} `xml:"vcSessionCookie,omitempty"` // Cookie is a vCenter session cookie that can be used with other SDK endpoints (e.g. pbm).
 	ID       string      `xml:"operationID,omitempty"`     // ID is the operationID used by ESX/vCenter logging for correlation.
 	Security interface{} `xml:",omitempty"`                // Security is used for SAML token authentication and request signing.
 }