# Managed Object - GuestAliasManager(vim.vm.guest.AliasManager)

Property of
  GuestOperationsManager
See also
  GuestAliases, GuestAuthAliasInfo, GuestAuthentication, GuestAuthSubject, GuestMappedAliases, VirtualMachine
Since
  vSphere API 6.0

## Managed Object Description

The GuestAliasManager supports single sign-on for virtual machine access to perform guest operations. The GuestAliasManager provides methods to create and access aliases.

A guest alias defines an association between a guest user account on a virtual machine and an external vSphere user account. The vSphere account is represented by credentials consisting of an X.509 certificate and a subject name. The certificate and subject name are encoded in SAML tokens that are provided by the VMware SSO Server. The SAML tokens are attached to guest operation requests. If the credentials in a SAML token match an alias that is defined for a virtual machine, the ESXi Server guest components grant access for execution of the guest operation in the context of the user account on the virtual machine.

To create a guest alias, use the AddGuestAlias method. AddGuestAlias establishes the association between a guest user account, certificate, and SAML token subject.

- The username parameter identifies the guest account.
- The base64Cert parameter specifies the X.509 certificate.
- The aliasInfo parameter identifies the SAML token subject (GuestAuthAliasInfo. subject. name).

If there are no aliases defined for a virtual machine, the ESXi Server will perform standard authentication using the credentials associated with a guest operation request. If one or more aliases are defined for a virtual machine, any guest operation request that uses SAML token authentication SAMLTokenAuthentication must specify a token that corresponds to one of the defined aliases.

After defining one or more guest aliases, you can specify SAMLTokenAuthentication for the auth parameter to guest operation methods:

- GuestProcessManager methods
- GuestFileManager methods
- GuestWindowsRegistryManager methods

For information about obtaining a SAML token from a VMware SSO Server, see VMware Single Sign-On Programming Guide.

You can define multiple aliases for a guest account. You can also map the credentials to an alias by setting mapCert to "true" in the call to the AddGuestAlias method. When an alias has a mapped credential, requests using that alias do not need to identify the guest account.

Properties

Name | Type | Description
--- | --- | ---
None

Methods

Methods defined in this Managed Object
AddGuestAlias, ListGuestAliases, ListGuestMappedAliases, RemoveGuestAlias, RemoveGuestAliasByCert

# AddGuestAlias(addAlias)

Defines an alias for a guest acount in a virtual machine. After the alias is defined, the ESXi Server will use the alias to authenticate guest operations requests.

This will add the given VMware SSO Server's certificate and a subject to the alias store of the specified user in the guest.

In order to add an alias to the guest, you must supply an existing valid credential. This can be any instance of GuestAuthentication, but must be valid for the specified guest username.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the GuestAliasManager used to make the method call.
vm P | ManagedObjectReference to a VirtualMachine | Virtual machine to perform the operation on.
auth | GuestAuthentication | The guest authentication data for this operation. See GuestAuthentication. These credentials must satisfy authentication requirements for a guest account on the specified virtual machine.
username | xsd:string | Username for the guest account on the virtual machine.
mapCert | xsd:boolean | Indicates whether the certificate associated with the alias should be mapped. If an alias certificate is mapped, guest operation requests that use that alias do not have to specify the guest account username in the SAMLTokenAuthentication object. If mapCert is false, the request must specify the username.
base64Cert | xsd:string | X.509 certificate from the VMware SSO Server, in base64 encoded DER format. The ESXi Server uses this certificate to authenticate guest operation requests.
aliasInfo | GuestAuthAliasInfo | Specifies the subject name for authentication. The subject name (when present) corresponds to the value of the Subject element in SAML tokens. The ESXi Server uses the subject name to authenticate guest operation requests.

P Required privilege: VirtualMachine.GuestOperations.ModifyAliases

Return Value

Type | Description
--- | ---
None

Faults

Type | Description
--- | ---
GuestComponentsOutOfDate | Thrown if the guest agent is too old to support the operation.
GuestMultipleMappings | Thrown if the operation fails because mapCert is set and the certificate already exists in the mapping file for a different user.
GuestOperationsFault | Thrown if there is an error processing a guest operation.
GuestOperationsUnavailable | Thrown if the VM agent for guest operations is not running.
GuestPermissionDenied | Thrown if there are insufficient permissions in the guest OS.
InvalidArgument | Thrown if the operation fails because the certificate is invalid.
InvalidGuestLogin | Thrown if the the guest authentication information was not accepted.
InvalidPowerState | Thrown if the VM is not powered on.
InvalidState | Thrown if the operation cannot be performed because of the virtual machine's current state.
OperationDisabledByGuest | Thrown if the operation is not enabled due to guest agent configuration.
OperationNotSupportedByGuest | Thrown if the operation is not supported by the guest OS.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress | Thrown if the virtual machine is busy.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="AddGuestAlias" type="vim25:AddGuestAliasRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="AddGuestAliasResponse"> <complexType/> </element>

# ListGuestAliases(listAliases)

Lists the GuestAliases for a specified user in the guest that can be used for authentication of guest operations.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the GuestAliasManager used to make the method call.
vm P | ManagedObjectReference to a VirtualMachine | Virtual machine to perform the operation on.
auth | GuestAuthentication | The guest authentication data for this operation. See GuestAuthentication. These credentials must satisfy authentication requirements for a guest account on the specified virtual machine.
username | xsd:string | The guest user whose Alias store is being queried.

P Required privilege: VirtualMachine.GuestOperations.QueryAliases

Return Value

Type | Description
--- | ---
GuestAliases[] |

Faults

Type | Description
--- | ---
GuestComponentsOutOfDate | Thrown if the guest agent is too old to support the operation.
GuestOperationsFault | Thrown if there is an error processing a guest operation.
GuestOperationsUnavailable | Thrown if the agent for guest operations is not running.
GuestPermissionDenied | Thrown if there are insufficient permissions in the guest OS.
InvalidGuestLogin | Thrown if the the guest authentication information was not accepted.
InvalidPowerState | Thrown if the VM is not powered on.
InvalidState | Thrown if the operation cannot be performed because of the virtual machine's current state.
OperationDisabledByGuest | Thrown if the operation is not enabled due to guest agent configuration.
OperationNotSupportedByGuest | Thrown if the operation is not supported by the guest OS.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress | Thrown if the virtual machine is busy.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ListGuestAliases" type="vim25:ListGuestAliasesRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ListGuestAliasesResponse"> <complexType> <sequence> <element name="returnval" type="vim25:GuestAliases" minOccurs="0" maxOccurs="unbounded"/> </sequence> </complexType> </element>

# ListGuestMappedAliases(listMappedAliases)

Lists the GuestMappedAliases in the guest that can be used for authentication of guest operations.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the GuestAliasManager used to make the method call.
vm P | ManagedObjectReference to a VirtualMachine | Virtual machine to perform the operation on.
auth | GuestAuthentication | The guest authentication data for this operation. See GuestAuthentication. These credentials must satisfy authentication requirements for a guest account on the specified virtual machine.

P Required privilege: VirtualMachine.GuestOperations.QueryAliases

Return Value

Type | Description
--- | ---
GuestMappedAliases[] |

Faults

Type | Description
--- | ---
GuestComponentsOutOfDate | Thrown if the guest agent is too old to support the operation.
GuestOperationsFault | Thrown if there is an error processing a guest operation.
GuestOperationsUnavailable | Thrown if the VM agent for guest operations is not running.
GuestPermissionDenied | Thrown if there are insufficient permissions in the guest OS.
InvalidGuestLogin | Thrown if the the guest authentication information was not accepted.
InvalidPowerState | Thrown if the VM is not powered on.
InvalidState | Thrown if the operation cannot be performed because of the virtual machine's current state.
OperationDisabledByGuest | Thrown if the operation is not enabled due to guest agent configuration.
OperationNotSupportedByGuest | Thrown if the operation is not supported by the guest OS.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress | Thrown if the virtual machine is busy.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ListGuestMappedAliases" type="vim25:ListGuestMappedAliasesRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ListGuestMappedAliasesResponse"> <complexType> <sequence> <element name="returnval" type="vim25:GuestMappedAliases" minOccurs="0" maxOccurs="unbounded"/> </sequence> </complexType> </element>

# RemoveGuestAlias(removeAlias)

Removes an alias from the guest so it can no longer be used for authentication of guest operations. It will also be removed from the mapped credentials.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the GuestAliasManager used to make the method call.
vm P | ManagedObjectReference to a VirtualMachine | Virtual machine to perform the operation on.
auth | GuestAuthentication | The guest authentication data for this operation. See GuestAuthentication. These credentials must satisfy authentication requirements for a guest account on the specified virtual machine.
username | xsd:string | Username for the guest account on the virtual machine.
base64Cert | xsd:string | The X.509 certificate associated with the alias to be removed, in base64 encoded DER format.
subject | GuestAuthSubject | The subject of the alias.

P Required privilege: VirtualMachine.GuestOperations.ModifyAliases

Return Value

Type | Description
--- | ---
None

Faults

Type | Description
--- | ---
GuestComponentsOutOfDate | Thrown if the guest agent is too old to support the operation.
GuestOperationsFault | Thrown if there is an error processing a guest operation.
GuestOperationsUnavailable | Thrown if the VM agent for guest operations is not running.
GuestPermissionDenied | Thrown if there are insufficient permissions in the guest OS.
InvalidArgument | Thrown if the operation fails because the certificate is invalid.
InvalidGuestLogin | Thrown if the the guest authentication information was not accepted.
InvalidPowerState | Thrown if the VM is not powered on.
InvalidState | Thrown if the operation cannot be performed because of the virtual machine's current state.
OperationDisabledByGuest | Thrown if the operation is not enabled due to guest agent configuration.
OperationNotSupportedByGuest | Thrown if the operation is not supported by the guest OS.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress | Thrown if the virtual machine is busy.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RemoveGuestAlias" type="vim25:RemoveGuestAliasRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RemoveGuestAliasResponse"> <complexType/> </element>

# RemoveGuestAliasByCert(removeAliasByCert)

Removes a VMware SSO Server's certificate and all associated aliases from the guest so it can no longer be used for authentication of guest operations. It will also be removed from the global certificate-to-user mapping file in the guest.

Required Privileges
  None

Parameters

Name | Type | Description
--- | --- | ---
_this | ManagedObjectReference | A reference to the GuestAliasManager used to make the method call.
vm P | ManagedObjectReference to a VirtualMachine | Virtual machine to perform the operation on.
auth | GuestAuthentication | The guest authentication data for this operation. See GuestAuthentication. These credentials must satisfy authentication requirements for a guest account on the specified virtual machine.
username | xsd:string | Username for the guest account on the virtual machine.
base64Cert | xsd:string | The X.509 certificate to be removed, in base64 encoded DER format.

P Required privilege: VirtualMachine.GuestOperations.ModifyAliases

Return Value

Type | Description
--- | ---
None

Faults

Type | Description
--- | ---
GuestComponentsOutOfDate | Thrown if the guest agent is too old to support the operation.
GuestOperationsFault | Thrown if there is an error processing a guest operation.
GuestOperationsUnavailable | Thrown if the VM agent for guest operations is not running.
GuestPermissionDenied | Thrown if there are insufficient permissions in the guest OS.
InvalidArgument | Thrown if the operation fails because the certificate is invalid.
InvalidGuestLogin | Thrown if the the guest authentication information was not accepted.
InvalidPowerState | Thrown if the VM is not powered on.
InvalidState | Thrown if the operation cannot be performed because of the virtual machine's current state.
OperationDisabledByGuest | Thrown if the operation is not enabled due to guest agent configuration.
OperationNotSupportedByGuest | Thrown if the operation is not supported by the guest OS.
RuntimeFault | Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.
TaskInProgress | Thrown if the virtual machine is busy.

Events

Type
None

Show WSDL type definition
<element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RemoveGuestAliasByCert" type="vim25:RemoveGuestAliasByCertRequestType"/> <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RemoveGuestAliasByCertResponse"> <complexType/> </element>