| 1 | <?xml version='1.0' encoding='UTF-8'?>
|
|---|
| 2 | <!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
|
|---|
| 3 | <topic xml:lang="en-us" id="vbox-auth">
|
|---|
| 4 | <title>RDP Authentication</title>
|
|---|
| 5 |
|
|---|
| 6 | <body>
|
|---|
| 7 | <p>For each virtual machine that is remotely accessible using RDP, you can individually determine if and how client
|
|---|
| 8 | connections are authenticated. For this, use the <userinput>VBoxManage modifyvm</userinput> command with the
|
|---|
| 9 | <codeph>--vrde-auth-type</codeph> option. See <xref href="vboxmanage-modifyvm.dita">VBoxManage modifyvm</xref>.
|
|---|
| 10 | The following methods of authentication are available: </p>
|
|---|
| 11 | <ul>
|
|---|
| 12 | <li>
|
|---|
| 13 | <p>The <b outputclass="bold">null</b> method means that there is no authentication at all. Any client can
|
|---|
| 14 | connect to the VRDP server and thus the virtual machine. This is very insecure and only to be recommended for
|
|---|
| 15 | private networks. </p>
|
|---|
| 16 | </li>
|
|---|
| 17 | <li>
|
|---|
| 18 | <p>The <b outputclass="bold">external</b> method provides external authentication through a special
|
|---|
| 19 | authentication library. <ph conkeyref="vbox-conkeyref-phrases/product-name"/> ships with two special
|
|---|
| 20 | authentication libraries: </p>
|
|---|
| 21 | <ol>
|
|---|
| 22 | <li>
|
|---|
| 23 | <p>The default authentication library, <userinput>VBoxAuth</userinput>, authenticates against user
|
|---|
| 24 | credentials of the hosts. Depending on the host platform, this means the following: </p>
|
|---|
| 25 | <ul>
|
|---|
| 26 | <li>
|
|---|
| 27 | <p>On Linux hosts, <userinput>VBoxAuth.so</userinput> authenticates users against the host's PAM system. </p>
|
|---|
| 28 | </li>
|
|---|
| 29 | <li>
|
|---|
| 30 | <p>On Windows hosts, <userinput>VBoxAuth.dll</userinput> authenticates users against the host's WinLogon
|
|---|
| 31 | system. </p>
|
|---|
| 32 | </li>
|
|---|
| 33 | <li>
|
|---|
| 34 | <p>On macOS hosts, <userinput>VBoxAuth.dylib</userinput> authenticates users against the host's
|
|---|
| 35 | directory service. </p>
|
|---|
| 36 | </li>
|
|---|
| 37 | </ul>
|
|---|
| 38 | <p>In other words, the external method by default performs authentication with the user accounts that exist
|
|---|
| 39 | on the host system. Any user with valid authentication credentials is accepted. For example, the username
|
|---|
| 40 | does not have to correspond to the user running the VM. </p>
|
|---|
| 41 | </li>
|
|---|
| 42 | <li>
|
|---|
| 43 | <p>An additional library called <userinput>VBoxAuthSimple</userinput> performs authentication against
|
|---|
| 44 | credentials configured in the <codeph>extradata</codeph> section of a virtual machine's XML settings file.
|
|---|
| 45 | This is probably the simplest way to get authentication that does not depend on a running and supported
|
|---|
| 46 | guest. The following steps are required: </p>
|
|---|
| 47 | <ol>
|
|---|
| 48 | <li>
|
|---|
| 49 | <p>Enable <userinput>VBoxAuthSimple</userinput> with the following command: </p>
|
|---|
| 50 | <pre xml:space="preserve">VBoxManage setproperty vrdeauthlibrary "VBoxAuthSimple"</pre>
|
|---|
| 51 | </li>
|
|---|
| 52 | <li>
|
|---|
| 53 | <p>To enable the library for a particular VM, you must switch authentication to external, as follows: </p>
|
|---|
| 54 | <pre xml:space="preserve">VBoxManage modifyvm <varname>VM-name</varname> --vrde-auth-type external</pre>
|
|---|
| 55 | <p>Replace <varname>VM-name</varname> with the VM name or UUID. </p>
|
|---|
| 56 | </li>
|
|---|
| 57 | <li>
|
|---|
| 58 | <p>You then need to configure users and passwords by writing items into the machine's extradata. Since
|
|---|
| 59 | the XML machine settings file, into whose <codeph>extradata</codeph> section the password needs to be
|
|---|
| 60 | written, is a plain text file, <ph conkeyref="vbox-conkeyref-phrases/product-name"/> uses hashes to
|
|---|
| 61 | encrypt passwords. The following command must be used: </p>
|
|---|
| 62 | <pre xml:space="preserve">VBoxManage setextradata <varname>VM-name</varname> "VBoxAuthSimple/users/<varname>user</varname>" <varname>hash</varname>
|
|---|
| 63 | </pre>
|
|---|
| 64 | <p>Replace <varname>VM-name</varname> with the VM name or UUID, <varname>user</varname> with the user
|
|---|
| 65 | name who should be allowed to log in and <varname>hash</varname> with the encrypted password. The
|
|---|
| 66 | following command example obtains the hash value for the password <codeph>secret</codeph>: </p>
|
|---|
| 67 | <pre xml:space="preserve">$ VBoxManage internalcommands passwordhash "secret"
|
|---|
| 68 | 2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</pre>
|
|---|
| 69 | <p>You then use <userinput>VBoxManage setextradata</userinput> to store this value in the machine's
|
|---|
| 70 | <codeph>extradata</codeph> section. </p>
|
|---|
| 71 | <p>As a combined example, to set the password for the user <codeph>john</codeph> and the machine
|
|---|
| 72 | <codeph>My VM</codeph> to <codeph>secret</codeph>, use this command: </p>
|
|---|
| 73 | <pre xml:space="preserve">VBoxManage setextradata "My VM" "VBoxAuthSimple/users/john"
|
|---|
| 74 | 2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</pre>
|
|---|
| 75 | </li>
|
|---|
| 76 | </ol>
|
|---|
| 77 | </li>
|
|---|
| 78 | </ol>
|
|---|
| 79 | </li>
|
|---|
| 80 | <li>
|
|---|
| 81 | <p>The <b outputclass="bold">guest</b> authentication method performs authentication with a special component
|
|---|
| 82 | that comes with the Guest Additions. As a result, authentication is not performed on the host, but with the
|
|---|
| 83 | guest user accounts. </p>
|
|---|
| 84 | <p>This method is currently still in testing and not yet supported. </p>
|
|---|
| 85 | </li>
|
|---|
| 86 | </ul>
|
|---|
| 87 | <p>In addition to the methods described above, you can replace the default external authentication module with any
|
|---|
| 88 | other module. For this, <ph conkeyref="vbox-conkeyref-phrases/product-name"/> provides a well-defined interface
|
|---|
| 89 | that enables you to write your own authentication module. This is described in detail in the <ph
|
|---|
| 90 | conkeyref="vbox-conkeyref-phrases/product-name"/> Software Development Kit (SDK) reference. See <xref
|
|---|
| 91 | href="VirtualBoxAPI.dita#VirtualBoxAPI"/>. </p>
|
|---|
| 92 | </body>
|
|---|
| 93 |
|
|---|
| 94 | </topic>
|
|---|
