VMware vSphere Web Services SDK编程指南（五）- 5.1 客户端应用（vCenter 服务器连接）

5.1 vCenter 服务器连接

---

本章包括以下主题：

■ 5.1 vCenter 服务器连接
■ 5.2 与 vCenter 服务器建立一个单点登录会话
■ 5.3 使用用户名和密码凭证建立一个会话
■ 5.4 Web 服务器会话令牌
■ 5.5 vSphere API 的多个版本
■ 5.6 标识由服务器支持的API版本
■ 5.7 Sample 应用程序

---

5.1 vCenter 服务器连接

每个 vCenter 服务器客户端应用程序都必须连接到服务器，并将用户帐户凭证传递给服务器认证，建立连接后，客户端应用程序就可以使用 vSphere 服务访问虚拟环境。

vSphere 使用 SSL 证书、HTTP 令牌和 vCenter 单点登录口令对客户端进行身份验证，并支持客户端和 vCenter 服务器之间的持久连接。
下表提供了这些要素的概述。

Client-Server 连接的安全要素

安全要素 描述 SSL 证书 vSphere服务器使用标准 X.509 版本3 ( X.509v3 ) 证书对通过安全套接字层 (SSL)协议连接发送的会话信息进行加密，在生产环境，客户端应用程序在连接序列中验证vSphere 服务器证书。 HTTP 令牌 vSphere服务器使用一个HTTP令牌来标识验证客户端会话，服务器在对客户机连接请求的响应中提供HTTP令牌，客户机和服务器之间的后续信息包括 HTTP 令牌包含于 HTTP 消息头内。 客户端认证
单点登录口令 vSphere支持vCenter单点登录， vCenter客户端可以从一个vCenter 单点登录的服务器上获得一个vCenter 单点登录口令，并使用该口令登录到vCenter服务器 客户端认证
用户名/密码 对client-server 连接的用户名/密码验证，客户端可以直接向vCenter服务器提交用户凭证以建立会话，或者使用vCenter单点登录服务来替换SAML（Security Assertion Markup Language）令牌

5.2 与 vCenter 服务器建立一个单点登录会话

vSphere 用单点登录为客户端提供了一个单点认证， vSphere 包含 vCenter 单点登录服务器。要使用 vCenter 单点登录，你的客户端要从vCenter 单点登录服务器获取一个 SAML（Security Assertion Markup Language, 安全声明标记语言）令牌，并在发起登录请求时将该令牌传递给 vCenter 服务器，该令牌表示客户端并包含支持客户端身份验证的声明。vSphere环境中的组件基于初始身份验证执行操作。
关于从 vCenter 单点登录服务器获取 vCenter 单点登录令牌的信息可查看vCenter 单点登录编程指南。

要使用单点登录，你的客户端需调用 LoginByToken 方法，并向 vCenter服务器发送一个 SAML 令牌，通过将该令牌嵌入到 LoginByToken 请求的SOAP 消息头中。在登录过程中，客户端必须保存并恢复 HTTP 会话 cookie。
vCenter Single Sign-On SDK 包含有如何使用LoginByToken方法的示例代码。

下面描述了使用 LoginByToken 方法和vCenter服务器建立一个vCenter 单点登录会话的例子。
■ LoginByToken (C# Example) 略
■ LoginByToken (Java Example)

LoginByToken (Java Example)
下面的示例是基于 vCenter Single Sign On SDK 中的 LoginByTokenSample.java 文件的，该 SDK 包含支持 HTTP 和 SOAP 消息头操作的 Java 代码。

■ 客户端支持与 vCenter 服务器单点登录会话
■ 保存 vCenter 服务器会话 Cookie
■ 使用 LoginByToken
■ 恢复 vCenter 服务器会话 Cookie

客户端支持与 vCenter 服务器单点登录会话

当获取到 SAML 令牌后，你可以使用 vSphere Web Services API 方法 LoginByToken 建立一个与 vCenter 服务器的 vCenter 单点登录会话。
在会话开始时，客户端负责以下任务：

• 将 vCenter 单点登录令牌和一个时间戳插入到 LoginByToken 消息的 SOAP 头中；

• 维护 vCenter 会话 cookie。在登录过程中，服务器产生一个 HTTP 会话 cookie 以支持该持久连接，客户端必须保存这个 cookie 并在适当的时候重新引入它；

• 如果稍后你的客户端调用 LoginByToken 方法，或者其它登录方法，服务器会在响应中发出一个新的会话 cookie，所以你必须有一个 cookie 处理程序来保存后续请求的 cookie。

示例程序使用下列步骤：

• 调用 RetrieveServiceContent 方法和 vCenter 服务器建立一个 HTTP 连接并保存 HTTP 会话 cookie；

• 调用 LoginByToken 方法验证 vCenter 会话，为了将令牌发送到 vCenter 服务器，客户端使用一个处理程序将令牌和时间戳嵌入到消息的 SOAP 消息头中，然后客户端使用一个 HTTP 头处理方法从 vCenter 服务器响应中提取 cookie ；

• 为后续请求恢复会话 cookie。为验证会话开始于 LoginByToken 方法，客户端使用一个 handler 将会话 cookie 嵌入 HTTP 消息头里。

HTTP 和 SOAP 头处理器
要使用 vCenter 单点登录口令登录 vCenter 服务器，该示例使用头处理器（handlers）来操作登录请求的 HTTP 和 SOAP 头元素，当建立了一个 handler 之后，后续的请求会自动调用该 handler。

• handler 程序将 vCenter 单点登录令牌和时间戳放入 SOAP 头，然后将其嵌入登录请求的 HTTP 消息头。

• 一个提取 handler 程序获取由 vCenter 服务器提供的 HTTP 会话cookie。在设置了处理程序之后，对 LoginByToken 方法的调用将调用处理程序从服务器的响应中提取cookie。

下图显示了 当与 vCenter 服务器建立了一个 vCenter 单点登录会话时，使用 handler 对头元素的操作

开启一个 vCenter 会话

---

重要：对 vCenter 服务器的每次调用都将调用已建立的一些消息处理程序，在会话建立之后，使用 SOAP 和 HTTP 消息处理器所涉及的开销是不必要的。这个示例在设置 SOAP 和 HTTP 处理程序之前保存了默认的消息处理器，在会话建立之后，会重置处理器链并还原默认处理器。

示例代码还对 VimPortType.getVimPort 使用了多次调用来管理请求上下文，getVimPort 方法清除 HTTP 请求上下文。
在每次调用 getVimPort 方法之后，客户端将请求上下文端点地址重新设置为 vCenter 服务器 URL。
在客户端获取到会话 cookie 之后，会在后续请求中恢复 cookie。

---

示例代码
下面的示例代码显示了如何同安全令牌密钥所有者使用 LoginByToken 方法，示例代码片段取自 vCenter Single Sign On SDK 中的示例代码，文件位置在 Java samples 目录(SDK/ssoclient/java/JAXWS/samples)：

■ LoginByToken sample:
samples/com/vmware/vsphere/samples/LoginByTokenSample.java
■ Header cookie handlers:
samples/com/vmware/vsphere/soaphandlers/HeaderCookieHandler.java
samples/com/vmware/vsphere/soaphandlers/HeaderCookieExtractionHandler.java
■ SOAP 消息头处理器。 这是被用于 vCenter 单点登录示例中的一些处理器， 这些 SOAP handler 文件在 vCenter Single Sign-On SDK 中并位于 SSO 客户端 soaphandlers 目录:
SDK/ssoclient/java/JAXWS/samples/com/vmware/sso/client/soaphandlers

保存 vCenter 服务器会话 cookie
这部分是建立一个与 vCenter 服务器的 HTTP 会话并保存 HTTP 会话cookie 的代码片段。

下面描述了这些步骤，并展示了相应的对象和方法：

1. 使用 getHandlerResolver 方法保存默认的消息处理器。要使用 HTTP 和 SOAP 消息处理器，你必须先保存默认的消息处理器，在登录之后才能恢复出来，登录之后 HTTP 和 SOAP 消息处理器的开销是不必要的；

2. 设置 cookie 处理器。HeaderCookieExtractionHandler 方法可获取 HTTP cookie；

3. 获取 VIM 端口。VIM 端口提供了访问 vSphere API 的方法，包括 LoginByToken 方法；

4. 设置请求上下文端点地址为 vCenter 服务器 URL；

5. 获得 ServiceContent。这个方法可建立 HTTP 连接。

下面展示了保存会话 cookie 的 Java 代码。

Example: 保存 vCenter 服务器会话 Cookie

/** The example 使用一个 SAML 令牌 (从一个 vCenter 单点登录服务器获得) 和 vCenter 服务器 URL.* 下面的声明指出了数据类型; 令牌数据类型(元素)对应于 vCenter 单点登录服务器返回的令牌数据类型。** Element token; -- from vCenter Single Sign On Server* String vcServerUrl; -- identifies vCenter Server** First, save the default message handler.*/HandlerResolver defaultHandler = vimService.getHandlerResolver();/** Create a VIM service object.*/vimService = new VimService();/** Construct a managed object reference for the ServiceInstance.*/ManagedObjectReference SVC_INST_REF = new ManagedObjectReference();SVC_INST_REF.setType("ServiceInstance");SVC_INST_REF.setValue("ServiceInstance");/** Get the VIM port for access to vSphere API methods. This call clears the request context.*/vimPort = vimService.getVimPort();/** Get the request context and set the connection endpoint.*/Map<String, Object> ctxt = ((BindingProvider) vimPort)  .getRequestContext();ctxt.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, vcServerUrl);ctxt.put(BindingProvider.SESSION_MAINTAIN_PROPERTY, true);/** Retrieve the ServiceContent. This call establishes the HTTP connection.*/serviceContent = vimPort.retrieveServiceContent(SVC_INST_REF);

使用 LoginByToken
这部分是设置消息处理器和调用 LoginByToken 方法的代码片段。
下面描述了这些步骤，并展示了相应的对象和方法：

1. 创建一个 HeaderHandlerResolver 对象，然后设置消息安全处理器用于 cookie 提取并将 SAML 令牌 和认证插入 SOAP 消息头;

2. 获取 VIM 端口;

3. 在 HTTP 请求上下文设置连接端点；

4. 调用 LoginByToken 方法，该调用方法执行处理程序将元素插入到消息头中，该方法返回一个会话 cookie 用于识别新创建的会话。

5. 提取 cookie 并保存作为之后使用。

下面展示了 调用 LoginByToken 方法的 Java 代码。

Example: 使用 LoginByToken

/** Create a handler resolver and add the handlers.* Create a cookie extraction handler and add it to the handler resolver.*/HeaderHandlerResolver handlerResolver = new HeaderHandlerResolver();HeaderCookieExtractionHandler cookieExtractor = new HeaderCookieExtractionHandler();handlerResolver.addHandler(cookieExtractor);handlerResolver.addHandler(new TimeStampHandler());handlerResolver.addHandler(new SamlTokenHandler(token));handlerResolver.addHandler(new HeaderCookieHandler(cookie));handlerResolver.addHandler(new WsSecuritySignatureAssertionHandler(userCert.getPrivateKey(),userCert.getUserCert(), Utils   .getNodeProperty(token, "ID")));vimService.setHandlerResolver(handlerResolver);/** Create a handler resolver.* Set the VIM service handler resolver.*/vimService.setHandlerResolver(handlerResolver);/** Get the Vim port; this call clears the request context.*/vimPort = vimService.getVimPort();/** Retrieve the request context and set the server URL.*/Map<String, Object> ctxt = ((BindingProvider) vimPort)  .getRequestContext();ctxt.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, vcServerUrl);ctxt.put(BindingProvider.SESSION_MAINTAIN_PROPERTY, true);/** Call LoginByToken.*/UserSession us = vimPort.loginByToken(  serviceContent.getSessionManager(), null);/** Save the HTTP cookie.*/String cookie = cookieExtractor.getCookie();

恢复 vCenter 服务器会话 cookie

登录后，你必须恢复 vCenter 会话上下文。这部分是恢复默认消息处理器和会话 cookie 的代码片段。当默认处理器被 cookie 处理器代替，客户端通过调用请求上下文方法重置会话 cookie 来直接访问上下文字段。
下面描述了这些步骤，并展示了相应的对象和方法：

1. 恢复默认消息处理器。该处理器用于 LoginByToken 不用于后续 vSphere API 的调用；

2. 获取 VIM 端口；

3. 在 HTTP 请求上下文设置连接端点；

4. 设置 HTTP 请求头（vCenter 会话 cookie）。

下面示例展示了恢复 vCenter 会话的 Java 代码，这里的代码需要 vCenter URL 、cookie 及在登录前获取的默认处理器。

Example: 恢复 vCenter 服务器会话

/** Reset the default handler. This overwrites the existing handlers, effectively removing them.*/vimService.setHandlerResolver(defaultHandler);vimPort = vimService.getVimPort();/** Restore the connection endpoint in the request context.*/// Set the validated session cookie and set it in the header for once,// JAXWS will maintain that cookie for all the subsequent requestsMap<String, Object> ctxt = ((BindingProvider) vimPort)  .getRequestContext();ctxt.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, vcServerUrl);ctxt.put(BindingProvider.SESSION_MAINTAIN_PROPERTY, true);/** Reset the cookie in the request context.*/Map<String, List<String>> headers = (Map<String, List<String>>) ctxt.get(MessageContext.HTTP_REQUEST_HEADERS);if (headers == null) {headers = new HashMap<String, List<String>>();}headers.put("Cookie", Arrays.asList(cookie));ctxt.put(MessageContext.HTTP_REQUEST_HEADERS, headers);

---

原文：
VMware vSphere 6.5 Documentation Center：Client Applications