Custom Logon

Custom Logon is available in every AADS version for Windows Vista and newer.

The subject "Custom Logon" is not for the end-user, but for the Administrator and Software Developer.

Be very carefully: if a mistake is made, the logon process will fail, possible resulting in a completely unusable server.
At least Windows-safe-mode is needed in order to recover from a wrong settings.

"Custom Logon" enables Third Parties or AADS customers to have their "own" logic, achieved by their "own" program/software. This can be used for (example)

• Additional user verification before a desktop is shown, including an "own" look-and-feel.

Whatever the "Custom Logon Program/Software" does, is not decided by AADS. The functionality of the "Custom Logon Program/Software" is defined by the Software Developer of the "Custom Logon Program/Software".

The "Custom Logon Program/Software" runs within the security context of the logged-on RDP user.

Flowchart

Registry Entries

Location of the registry keys

Registry key Names, Types and Default values

• With a default AADS installation, none of these keys are created or do exist.
• The Administrator or Software developer is expected to create these keys.
• If a key does not exist, the Default Value of the key is used.
• If none of these keys do exist, which is default the case, the Custom Logon functionality will not be applied.

useGina Do Apply to Console

• Default the functionality of Custom Logon will not be done when the Desktop Session is on the Console of the AADServer.
• A Value not equal to 0, for example the Value ONE (1), implies that the functionality of Custom Logon will be done when the Desktop Session is on the Console of the AADServer.
• It is recommend not to do the functionality of Custom Logon on the Console of the AADServer. In the event of problems related to the functions of Custom Logon, those problems can be fixed by logging in on the Console of the AADServer. Therefore it is recommended to have ZERO (0) for the Value of this Key.
• If the key does not exist, the Default Value of ZERO (0) is used, implying that the functionality of Custom Logon will not be done when the Desktop Session is on the Console of the AADServer.

useGina If Member of Group

• Default the functionality of Custom Logon will be applied to all users.
• When this Key contains the name of a valid, existing Windows Group, the functionality of Custom Logon will only be applied to users who are a member of this Windows Group.
• In case of AADS Classic, the Windows Group needs to be defined locally on the AADServer.
• In case of AADS Enterprise, the Windows Group can be defined locally on the AADServer, or in the Domain.
• It is recommend  to use the functionality of this key. In the event of problems related to the functions of Custom Logon, those problems will only be applied to the limited number of users who are member of the Group. Other users like Administrators or IT-Admin users, who are not member of this Group, will be able to do a RDP/RDP+/SSL session without the functionality of Custom Logon, and will therefore be able to fix whatever need to be fixed.
• If the key does not exist, the functionality of Custom Logon will be applied to all users.
• If the key does exist, but contains a non-valid, non-existing Group, then the functionality of Custom Logon will never be applied because no user is member of the non-valid, non-existing Group.

Administrator

• The functionality of Custom Logon will not be applied for the user Administrator .
  • This exception is about the user Administrator .
  • This exception is not about other users which are member of the group Administrators or who do have Administrator Rights.
• Note: Default the user Administrator is disabled on Windows since Windows Vista.

useGina Program Name

• If this Key is not filled, or does not exist, the functionality of Custom Logon will not be done.
• With a default AADS installation, none of these keys are created or do exist.
  • Therefore, a default AADS installation will not do the functionality of Custom Logon.
• If this Key is filled, the functionality of Custom Logon will be done.
  • Only filling in this Key is already enough to apply the functionality of Custom Logon, because the other Keys will use their Default Values.

• If the Value of this Key (1) contains an invalid Filename, or (2) contains an non-existing Filename, or (3) there is "some" problem with starting / executing the Program, the RDP/RDP+/SSL session will be logged off and disconnected.

• Before it is "decided" that the RDP/RDP+/SSL session will be logged off and disconnected, first it is decided if the functionality of Custom Logon should be applied based on (1) is this the Console session and useGina Do Apply to Console, and (2) is the user member of the group in useGina If Member of Group. If the functionality of Custom Logon should not be applied because of (1) and/or (2), then the RDP session will not be logged off, but continued as usual.

• The Program as started by the AADServer needs to terminate with an EXITCODE:
  • GetExitCodeProcess
  • An EXITCODE with the value 1 implies that the AADServer continues the login of the remote user as usual.
  • An EXITCODE with the value 2 implies that the AADServer again starts the Program.
  • Any other EXITCODE implies that the AADServer does a logoff and disconnect of the remote user.

useGina TimeOut Running Program (sec)

• If the Program runs longer then the number of seconds in this Key, the remote user will be logged off and disconnected.
• If the Value of this Key is ZERO (0), no Time Out will be applied.
• The minimal Value of this Key is ZERO (0 aka no TimeOut).
• The maximal Value of this Key is 3600 Seconds (1 Hour)

useGina Delay between Program Restarts (sec)

Time is one of the "enemies" of an hacker. Causing "long" time delays between hack/logon attempts, reduces the ability of the hacker to do brute-force logon attempts.

• As stated, an EXITCODE with the value 2 implies that the AADServer again starts the Program.
• Between the "termination" of the Program, and "starting again" of the Program, AADS has a "delay".
• The minimal Value of this Key is ONE (1 second).
• The maximum Value of this Key is 600 (10 Minutes).

HowTo Test

Step 1

• Install AADS Demo on some test hardware or on some VM.
• Download our tool AADSTestToolGenerateUsers.exe
• Create a group "TextExitCode" and make an user member of this group

• Use this REG file as a starting point for testing:

Windows Registry Editor Version 5.00 [HKEY_LOCAL_MACHINE\SOFTWARE\AADServer] "useGina Program Name"="C:\\Program Files\\AADServer\\AADSTestToolGenerateUsers.exe" "useGina Delay between Program Restarts (sec)"=dword:00000005 "useGina TimeOut Running Program (sec)"=dword:0000012C "useGina If Member of Group"="TestExitCode" "useGina Do Apply to Console"= dword:00000000

Note: the value 12C is hex for 300, which is 5 minutes.

• Download AADSTestToolGenerateUsers.exe and place it in the folder  C:\Program Files\AADServer 
• Login with the username "luser002" and test that the "Custom Logon" functionality works.
  Use the TabPage "ExitCode" from the tool  AADSTestToolGenerateUsers.exe for testing with the ExitCode

Step 2

rem test echo on cd C:\test MyTestExitCode.exe echo %ERRORLEVEL%

Step 3

• Define a Group on the local AADServer or in the Domain.
• Make 1 (or a few) users member of this Group.
• Create at least the following 2 Keys
  • useGina Program Name
  • useGina If Member of Group
• Create and use your own "Program" for some Custom Logon functionality.
• Have fun with testing...

Logfile

When the functionality of Custom Logon is applied to an user, a logfile for the user will be created:

• The logfile is names AADServer_SessionInit.utf8.log

Example Local User

• The Local User "luser001" did a RDP session. The sessionnumber was 4.

Example Domain User

• The Domain User "domain001" did a RDP session. The sessionnumber was 7.

Example logging