Managed Object - HostActiveDirectoryAuthentication(vim.host.ActiveDirectoryAuthentication)

Extends: HostDirectoryStore
Since: vSphere API 4.1

Managed Object Description

The HostActiveDirectoryAuthentication managed object indicates domain membership status and provides methods for adding a host to and removing a host from a domain.

Properties

Name	Type	Description
None
Properties inherited from HostDirectoryStore
None
Properties inherited from HostAuthenticationStore
info

Methods

Methods defined in this Managed Object
DisableSmartCardAuthentication, EnableSmartCardAuthentication, ImportCertificateForCAM_Task, InstallSmartCardTrustAnchor, JoinDomain_Task, JoinDomainWithCAM_Task, LeaveCurrentDomain_Task, ListSmartCardTrustAnchors, RemoveSmartCardTrustAnchor, RemoveSmartCardTrustAnchorByFingerprint, ReplaceSmartCardTrustAnchors
Methods inherited from HostDirectoryStore
None
Methods inherited from HostAuthenticationStore
None

DisableSmartCardAuthentication(disableSmartCardAuthentication)

Disables console authentication using a local smart card and reader.

Required Privileges: Host.Config.AuthenticationStore
Since: vSphere API 6.0

Parameters

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

Return Value

Type	Description
None

Faults

Type	Description
ActiveDirectoryFault	Thrown if the active directory client could not be reconfigured.
HostConfigFault	Thrown if the host configuration prevents smart card authentication from being disabled.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="DisableSmartCardAuthentication" type="vim25:DisableSmartCardAuthenticationRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="DisableSmartCardAuthenticationResponse">
            <complexType/>
         </element>

EnableSmartCardAuthentication(enableSmartCardAuthentication)

Enables console authentication using a local smart card and reader. To take effect this feature requires an active domain membership to a domain with users configured to authenticate using smart cards.

Required Privileges: Host.Config.AuthenticationStore
Since: vSphere API 6.0

Parameters

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

Return Value

Type	Description
None

Faults

Type	Description
ActiveDirectoryFault	Thrown if the active directory client could not be reconfigured.
HostConfigFault	Thrown if the host configuration prevents smart card authentication from being enabled.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="EnableSmartCardAuthentication" type="vim25:EnableSmartCardAuthenticationRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="EnableSmartCardAuthenticationResponse">
            <complexType/>
         </element>

ImportCertificateForCAM_Task(importCertificateForCAM)

Import the CAM server's certificate to the local store of vmwauth.

The certificate should have already been uploaded to ESXi file system.

Required Privileges: Host.Config.AuthenticationStore
Since: vSphere API 5.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostActiveDirectoryAuthentication used to make the method call.
certPath	xsd:string	full path of the certificate on ESXi
camServer	xsd:string	IP of server providing the CAM service.

Return Value

Type	Description
ManagedObjectReference to a Task

Faults

Type	Description
ActiveDirectoryFault	Thrown for any problem that is not handled with a more specific fault.
FileNotFound	Thrown if the certificate file does not exist
InvalidCAMServer	Thrown if camServer is not a valid IP address
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

InstallSmartCardTrustAnchor(installSmartCardTrustAnchor)

Install a trust anchor certificate for smart card authentication.

Required Privileges: Host.Config.AuthenticationStore
Since: vSphere API 6.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostActiveDirectoryAuthentication used to make the method call.
cert	xsd:string	SSL certificate in PEM format

Return Value

Type	Description
None

Faults

Type	Description
HostConfigFault	Thrown if the host configuration prevents the certificate from being installed.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="InstallSmartCardTrustAnchor" type="vim25:InstallSmartCardTrustAnchorRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="InstallSmartCardTrustAnchorResponse">
            <complexType/>
         </element>

JoinDomain_Task(joinDomain)

Adds the host to an Active Directory domain.

If the HostAuthenticationStoreInfo.enabled property is True (accessed through the info property), the host has joined a domain. The vSphere API will throw the InvalidState fault if you try to add a host to a domain when the host has already joined a domain.

Required Privileges: Host.Config.AuthenticationStore

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostActiveDirectoryAuthentication used to make the method call.
domainName	xsd:string	Name of the domain to be joined.
userName	xsd:string	Name for an Active Directory account that has the authority to add hosts to the domain.
password	xsd:string	Password for the `userName` account.

Return Value

Type	Description
ManagedObjectReference to a Task

Faults

Type	Description
ActiveDirectoryFault	Thrown for any problem that is not handled with a more specific fault.
BlockedByFirewall	Thrown if ports needed by the join operation are blocked by the firewall.
ClockSkew	Thrown if the clocks of the host and the domain controller differ by more than the allowed amount of time.
DomainNotFound	Thrown if the domain controller for `domainName` cannot be reached.
HostConfigFault	Thrown if the host configuration prevents the join operation from succeeding.
InvalidHostName	Thrown if the domain part of the host's FQDN doesn't match the domain being joined.
InvalidLogin	Thrown if `userName` and `password` are not valid user credentials.
InvalidState	Thrown if the host has already joined a domain.
NoPermissionOnAD	Thrown if `userName` has no right to add hosts to the domain.
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 HostActiveDirectoryAuthentication object is busy.

Events

Type
None

JoinDomainWithCAM_Task(joinDomainWithCAM)

Adds the host to an Active Directory domain through CAM service.

Required Privileges: Host.Config.AuthenticationStore
Since: vSphere API 5.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostActiveDirectoryAuthentication used to make the method call.
domainName	xsd:string	Name of the domain to be joined.
camServer	xsd:string	Name of server providing the CAM service.

Return Value

Type	Description
ManagedObjectReference to a Task

Faults

Type	Description
ActiveDirectoryFault	Thrown for any problem that is not handled with a more specific fault.
BlockedByFirewall	Thrown if ports needed by the join operation are blocked by the firewall.
CAMServerRefusedConnection	Thrown if the specified CAM server is not reachable, or if the server denied access.
ClockSkew	Thrown if the clocks of the host and the domain controller differ by more than the allowed amount of time.
DomainNotFound	Thrown if the domain controller for `domainName` cannot be reached.
HostConfigFault	Thrown if the host configuration prevents the join operation from succeeding.
InvalidCAMCertificate	Thrown if the certificate of the given CAM server cannot be verified.
InvalidCAMServer	Thrown if camServer is not a valid IP address, or if camServer is not accessible.
InvalidHostName	Thrown if the domain part of the host's FQDN doesn't match the domain being joined.
InvalidState	Thrown if the host has already joined a domain.
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 HostActiveDirectoryAuthentication object is busy.

Events

Type
None

LeaveCurrentDomain_Task(leaveCurrentDomain)

Removes the host from the Active Directory domain to which it belongs.

Required Privileges: Host.Config.AuthenticationStore

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostActiveDirectoryAuthentication used to make the method call.
force	xsd:boolean	If `True`, any existing permissions on managed entities for Active Directory users will be deleted. If `False` and such permissions exist, the operation will fail.

Return Value

Type	Description
ManagedObjectReference to a Task

Faults

Type	Description
ActiveDirectoryFault	Thrown for any problem that is not handled with a specific fault.
AuthMinimumAdminPermission	Thrown if this change would leave the system with no Administrator permission on the root node.
InvalidState	Thrown if the host is not in a domain or there are active permissions for Active Directory users.
NonADUserRequired	only non Active Directory users can initiate the leave domain operation.
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 ActiveDirectoryAuthentication object is busy.

Events

Type
None

ListSmartCardTrustAnchors(listSmartCardTrustAnchors)

Lists installed trust anchor certificates for smart card authentication.

Required Privileges: Host.Config.AuthenticationStore
Since: vSphere API 6.0

Parameters

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

Return Value

Type	Description
xsd:string[]	SSL certificates of trusted CAs in PEM format.

Faults

Type	Description
HostConfigFault	Thrown if the host configuration prevents the certificates from being listed.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ListSmartCardTrustAnchors" type="vim25:ListSmartCardTrustAnchorsRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ListSmartCardTrustAnchorsResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

RemoveSmartCardTrustAnchor(removeSmartCardTrustAnchor)

Deprecated. Please remove by fingerprint/digest instead.

Remove a smart card trust anchor certificate from the system.

Required Privileges: Host.Config.AuthenticationStore
Since: vSphere API 6.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostActiveDirectoryAuthentication used to make the method call.
issuer	xsd:string	Certificate issuer
serial	xsd:string	Certificate serial number (decimal integer)

Return Value

Type	Description
None

Faults

Type	Description
HostConfigFault	Thrown if the host configuration prevents the certificate from being removed.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RemoveSmartCardTrustAnchor" type="vim25:RemoveSmartCardTrustAnchorRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RemoveSmartCardTrustAnchorResponse">
            <complexType/>
         </element>

RemoveSmartCardTrustAnchorByFingerprint(removeSmartCardTrustAnchorByFingerprint)

Remove a smart card trust anchor certificate from the system by fingerprint.

Required Privileges: Host.Config.AuthenticationStore
Since: vSphere API 6.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostActiveDirectoryAuthentication used to make the method call.
fingerprint	xsd:string	Certificate fingerprint
digest	xsd:string	Digest function used to compute fingerprint. One of HostActiveDirectoryAuthenticationCertificateDigest.

Return Value

Type	Description
None

Faults

Type	Description
HostConfigFault	Thrown if the host configuration prevents the certificate from being removed.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RemoveSmartCardTrustAnchorByFingerprint" type="vim25:RemoveSmartCardTrustAnchorByFingerprintRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RemoveSmartCardTrustAnchorByFingerprintResponse">
            <complexType/>
         </element>

ReplaceSmartCardTrustAnchors(replaceSmartCardTrustAnchors)

Replace the trust anchor certificates for smart card authentication.

Required Privileges: Host.Config.AuthenticationStore
Since: vSphere API 6.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the HostActiveDirectoryAuthentication used to make the method call.
certs*	xsd:string[]	List of trusted CA certificates in PEM format. If empty then all existing trust anchors are removed.

*Need not be set

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.

Events

Type
None

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ReplaceSmartCardTrustAnchors" type="vim25:ReplaceSmartCardTrustAnchorsRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ReplaceSmartCardTrustAnchorsResponse">
            <complexType/>
         </element>