vCenter Server Single Sign On Session

After you obtain a SAML token from the vCenter Single Sign On Server, you can use the vSphere API method LoginByToken to establish a single sign on session with a vCenter Server. See vCenter Single Sign On Client Example for an example of obtaining a vCenter Single Sign On token.

At the beginning of a vCenter Single Sign On session, your client is responsible for the following tasks:

■

Maintain the vCenter session cookie. The vSphere architecture uses an HTTP cookie to support a persistent connection between a vSphere client and a vCenter Server. During the initial connection, the Server produces a session cookie. Operations during the login sequence will reset the request context so your client must save this cookie and re-introduce it at the appropriate times.

■	Insert the vCenter Single Sign On token and a timestamp into the SOAP header of the LoginByToken message.

The example program uses these general steps:

1	Call the RetrieveServiceContent method to establish an HTTP connection with the vCenter Server and save the HTTP session cookie. The client uses an HTTP header handler method to extract the cookie from the vCenter Server response.

2

Call the LoginByToken method to authenticate the vCenter session. To send the token to the vCenter Server, the client uses a handler to embed the token and a time stamp in the SOAP header for the message. To identify the session started with the RetrieveServiceContent method, the client uses a handler to embed the session cookie in the HTTP header.

3	Restore the session cookie.

HTTP and SOAP Header Handlers

To use a vCenter Single Sign On token to login to a vCenter Server, the example uses header handlers to manipulates the HTTP and SOAP header elements of the login request. After establishing a handler, subsequent requests automatically invoke the handler.

■	An extraction handler obtains the HTTP session cookie provided by the vCenter Server. After setting up the handler, a call to the RetrieveServiceContent method will invoke the handler to extract the cookie from the Server response.

■	Insertion handlers put the vCenter Single Sign On token and a timestamp into the SOAP header and the session cookie into the HTTP header of the login request.

The following figure shows the use of handlers to manipulate header elements when establishing a vCenter Single Sign On session with a vCenter Server.

Starting a vCenter Session

 

Important Every call to the vCenter Server will invoke any message handlers that have been established. The overhead involved in using the SOAP and HTTP message handlers is not necessary after the session has been established. The example saves the default message handler before setting up the SOAP and HTTP handlers. After establishing the session, the example will reset the handler chain and restore the default handler. The example code also uses multiple calls to the VimPortType.getVimPort method to manage the request context. The getVimPort method clears the HTTP request context. After each call to the getVimPort method, the client resets the request context endpoint address to the vCenter Server URL. After the client has obtained the session cookie, it will restore the cookie in subsequent requests.

Sample Code

The code examples in the following sections show how to use the LoginByToken method with a holder-of-key security token. The code examples are based on the sample code contained in the vCenter Single Sign On SDK. The files are located in the Java samples directory (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 header handlers. These are the same handlers that are used in vCenter LoginByToken Example. The SOAP handler files are located in the vCenter Single Sign On client soaphandlers directory:

samples/com/vmware/sso/client/soaphandlers