Managed Object - SessionManager

Property of: ServiceContent
See also: SessionManagerLocalTicket, UserSession

Managed Object Description

This managed object type includes methods for logging on and logging off clients, determining which clients are currently logged on, and forcing clients to log off.

Properties

Name	Type	Description
currentSession* P	UserSession	This property contains information about the client's current session. If the client is not logged on, the value is null.
defaultLocale P	xsd:string	This is the default server locale.
message* P	xsd:string	The system global message from the server.
messageLocaleList* P	xsd:string[]	Provides the list of locales for which the server has localized messages.
sessionList* P	UserSession[]	The list of currently active sessions.
supportedLocaleList* P	xsd:string[]	Provides the list of locales that the server supports. Listing a locale ensures that some standardized information such as dates appear in the appropriate format. Other localized information, such as error messages, are displayed, if available. If localized information is not available, the message is returned using the system locale.

*May not be presentPRequired privilege - see tooltip for details

Methods

Methods defined in this Managed Object
AcquireLocalTicket, ImpersonateUser, Login, LoginBySSPI, Logout, SessionIsActive, SetLocale, TerminateSession, UpdateServiceMessage

AcquireLocalTicket

Acquires a one-time ticket for mutual authentication between a server and client.

The caller of this operation can use the user name and file content of the returned object as the userName and password arguments for login operation. The local ticket that is returned becomes invalid either after it is used or after a server-determined ticket expiration time passes. This operation can be used by servers and clients to avoid re-entering user credentials after authentication by the operating system has already happened.

For example, service console utilities that connect to a host agent should not require users to re-enter their passwords every time the utilities run. Since the one-time password file is readable only by the given user, the identity of the one-time password user is protected by the operating system file permission.

Only local clients are allowed to call this operation. Remote clients receive an InvalidRequest fault upon calling this operation.

Required Privileges: System.Anonymous

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the SessionManager used to make the method call.
userName	xsd:string	User requesting one-time password.

Return Value

Type	Description
SessionManagerLocalTicket	LocalTicket object containing userName and path to file containing one-time password for use in login operation.

Faults

Type	Description
InvalidLogin	Thrown if the userName is invalid.
NoPermission	Thrown if the user and password are valid, but the user has no access granted.
NotSupported	Thrown if the server does not support this operation.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="AcquireLocalTicket" type="vim25:AcquireLocalTicketRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="AcquireLocalTicketResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:SessionManagerLocalTicket"/>
               </sequence>
            </complexType>
         </element>

ImpersonateUser

Converts current session to impersonate the specified user. The current session will take on the identity and authorization level of the user. That user must have a currently-active session.

Required Privileges: Sessions.ImpersonateUser
Since: VI API 2.5

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the SessionManager used to make the method call.

userName

xsd:string

The user to impersonate.

locale*

xsd:string

A two-character ISO-639 language ID (like "en") optionally followed by an underscore and a two-character ISO 3166 country ID (like "US").

Examples are "de", "fr_CA", "zh", "zh_CN", and "zh_TW". Note: The method uses the server default locale when a locale is not provided. This default can be configured in the server configuration file. If unspecified, it defaults to the locale of the server environment or English ("en") if unsupported.

*Need not be set

Return Value

Type	Description
UserSession

Faults

Type	Description
InvalidLocale
InvalidLogin
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ImpersonateUser" type="vim25:ImpersonateUserRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ImpersonateUserResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:UserSession"/>
               </sequence>
            </complexType>
         </element>

Login

Log on to the server. This method fails if the user name and password are incorrect, or if the user is valid but has no permissions granted.

Required Privileges: System.Anonymous

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the SessionManager used to make the method call.
userName	xsd:string	The ID of the user who is logging on to the server.
password	xsd:string	The password of the user who is logging on to the server.
locale*	xsd:string	A two-character ISO-639 language ID (like "en") optionally followed by an underscore and a two-character ISO 3166 country ID (like "US"). Examples are "de", "fr_CA", "zh", "zh_CN", and "zh_TW". Note: The method uses the server default locale when a locale is not provided. This default can be configured in the server configuration file. If unspecified, it defaults to the locale of the server environment or English ("en") if unsupported.

*Need not be set

Return Value

Type	Description
UserSession	The UserSession object.

Faults

Type	Description
InvalidLocale	Thrown if the locale is invalid or unknown to the server.
InvalidLogin	Thrown if the user and password combination is invalid.
NoPermission	Thrown if the user is valid, but has no access granted.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="Login" type="vim25:LoginRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="LoginResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:UserSession"/>
               </sequence>
            </complexType>
         </element>

LoginBySSPI

NOTE: This method is experimental and subject to change in future releases.

Log on to the server using SSPI pass-through authentication.

This method provides support for passing credentials of the calling process to the server without using a password, by leveraging the Windows Security Support Provider Interface (SSPI) library.

If the function is not supported, this throws a NotSupported fault.

The client first calls AcquireCredentialsHandle(). If Kerberos is used, this should include the desired credential to pass. The client then calls InitializeSecurityContext(). The resulting partially-formed context is passed in Base-64 encoded form to this method.

If the context has been successfully formed, the server proceeds with login and behaves like vim.SessionManager.login. If further negotiation is needed, the server throws an SSPIChallenge fault with a challenge token, which the client should again pass to InitializeSecurityContext(), followed by calling this method again.

For more information, see the MSDN documentation on SSPI.

Required Privileges: System.Anonymous
Since: VI API 2.5

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the SessionManager used to make the method call.

base64Token

xsd:string

The partially formed context returned from InitializeSecurityContext().

locale*

xsd:string

A two-character ISO-639 language ID (like "en") optionally followed by an underscore and a two-character ISO 3166 country ID (like "US").

*Need not be set

Return Value

Type	Description
UserSession	The UserSession object.

Faults

Type	Description
InvalidLocale	Thrown if the locale is invalid or unknown to the server.
InvalidLogin	Thrown if the user context could not be passed successfully, or the context is not valid on the server.
NoPermission	Thrown if the user is valid, but has no access granted.
NotSupported	Thrown if the service does not support SSPI authentication.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
SSPIChallenge	Thrown if further negotiation is required.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="LoginBySSPI" type="vim25:LoginBySSPIRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="LoginBySSPIResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:UserSession"/>
               </sequence>
            </complexType>
         </element>

Logout

Log out and terminate the current session.

Required Privileges: System.View

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the SessionManager used to make the method call.

Return Value

Type	Description
None

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="Logout" type="vim25:LogoutRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="LogoutResponse">
            <complexType/>
         </element>

SessionIsActive

Validates that a currently-active session exists with the specified sessionID and userName associated with it. Returns true if session exists.

Required Privileges: Sessions.ValidateSession
Since: VI API 2.5

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the SessionManager used to make the method call.
sessionID	xsd:string	Session ID to validate.
userName	xsd:string	User name to validate.

Return Value

Type	Description
xsd:boolean

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="SessionIsActive" type="vim25:SessionIsActiveRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="SessionIsActiveResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="xsd:boolean"/>
               </sequence>
            </complexType>
         </element>

SetLocale

Sets the session locale.

Required Privileges: System.View

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the SessionManager used to make the method call.

locale

xsd:string

A two-character ISO-639 language ID (like "en") optionally followed by an underscore and a two-character ISO 3166 country ID (like "US").

Return Value

Type	Description
None

Faults

Type	Description
InvalidLocale	Thrown if the locale is invalid or unknown to the server.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="SetLocale" type="vim25:SetLocaleRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="SetLocaleResponse">
            <complexType/>
         </element>

TerminateSession

Log off and terminate the provided list of sessions.

This method is only transactional for each session ID. The set of sessions are terminated sequentially, as specified in the list. If a failure occurs, for example, because of an unknown sessionID, the method aborts with an exception. When the method aborts, any sessions that have not yet been terminated are left in their unterminated state.

Required Privileges: Sessions.TerminateSession

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the SessionManager used to make the method call.
sessionId	xsd:string[]	A list of sessions to terminate.

Return Value

Type	Description
None

Faults

Type	Description
InvalidArgument	Thrown if a sessionId matches the current session. Use the logout method to terminate the current session.
NotFound	Thrown if a sessionId could not be found as a valid logged-on session.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="TerminateSession" type="vim25:TerminateSessionRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="TerminateSessionResponse">
            <complexType/>
         </element>

UpdateServiceMessage

Updates the system global message. If not blank, the message is immediately displayed to currently logged-on users. When set, the message is shown by new clients upon logging in.

Required Privileges: Sessions.GlobalMessage

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the SessionManager used to make the method call.
message	xsd:string	The message to send. Newline characters may be included.

Return Value

Type	Description
None

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateServiceMessage" type="vim25:UpdateServiceMessageRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateServiceMessageResponse">
            <complexType/>
         </element>