Scripting Object - VcSessionManager

Scripting-object corresponding to
SessionManager
Attribute of
VcSdkConnection, VcServiceContent

Scripting 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.

Attributes

Name Type Description
currentSessionVcUserSession

@since VI API 2.5
defaultLocaleString

@since VI API 2.5
idString

@since Unknown
messageString

@since VI API 2.5
messageLocaleListString []

@since VI API 2.5
morefVcManagedObjectReference

returns the ManagedObjectReference of this ManagedObject @since Unknown
sdkConnectionVcSdkConnection

@since Unknown
sdkIdString

@since Unknown
sessionListVcUserSession []

@since VI API 2.5
supportedLocaleListString []

@since VI API 2.5
typeStringDeprecated.

Returns the name for the this managed object's vim type @since Unknown
vimHostVcSdkConnection

@since Unknown
vimIdString

@since Unknown
vimTypeString

@since Unknown

Methods

Methods defined in this Scripting Object
_getRef, acquireCloneTicket, acquireGenericServiceTicket, acquireLocalTicket, acquireSessionTicket, cloneSession, createTrigger, impersonateUser, login, loginBySessionTicket, loginBySSLThumbprint, loginBySSPI, loginByToken, loginExtensionByCertificate, loginExtensionBySubjectName, logout, sessionIsActive, setLocale, terminateSession, updateServiceMessage

setLocale

Sets the session locale. @since VI API 2.5

Parameters

NameTypeDescription
arg0String


Return Value

Type Description
None

_getRef

@since Unknown

Parameters

NameTypeDescription
None

Return Value

Type Description
VcManagedObjectReference

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. @since VI API 2.5

Parameters

NameTypeDescription
arg0String

arg1String

arg2String


Return Value

Type Description
VcUserSession

loginBySSLThumbprint

Creates a special privileged session for secure host to host communication within a cluster. Requires that the client connects using SSL, with a certificate whose SSL thumbprint is in the list of thumbprints supplied by Virtual Center. @since vSphere API 4.0

Parameters

NameTypeDescription
arg0String


Return Value

Type Description
VcUserSession

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. @since VI API 2.5

Parameters

NameTypeDescription
arg0String


Return Value

Type Description
None

loginExtensionBySubjectName

Creates a special privileged session that includes the Sessions.ImpersonateUser privilege. Requires that the extension connected using SSL, with a certificate that has a subject name that matches the subject name registered for the extension.

As of vSphere API 4.0, the NotFound fault is no longer thrown. Instead, InvalidLogin is thrown if the specified extension is not registered. @since VI API 2.5

Parameters

NameTypeDescription
arg0String

arg1String


Return Value

Type Description
VcUserSession

acquireGenericServiceTicket

Creates and returns a one-time credential that may be used to make the specified request. @since vSphere API 5.0

Parameters

NameTypeDescription
arg0VcSessionManagerServiceRequestSpec


Return Value

Type Description
VcSessionManagerGenericServiceTicket

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. @since VI API 2.5

Parameters

NameTypeDescription
arg0String


Return Value

Type Description
VcSessionManagerLocalTicket

sessionIsActive

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

Parameters

NameTypeDescription
arg0String

arg1String


Return Value

Type Description
Boolean

loginBySessionTicket

Log on to the server based on a ticket generated by the {@link SessionManager#acquireSessionTicket} method. If successful, the session will have the same credentials and locale as the session from which the ticket was generated. @since vSphere API 4.0

Parameters

NameTypeDescription
arg0String


Return Value

Type Description
VcUserSession

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. @since VI API 2.5

Parameters

NameTypeDescription
arg0String []


Return Value

Type Description
None

loginExtensionByCertificate

Creates a special privileged session that includes the Sessions.ImpersonateUser privilege. Requires that the client connect over SSL and provide an X.509 certificate for which they hold the private key. The certificate must match the certificate used in an earlier call to {@link vim.ExtensionManager#setCertificate}.

NOTE: Verification of the received certificate (such as expiry, revocation, and trust chain) is not required for successful authentication using this method. If certificate verification is desired, use the {@link vim.SessionManager#loginExtensionBySubjectName} method instead. @since vSphere API 4.0

Parameters

NameTypeDescription
arg0String

arg1String


Return Value

Type Description
VcUserSession

logout

Log out and terminate the current session. @since VI API 2.5

Parameters

NameTypeDescription
None

Return Value

Type Description
None

acquireCloneTicket

Acquire a session-specific ticket string which can be used to clone the current session. The caller of this operation can pass the ticket value to another entity on the client. The recipient can then call {@link #cloneSession} with the ticket string on an unauthenticated session and avoid having to re-enter credentials.

The ticket may only be used once and becomes invalid after use. The ticket is also invalidated when the corresponding session is closed or expires. The ticket is only valid on the server which issued it.

This sequence of operations is conceptually similar to the functionality provided by {@link #acquireLocalTicket}, however the methods can be used by remote clients and do not require a shared filesystem for transport. @since VI API 2.5u2

Parameters

NameTypeDescription
None

Return Value

Type Description
String

loginByToken

Log on to the server through token representing principal identity. The token is obtained from SSO (single sign-on) service. This method fails if the token is not valid, or the principal has no permissions granted. Two type of sso tokens are supported by this method: Bearer and Holder-of-Key (HoK). If the token type obliges the method caller to prove his rights to present this token (HoK), then a signature is supplied as well. The token and the security signature if available are provided in a transport specific way.

If the communication with the VirtualCenter is SOAP based read the WS-Security specification (SAML Token profile) to understand how to transport the SSO token and signature.

Usual login scenario:

  1. Acquire HoK token from the SSO service. Different authentication mechanisms are available for acquiring token (user/password, certificate, SSPI and so on). For more details consult the SSO documentation. To find the location of your SSO service consult the Virtual Infrastructure documentation.
  2. Once SSO token is acquired successfully {@link #loginByToken} could be invoked.
@since vSphere API 5.1

Parameters

NameTypeDescription
arg0String


Return Value

Type Description
VcUserSession

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. If the given userName is an extension key and this key does not overlap with a user name of any currently-active session, it will take on the identity and authorization level of that extension provided the current session has the same authorization level of that extension. @since VI API 2.5

Parameters

NameTypeDescription
arg0String

arg1String


Return Value

Type Description
VcUserSession

cloneSession

Clone the session specified by the clone ticket and associate it with the current connection. The current session will take on the identity and authorization level of the UserSession associated with the specified cloning ticket. @since VI API 2.5u2

Parameters

NameTypeDescription
arg0String


Return Value

Type Description
VcUserSession

createTrigger

@since Unknown

Parameters

NameTypeDescription
timeoutNumber

filterString

conditionString

filterToSyncString


Return Value

Type Description
Trigger

loginBySSPI

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 {@link 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. @since VI API 2.5

Parameters

NameTypeDescription
arg0String

arg1String


Return Value

Type Description
VcUserSession

acquireSessionTicket

Generate a ticket for authenticating to a remote service, or for a reference to the current session.

This method may be called immediately after a call to {@link vim.SessionManager#login} or any other login method, even if the login fails with a {@link vim.fault.NoPermission} fault.

The resulting ticket is expected to be used immediately, and has a limited valid lifetime set by the server.

Clients should treat live tickets with the same sensitivity as a password. @since vSphere API 4.0

Parameters

NameTypeDescription
arg0String


Return Value

Type Description
String