Functional specification

Solution Design

Updated: 27 Sep 2017

Client Side Group Policy Extension

Implementation

CSE is implemented as single DLL file, publishing the following entry points:

  • ProcessGroupPolicy — It is main entry point for Group Policy framework. This entry point implements ProcessGroupPolicy() callback as described in MSDN
  • DllRegisterServer — Can be used for manual registration of CSE with GPO framework and with Event Log service during the CSE installation/upgrade in case that it is not possible to use MSI installer for installation
  • DllUnregisterServer — Can be used for manual deregistration of CSE from GPO framework and Event Log service during the uninstallation process of CSE in case that it is not possible to use MSI installer for installation

Logic of the processing is as follows:

  1. CSE connects to Active Directory; to the computer object managed machine it is running on
  2. CSE then reads the value of attribute ms-MCS-AdmPwdExpirationTime. This attribute stores the expiration time of current password
    • When the attribute is empty, password was never changed, so CSE knows it is the time to reset the password
    • When the timestamp is not older than current time, password has not expired yet, and CSE does not perform any other operation and finishes processing
    • When the timestamp is older than current time, CSE knows it is the time to reset the password
  3. When configuration requires password to comply with maximum age restriction, CSE compares expiration time with maximum age of password specified in GPO. When expiration is longer than maximum age, CSE knows that it’s time to change the password and reset the password age
  4. When configuration requires protection against password changes outside of solution, CSE reads age of managed local administrator account and compares it with expected age, given by last password change performed by CSE. When age is different than expected, password is considered invalid and CSE knows it’s time to reset it
  5. When password needs to be reset, CSE detects the local Administrator account to manage (either via name configured using GPO or via well-known SID) and connects to it
  6. Then CSE invents new password according to required criteria (length and complexity)
  7. In case that solution is configured to store the password encrypted in AD, CSE loads encryption key from GPO and uses it to encrypt the password. CSE then converts encrypted blob to Base64 string
  8. Then CSE reports new password (plain text or Base64 encoded encrypted blob) and timestamp to Active Directory, to the following attributes of computer account for machine it runs on:
    • ms-MCS-AdmPwd: password
      • either plaintext password
      • or Base64 string containing encrypted password, prefixed by ID of the key used for encryption
        Format: <keyID>:<space><Base64>
        Example:
        1: ZmwKf34lH1/+NsjIWSfKQSb4H…
    • ms-MCS-AdmPwdExpirationTime: timestamp of current time plus configured age of password, in FILETIME format (64-bit integer), in UTC
    • ms-MCS-AdmPwdHistory: in case that maintenance of password history is required, timestamp of current time (Directory string) plus password as reported to ms-MCS-AdmPwd attribute
      Format: <timestamp>:<space><value of ms-MCS-AdmPwd>
      Example:
      20140929233650.0Z: 1: ZmwKf34lH1/+NsjIWSfKQSb4H…
    • Note: This communication with Active Directory is encrypted with Kerberos encryption
      • Important: When CSE communicates with Active Directory, it avoids talking with RODC and always looks for writable DC to talk with.
  9. After password and expiration timestamp are successfully reported to AD, the password of managed Administrator account is reset to new value invented in step 6
    • Reason for this sequence of steps is that we cannot report and reset password as a single transaction.
      So, we consider the reporting of password to AD as more “risky” – more things can get wrong as there is network between workstation and domain controller, whereas password reset operation works against local computer.
      We try to perform the operation considered riskier first to be able to catch any errors prior resetting the password.
      This order of steps minimizes the risk that reported password will be different than actual password of managed Administrator account
  10. After successfully resetting the password, CSE finishes execution reporting success to GPO framework that called it
  11. In case that some error occurs during the execution, CSE logs the error to Application log and finishes execution, reporting the error to GPO framework that called it

Configuration

CSE is configurable using registry values specified in the registry key:
HKLM\Software\Policies\Microsoft Services\AdmPwd
Currently the following configuration values are supported:

Value Type Meaning
AdmPwdEnabled REG_DWORD Setting to non-zero enables the solution.
Resulting policy must have this value set to non-zero so as the solution is enabled to work on managed machine.
Managed by policy “Enable local admin password management”
AdminAccountName REG_SZ Name of local account to manage password for.
If not configured, CSE manages built-in Administrator password regardless of its name (detects it via well-known SID)
Managed by policy “Customize administrator account name”
ManualPasswordChangeProtectionEnabled REG_DWORD Setting to zero disables protection against manual changes of managed local administrator account.
If not configured or set to non-zero, protection is active
Managed by policy “Protect against manual changes of password”
LogLevel REG_DWORD Logging level on clients.
Supported values are specified below
If not configured, default is 0.
Managed by policy “Logging level”
PasswordLength REG_DWORD Length of password generated
Minimum: 8
Maximum: 64
Default: 12
Managed by policy “Password Settings”
PasswordComplexity REG_DWORD Complexity of generated password
Minimum: 1
Maximum: 4
Default: 4
Meaning of values:
1 … large letters
2 … large letters + small letters
3 … large letters + small letters + numbers
4 … large letters + small letters + numbers + spec chars
Managed by policy “Password Settings”
PasswordAge REG_DWORD Age of password in hours.
Minimum: 1
Maximum: 9999
Default: 720 (30 days)
Managed by policy “Password Settings”
PublicKey REG_SZ Base64-encoded public key for password encryption. This is CryptoAPI encryption key, used by clients up to 7.5.1.0.
Get key via PowerShell cmdlet Get-AdmPwdPublicKey
Managed by policy „Password encryption“
EncryptionKey REG_SZ Base64-encoded public key for password encryption. This is CNG encryption key, used by clients v7.5.2.0 and above
Get key via PowerShell cmdlet Get-AdmPwdPublicKey
Managed by policy „Password encryption“
PwdExpirationProtectionEnabled REG_DWORD Whether CSE shall enforce password age to be aligned with PasswordAge parameter
If set to non-zero, when password expiration time set on computer exceeds PasswordAge policy, password is reset upon next GPO refresh and expiration is set according to policy
Managed by policy “Do not allow password expiration time longer than required by policy”
PwdEncryptionEnabled REG_DWORD Whether or not password encryption is enabled
Default: No
Managed by policy „Password encryption“
PwdHistoryEnabled REG_DWORD Whether or not to maintain password history for computer
Managed by policy „Maintain history of passwords“

Note: In GPO UI, all configuration settings related to configuration of CSE ale located under Computer configuration/Administrative Templates/AdmPwd Enterprise/Managed Clients path

Logging

CSE logs all events in Application Event Log of local computer. Log messages are English only, but can be localized or additional language can be added, if necessary, in the future.

Type of events that are logged is configurable either via GPO or via the following registry REG_DWORD value: HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GPExtensions\{D76B9641-3288-4f75-942D-087DE603E3EA}\ExtensionDebugLevel

Note: This registry value takes precedence over Logging level policy – see above for details

Semantic of possible values is as follows:

Value Meaning
0 Silent mode; log errors only
When no error occurs, no information is logged about CSE activity
This is a default value
1 Log Errors and warnings
2 Verbose mode, log everything

Event source for all events reported by CSE is always “AdmPwd”. The following table summarizes the events that can occur in the Event Log:

ID Severity Description Comment
2 Error Could not get computer object from AD. Error %1 This event is logged in case that CSE is not able to connect to computer account for local computer in AD.
%1 is a placeholder for error code returned by function that retrieves local computer name, converts it to DN and connects to AD object specified by the DN
3 Error Could not get local Administrator account. Error %1 This event is logged in case that CSE is not able to connect to built-in Administrator account.
%1 is a placeholder to error code returned by function that detects the name of local administrator’s account and connects to the account
4 Error Could not get password expiration timestamp from computer account in AD. Error %1. This event is logged in case that CSE is not able to read the value of ms-MCS-AdmPwdExpirationTime of computer account in AD
%1 is a placeholder for error code returned by function that reads the value of the attribute and converts the value to unsigned __int64 type
6 Error Could not create new password. Error %1. This event is logged when CSE for any reason (typically because of failure to initialize/use random number generator) cannot create new password for local admin account
7 Error Could not encrypt password. Error %1. This event is logged in any of the following situations:

  • CSE cannot locate public key in registry
  • Public key blob stored in GPO is invalid
  • RSA CSP is not able to encrypt the password
8 Error Could not write changed password to AD. Error %1. This event is logged in case that CSE is not able to report new password and timestamp to AD.
%1 is a placeholder for error code returned by LDAP modify request
9 Error Could not reset local Administrator’s password. Error %1 This event is logged in case that CSE is not able to reset the password of built-in Administrator account.
%1 is a placeholder for error returned byNetUserSetInfo() API call
12 Error Could not check if password is in sync with AD. Error %1. This error is logged when CSE is not able to detect password age of managed local administrator account.
%1 is placeholder for error returned by NetUserGetInfo() API call
100 Information Beginning processing with flags %1. This event is logged when CSE starts processing GPO update event
%1 is placeholder for value of flag passed toProcessGroupPolicy() entry point by GPO framework
101 Information It is not necessary to change password yet. Will be changed in %1 days, %2 hours. This event is logged in case that CSE detects that it is not yet the time to reset the password of managed admin account
103 Information Local Administrator’s password has been successfully encrypted This event is logged when password is successfully encrypted
104 Information Local Administrator’s password has been reported to AD. This event is logged when password is successfully reported to AD
105 Information Local Administrator’s password has been changed This event is logged after CSE resets the password of managed admin account
106 Information Admin password was not manipulated with (%1) This event is logged when CSE detects that password of managed local administrator account was not manipulated with.
%1 is placeholder for difference between expected and real password age, in seconds. Accepted difference is up to 3 seconds
110 Information Finished successfully This event is logged after CSE performed all required tasks and is about to finish
200 Warning Password expiration too long for computer (%1 days, %2 hours). Resetting password now. This event is logged in case that CSE detects that password expiration for computer is longer than allowed by policy in place while protection against excessive password age is turned on
201 Warning Password was manipulated with since last check (%1 seconds after regular password change). Resetting password now. This event is logged when CSE detect that password of managed local administrator account was changed outside of solution (such as manually by user with administrative permission).
202 Information Admin account management not enabled, exiting This event is logged when admin account management is not enabled and CSE is not allowed to work

Notes:

  • Generally, all events with severity “Error” are blocking, so in case that any error occurs, no other tasks are performed and CSE terminates its processing
  • Event source for the Event Log is embedded in the same executable as main GPO executive. Reason for this decision was to make the deployment simple

Information security

Active Directory

Solution maintains 3 pieces of information for managed local Administrator account in Active Directory:

  • Current password
  • Timestamp of expiration of current password
  • Password history Permission model around this information is as follows:
Information Who needs to read Who needs to write
Password PDS identity Computer that owns the computer account (so every computer can write password of own admin account to AD)
Password Expiration Timestamp PDS identity
Computer that owns the computer account (so every computer can know whether it is the time to change the password of own admin account)
Computer that owns the computer account (so every computer can write only password expiration timestamp to AD)
PDS identity
Password history PDS identity Computer that owns the computer account (so every computer can write password history of own admin account to AD)
AD administrator – to maintain password history

For Managed Domain Accounts – user accounts in AD, whose password is managed by PDS – security model is slightly different:

Information Who needs to read Who needs to write
Password PDS identity PDS identity
Password Expiration Timestamp PDS identity PDS identity
Password history PDS identity PDS identity

Note: Domain administrators can obviously read and write all attributes, but – in case that password is stored encrypted in AD – still are not able to get decrypted password unless given explicit permission. Only PDS can decrypt the password stored in AD.

Network communication

Network transmission protection include the following communication:

  • Between managed machine and AD
  • Between AD and PDS
  • Between PDS and client tools In all above scenarios, all transferred information is encrypted by Kerberos encryption, protecting transmitted data from eavesdropping. This is generally the same encryption that protects information on Kerberos tokens.

PDS

Solution recognizes 2 new extended rights in Active Directory:

  • Read Administrator Password
  • Reset Administrator Password Rights are imported to AD as a part of AD preparation procedure (PowerShell cmdletUpdate-AdmPwdADSchema). Those rights are not used by AD itself – they are used by PDS to perform authorization checks. Permissions apply to computer objects; use PowerShell cmdlets Set-AdmPwdReadPasswordPermission and Set-AdmPwdResetPasswordPermission to grant respective permissions to security principals who need them. By default, no one is granted the permission to read and reset admin passwords.

Protection against deletion of computer account

Computer accounts might be subject of accidental deletion. In such case (especially when AD Recycle Bin feature of Windows 2008 R2 is not implemented) password of built-in Administrator account would be lost and there would not be an easy way for support staff to read it: it would require using the SystemState backup to read the password – unless the Forest Functional Level (FFL) is Windows 2008 R2 and AD Recycle Bin feature is turned on. Approach for protection against accidental deletion of computer account is implemented as follows:

  • ms-MCS-AdmPwd and ms-MCS-AdmPwdHistory attributes are added to the set of attributes that will not be stripped off the object during the deletion
  • This means that password will still be available on tombstone of computer account for the lifetime of tombstone – which is 180 days by default
  • So, when accidental deletion of computer account occurs, Domain admin role will be able to quickly reanimate the tombstone object, and password can be retrieved from reanimated tombstone using solution client tools (such as Web UI)
  • Only after tombstone expires, the password is lost. Tombstone lifetime is long enough for password recovery Main benefit of this approach is that it allows not exporting passwords from AD infrastructure to independent location where it would need to be specially protected – just for the sake of protection against the special case of accidentally deleted computer account.

In addition, solution comes with ability to retrieve password directly from deleted computer account. Prerequisite for this ability is to properly set permission on Deleted Objects container in each domain of forest:

  • Read Property
  • List

Administrators can use cmdlet Set-AdmPwdPdsDeletedObjectsPermission to delegate the permission of Deleted Objects container to PDS service account.

Note: Deleted computer object keeps its original ACL – this means that users who were delegated to retrieve password from computer object before its deletion can do this on deleted computer, too.

Active Directory infrastructure

Active Directory infrastructure supports the solution by:

  • Implementing the shared storage of information maintained by the solution
  • Implementing GPO framework that is used to trigger CSE activity
  • Maintaining security model in ACLs applying to computer objects

The following paragraphs summarize changes that are required on the Active Directory level when implementing the solution.

AD Schema

Solution relies on 3 new attributes added to AD schema. Attributes store password of managed local administrator account for each workstation, password history and timestamp of password expiration. All attributes are added to may-contain attribute set of user class. Specification of new attributes is in the table below.

Attribute Parameter Value
ms-MCS-AdmPwd Syntax 2.5.5.5
(Printable case-sensitive string)
omSyntax 19
isSingleValued True
searchFlags 904
(fCONFIDENTIAL + fPRESERVEONDELETE + fRODCFilteredAttribute + fNeverAuditValue)
isMemberOfPartialAttributeSet False
OID BASE_OID.2.1
ms-MCS-AdmPwdExpirationTime Syntax 2.5.5.16
(Large integer)
omSyntax 65
isSingleValued True
searchFlags 0
isMemberOfPartialAttributeSet False
OID BASE_OID.2.2
ms-MCS-AdmPwdHistory Syntax 2.5.5.5
(Printable case-sensitive string)
omSyntax 19
isSingleValued False
searchFlags 904
(fCONFIDENTIAL + fPRESERVEONDELETE + fRODCFilteredAttribute + fNeverAuditValue)
isMemberOfPartialAttributeSet False
OID BASE_OID.2.3

BASE_OID: 1.2.840.113556.1.8000.2554.50051.45980.28112.18903.35903.6685103.1224907

Attributes that contain password are flagged as:

  • Confidential: CONTROL_ACCESS permission is required to read the value of attribute, so password is better protected
  • Preserved on delete: value is not stripped of the tombstone, so it is possible to recover password from deleted object
  • RODC filtered: value is not replicated to RODC
  • Excluded from audit: Domain controller does not write value of attribute to Security log when detailed auditing is enabled

Extended rights

Solution defines 2 new extended rights in AD Configuration partition. Specification is in table below.

Right Parameter Value
ms-Mcs-AdmPwdReadPassword objectClass controlAccessRight
displayName Read Administrator Password
appliesTo bf967a86-0de6-11d0-a285-00aa003049e2
(computer objects)
rightsGuid 2a72352f-f5f8-40a3-83b2-1d8562fa90c4
validAccesses 256
See here for details
showInAdvancedViewOnly FALSE
ms-Mcs-AdmPwdResetPassword objectClass controlAccessRight
displayName Reset Administrator Password
appliesTo bf967a86-0de6-11d0-a285-00aa003049e2
(computer objects)
rightsGuid 5E4DF2BA-49FB-4703-87D9-B69F00C4C039
validAccesses 256
showInAdvancedViewOnly FALSE

Password Decryption Service

Password Decryption Service (PDS) plays the following key roles:

  • Handling password retrieval and password reset requests from users
  • Management of passwords for Managed Domain Accounts
  • Maintenance of key pairs
  • Enforcement of auditing
  • License validation

PDS is designed to operate in multiple AD domains and forests. This means that AD domain / forest can be covered by instance of PDS running in different AD domain / forest, provided that the following prerequisites are met:

  • There is at least one-way trust relationship between forest where PDS is installed (PDS forest) and other forest, so as permissions can be granted to security principals from PDS forest in the other forest
  • Permissions to read password, reset password and for PDS itself are granted using objects resolvable from PDS domain / forest, such as global groups from PDS forest
  • PDS is allowed to perform authenticated LDAP operations against domain controllers of the other domain / forest
  • Any AD domain where users of PDS service have user accounts, has SRV records for PDS created in its DNS zone pointing to instance of PDS server(s), so as client tools can locate PDS instance
    • Or GPO PDS to be used is configured and applies to machines running administrative tools

PDS logs all activities into dedicated Windows log: Application and Service Logs – GreyCorbel-AdmPwd.E-PDS/Operational. PDS is implemented as Win32 service with name “AdmPwd.E PDS” and display name “AdmPwd.E Password Decryption Service”. Service executable and all related files are installed to %ProgramFiles%\AdmPwd\PDS, and is installed to run under NETWORK SERVICE account by default.

Configuration of service is managed by config file AdmPwd.Service.exe.config, located in service install folder.

PDS keeps decryption keys in CryptoKeyStorage subfolder. Setup program sets ACL on this subfolder so as only SYSTEM, Administrators and NETWORK SERVICE have access to it. Also, PDS supports extensibility to allow implementation of custom key storage. Currently available key storage options are:

  • File system keystore: stores keys on file system (by default in CryptoKeyStorage folder in PDS install folder). This keystore is installed with PDS.
  • Azure KeyVault keystore: Stores leys in Azure KeyVault as secrets. Loads the keys from KeyVault upon PDS service startup. Implementation of this keystore is available as open source solution on GitHub
  • HSM keystore: This type of keystore is available with any HSM supported by Cryptomathic Crypto Service Gateway (CSG) and is licensed separately

PDS registers and maintains DNS SRV record that is used by service clients to find the service.

PDS setup registers file PDS.Messages.dll as event message and resource file for Event Viewer.

Paragraphs below describe implementation details of service components.

Configuration

Configuration of service is maintained in AdmPwd.Service.exe.config file. Service recognizes configuration parameters as specified below

Parameter Meaning Note
Pds – Dns – Autodiscovery – RegistrationInterval Interval for DNS SRV record refresh, in seconds.
PDS automatically refreshes its own SRV record to prevent expiration
Default: 86400 (1 day)
Setting to 0 disables SRV record registration and refresh. This is useful in environments where PDS service account does not have permission to write to DNS.
Pds – Dns – Autodiscovery – UnregisterOnShutdown Whether PDS shall unregisters its own DNS SRV record during service shutdown Default: false
Pds – Dns – Autodiscovery – Priority Priority of SRV record being created by instance of PDS Default: 100
Pds – Dns – Autodiscovery – Weight Weight of SRV record being created by instance of PDS Default: 100
Note: Client tools delivered with solution ignore weight of SRV records – thus they do not perform load balancing
Pds – Dns – Autodiscovery – TTL TTL of registered SRV record, in seconds Default: 1200 (20 minutes)
Pds – Dns – Autodiscovery – DomainsToPublish – domain DNS name of domain where PDS shall publish own SRV record When specified, PDS registers SRV record in specified domains only.
PDS own domain must be listed as well so as PDS would register SRV record there.
If no domain specified, PDS registers SRV record in own domain only.
Pds – Keystore Identifier of assembly implementing keystore for key pairs PDS supports extensibility and different implementations of keystore.
Pds – AccessControl – HonorFullControlPermission Whether or not to honor Full Control permission on computer object when performing authorization checks for password reads and reset.
When set to TRUE, users who have Full control permission on computer objects can read and reset local admin password even when they are not given explicit permissions as specified in Extended Rights specification
Default: false
(Full control right on AD object does NOT give permission to read/reset admin password)
Pds – KeyAdmin – role Name of AD group implementing Key Admin role Default: Enterprise Admins
Pds – License – file Path to license file that unlocks the solution from freeware mode Default: license.xml
Relative to PDS folder; so, by default, PDS looks for license.xml file in %ProgramFiles%\AdmPwd\PDS
Can be also absolute path.
Pds – SupportedForests – forest List of forests managed by PDS. When missing, only local forest where PDS is installed is supported.

Default: Not present, which means that PDS manages only its own AD forest.

Note: Local PDS forest is always supported.

KeyStore – path Path where key pairs are stored Default: CryptoKeyStorage
Relative to PDS folder; so, by default, PDS looks for key pairs in %ProgramFiles%\AdmPwd\PDS\CryptoKeyStorage
KeyStore – pathType Whether path is absolute or relative Default: Relative
Possible values: Absolute, Relative
KeyStore – cryptoForNewKeys Cryptography used to generate new encryption/decryption keys Default: CryptoAPI
Possible values: CNG, CryptoAPI
Note: CryptoAPI is maintained for compatibility and ability to generate new keys using CryptoAPI will be removed in future versionsHowever, PDS will still be able to decrypt passwords encrypted with CryptoPAPI keys
KeyStore – SupportedKeySizes – add – value List of supported key sizes when creating new key pair PDS only allows to create key pair with one of the specified key sizes
 ManagedAccounts – passwordManagementInterval  How often PDS looks for expired passwords of Managed Domain Accounts  Default: 600 seconds
ManagedAccounts – containers – add – distinguishedName DN of container when PDS looks for Managed Domain Accounts to manage password for
ManagedAccounts – containers – add – passwordAge Password age for Managed Domain Accounts in given container, in minutes. Default: 43200 minutes (30 days)
ManagedAccounts – containers – add – keyId ID of encryption key to use to encrypt the password of Managed Domain Account in given container Default: 0, which means most recent key managed by keystore
ManagedAccounts – containers – add – passwordComplexity Required complexity of password for Managed Domain Accounts in given container

Allowed values:

1 .. Large letters

2 .. Large and Small letters

3 .. Large and Small letters and Numbers

4 .. Large and Small letters, Numbers and Special characters

Default: 4

ManagedAccounts – containers – add – passwordLength Required length of password set by PDS on Managed Domain Accounts in given container Default: 14

Sample of pretty-much default configuration:


<PDS>
<Dns>
<Autodiscovery UnregisterOnShutdown="true" RegistrationInterval="86400" Priority="100" Weight="100" TTL="1200">
<DomainsToPublish>
</DomainsToPublish>
</Autodiscovery>
</Dns>
<KeyStore assembly="AdmPwd.Service" typeName="AdmPwd.PDS.KeyStore.FileSystemKeyStore"/>
<AccessControl HonorFullControlPermission="false"/>
<KeyAdmin role="Enterprise Admins"/>
<License file="license.xml"/>
</PDS>
<KeyStore path="CryptoKeyStorage" pathType="Relative" cryptoForNewKeys="CryptoAPI">
<SupportedKeySizes>
<add value="1024"/>
<add value="2048"/>
<add value="3072"/>
<add value="4096"/>
</SupportedKeySizes>
</KeyStore>
<ManagedAccounts passwordManagementInterval="3600">
<containers>
<add distinguishedName="OU=managedDomainAccounts,DC=ad,DC=mycompany,DC=com" passwordAge="86400"/>
</containers>
</ManagedAccounts>

Licensing

Solution is free to use for up to 25 managed machines and 1 Managed Domain Account. For management of more machines or accounts, license is needed for respective number of machines or accounts. License is expressed by digitally signed license file that can be downloaded from solution licensing web . License file contains the following information:

  • Number of licensed machines
    • Note: PDS may support remote forests without explicit license for this forest, as long as managed machines in remote forest are included in number of licensed machines
  • Number of managed domain accounts
  • Name of AD forest PDS will be installed to
  • License expiration date

License file needs to be reachable to all instances of PDS – when not found or reachable, PDS switches itself into Freeware mode that allows 25 managed machines and 1 managed domain account. Multiple instances of PDS can use the same license file.

Path to and name of license file is specified in PDS configuration file – see PDS configuration for details. License file is digitally signed to prevent tampering with. License is validated upon PDS startup and then every 24 hours.

Only machines that were alive in last 60 days and are managed by the solution need a license. This means that:

  • Machines that are no longer in use and for some reason are not deleted from AD do not need license.
  • Deleted machines do not need license.

For Managed Domain Accounts, PDS manages password for only those accounts located in containers specified in configuration file. However, for purpose of counting of licenses, it looks for Managed Domain Accounts in entire domain

License validation scenarios and expected behavior are specified below:

  1. License file is missing, corrupted or tampered with
    • PDS switches into freeware mode
  2. License expired:
    • PDS switches into freeware mode
  3. License issued for different forest than PDS deployed in
    • PDS switches into freeware mode
  4. Number of licensed machines or Managed User Accounts is lower than actual number of managed machines in all AD forests supported by an instance of PDS
    • PDS degrades the service as follows:
      • For each request for password read and reset, PDS generates a random number between 0 and number of managed machines
      • If the number is greater than number of licensed machines, PDS refuses to fulfill the request and remembers the machine name, so all subsequent attempts to read/reset password for this machine will fail
    • So, PDS still works, but it may refuse to fulfill the request for some machines. The risk increases with number of unlicensed machines

When license file does not pass validation, normal operations can be restored by downloading updated license file with correct information, making it available to PDS and restarting the PDS service.

Logging

PDS records its activity into dedicated Windows log: Application and Service logs – GreyCorbel – AdmPwd.E – PDS – Operations and auditing Events logged by PDS fall into 4 categories:

Category Event types
Service Operation Events that cover PDS internal opration, such as shutdown, startup, key loading, DNS registration
Audit Events that track user activity, such as password reads and resets, and creation of new key pair by KeyAdmin role
Licensing Events that describe status of licenses and license counting
Account management Events that cover PDS activity in management of password of Managed Domain Accounts

Below is specification of events for each category

Operational

ID Severity Description Comment
100 Success Service started
101 Success Service stopped
102 Success Autodiscover record updated.
Record: %1
Logged every time PDS successfully updates its DNS SRV record
202 Error Failed to update Autodiscover record.
Record: %1
Error: %2
Logged in case that PDS fails to update its DNS SRV record
103 Success Autodiscover record removed
Record: %1
Logged when PDS removes its DNS SRV record.
Only happens when SrvRecordUnregisterOnShutdown parameter is set to true
203 Error Failed to remove Autodiscover record.
Record: %1
Error: %2
Logged in case that PDS fails to remove its DNS SRV record
104 Information Registering autodiscover SRV record with following:
Domain: %1
Host: %2
Port: %3
Priority: %4
Weight: %5
TTL: %6
Logged before registration of DNS SRV record. Shows parameters of SRV record being registered.
305 Warning Expiration time exists but password empty. This typically happens when service does not have properly configured permissions in AD.
Please verify configuration and if needed, fix permissions via Set-AdmPwdServiceAccountPermission cmdlet.
Forest: %1
Computer: %2
User: %3
Logged in case that service detects that response for local admin password retrieval contains timestamp of password expiration, but not a password itself.
This is to notify administrator of solution that PDS may not have enough permissions to read password from AD
106 Information Key Pair loaded
Id: %1
Logged when PDS successfully loads key pair from keystore
Note: Custom implementations of keystore are expected to implement logging of this event.
207 Error File based keystore does not exist. No keys will be loaded.
Keystore folder: %1
Logged when PDS does not find keystore folder pointed to by Pds – KeyStore – path parameter (see [PDS configuration)(#PDS_Config) for details)
208 Error Error during Autodiscover registration/unregistration.
Error: %1
Logged when PDS encounters unexpected error during SRV record registration/deregistration

Audit

ID Severity Description Comment
1000 Information Admin password retrieved.
Forest: %1
Computer: %2
IsDeleted: %3
User: %4
Logged when User retrieves password for admin account of specific computer in given forest.
Empty Forest field means that local PDS forest was used.
IsDeleted field is Boolean value that is true when user retrieved password for deleted computer account
1100 Warning Failed to retrieve admin password.
Forest: %1
Computer: %2
IsDeleted: %3
User: %4
Error: %5
Including scenario when user requesting the password retrieval does not have permission granted
1001 Information Admin password reset.
Forest: %1
Computer: %2
User: %3
Expiration time: %4
Expiration time contains expiration time specified by user in request.
For immediate expiration, current time is sent.
1101 Warning Failed to reset admin password.
Forest: %1
Computer: %2
User: %3
Error: %4
Including scenario when user requesting the password reset does not have permission granted
1002 Information Key pair generated.
KeyID: %2
User: %1
1102 Warning Failed to generate key pair.
User: %1
Error: %2
Including scenario when user requesting key pair generation is not member of Key Admin role
1003 Information Password of managed account retrieved.
Forest: %1
Account: %2
User: %3
Logged when User retrieves password for specified Managed Domain Account in given forest.
Empty Forest field means that local PDS forest was used.
1103 Warning Failed to retrieve password of managed account.
Forest: %1
Account: %2
User: %3
Error: %4
Including scenario when user requesting the password retrieval does not have permission granted
1004 Information Password of managed account reset.
Forest: %1
Account: %2
User: %3
Expiration time: %4
Expiration time contains expiration time specified by user in request.
For immediate expiration, current time is sent.
1104 Warning Failed to reset password of managed account.
Forest: %1
Account: %2
User: %3
Error: %4
Including scenario when user requesting the password reset does not have permission granted

Licensing

ID Severity Description Comment
2100 Warning License file not found. Running in freeware mode.
License file path: %1
Logged when administrator did not provide license file. PDS runs in freeware mode that allows usage for 25 managed machines
2000 Information License validated.
Forest: %1
Licensed computers: %2
License usage: %3 (%4%)
License expiration: %5
Logged after successful validation of license file.
Placeholders used:
%1 – AD forest where PDS is installed
%2 – number of licensed computers
%3 – number of computers managed by solution
%4 – percentage of license usage
%5 – when current license expires
2001 Information Running in freeware mode.
Licensed computers: %1
License usage: %2 (%3%)
Logged after determining that solution is running without license file in freeware mode.
Placeholders used:
%1 – number of licensed computers by freeware license (currently 25)
%2 – number of computers managed by solution
%3 – percentage of license usage
2002 Information Managed machines stats for domain.
Domain: %1
License usage: %2
Logged for every domain covered by the solution. Shows number of machines managed by solution in each domain.
2003 Information Add-on license validated.
Add-on: %1
Type: %2
Logged when license for add-on component is successfully validated
Currently only add-on component that requires separate licensing is HSM keystore
2004 Information Running in freeware mode.
Licensed managed accounts: %1
License usage: %2 (%3%)
Logged when license file is not found, does not contain license for Managed Domain Accounts, license file is tampered with, or license is expired
2100 Warning License file not found. Running in freeware mode.%nLicense file path: %1 Logged when PDS does not find license file. In this situation, PDS switches to freeware mode.
2101 Warning License is about to expire.
Expiration date: %1
Please install updated license file.
Logged when license has 30 days or less to expiration date.
2102 Warning License file not found. Running in freeware mode.
License file path: %1
Logged when license file specified in PDS config file is not found
2103 Warning Missing license for add-on. Add-on switched to freeware mode.
Add-on: %1
Type: %2

Logged when license file does not contain license for add-on component.

Currently only add-on component that requires separate licensing is HSM keystore

2201 Error License file found, but digital signature validation did not pass. Running in freeware mode.
Please download updated license
License file path: %1
Logged when PDS finds out that license file was tampered with – digital signature is invalid. In this situation, PDS switches to freeware mode.
Administrator shall immediately download fresh copy of license file from AdmPwd licensing web.
2202 Error License expired. Running in freeware mode.
Expiration date: %1
Logged when PDS finds out that license has expired. Administrator shall immediately download updated license file from AdmPwd licensing web.
2203 Error Not enough licenses. For some computers, you may not be able to retrieve/reset admin password.
Licensed computers: %1
Total licenses needed: %2
Logged when PDS finds out that solution manages more computers than currently licensed.
When this happens, PDS may randomly refuse to get/reset password for a computer. Probability of refusing an operation increases with number of unlicensed computers
Note: Probability is computed as follows:
# of unlicensed computers / # of all computers
2204 Error License issued for different AD forest. Running in freeware mode.
Licensed forest: %1
Current forest: %2
This event is logged when PDS finds out that it runs in different AD forest than licensed.
License is issued for specific AD forest where PDS is installed in.
Note: PDS can support multiple AD forests, but it needs to have license for own forest and all forests where managed computers are.
When this happens, PDS switches into freeware mode.
2205 Error Error during license validation. Running in freeware mode.
License file: %1
Error: %2
Logged when PDS encounters any other error during license validation than specified otherwise.
When this happens, PDS switches into freeware mode.
2206 Error Error during license usage counting.
Domain: %1
Error: %2
Logged when PDS is not able to count license usage in specific domain
When this happens PDS temporarily allows to continue and does not count the forest into license consumption.
2207 Error Error during license usage counting.
Error: %1
Logged when PDS encounters unexpected error when counting license usage.
When this happens, PDS temporarily allows to continue and does not enforce license usage
2208 Error Not enough licenses for managed domain user accounts. For some managed accounts, you may not be able to retrieve/reset password.
Licensed managed accounts: %1
Total licenses needed: %2
Logged when PDS finds out that there is not enough licenses for all Managed Domain Accounts found in environment

Autodiscovery

PDS registers autodiscover SRV record in DNS. Record helps client tools to locate instance of PDS service. Service is supported to be running in multiple instances; each instance maintains own SRV record.

Clients use SRV record to discover instances of PDS as follows:

  • At startup, client performs query for SRV record _admpwd._tcp.domain
    • domain is client‘s domain
  • Client orders SRV records from DNS server response in ascending order by Priority to get list of discovered PDS instances, and marks each discovered instance as available.
  • During its lifetime, client works with list of discovered PDS instances as follows:
    • For each request for PDS, client gets the connection to the instance of PDS
    • Before connection is used, it is verified that instance of PDS behind the connection is responding
    • If PDS instance is not responding, connection is marked as unavailable and client tries to use next connection in the list. If not responding, client marks it as unavailable and tries to connect to next service in the list, etc…
    • As long as there is at least 1 service connection marked as available in the list, client uses it.
    • When there are no services in the list marked as available, client performs full discovery of available services (via DNS query for PDS SRV records) and throws exception informing upper layers of application logic that there were no services available
    • After receiving the exception, upper layers of application logic will decide how to continue. When decision is to retry the request, fresh list of discovered instances is used

Note: The same logic is used when client gets list of PDS instances from registry GPO – se Management tools configuration for details

Decision flow is depicted on flowchart below:

PDS discovery process

This means that autodiscovery data need to be available (via GPO or DNS) in every domain that hosts machines with solution administrative tools installed (not managed computers)
Instance of PD service maintains SRV record in own AD domain only by default, however, it can maintain records in other domains, too – see PDS configuration for details.
SRV records in DNS may be maintained manually. In this case, PDS shall be configured to mode that does not periodically register SRV records – see PDS configuration for details.

Service account

Default service account for PDS is NETWORK SERVICE. In this configuration service uses SPN HOST/<computername>.

It is however supported to run the service under domain account. To do so service SPN must be changed and registered with domain account. Change must be performed on both service side (all running instances) and client side.

To change service identity on server side, change it AdmPwd.Service.exe.config from dns to servicePrincipalName and set its value to SVC/AdmPwd as shown below:

<service behaviorConfiguration="AdmPwdService.ServiceBehavior" name="AdmPwd.Service.AdmPwdSvc">
  <endpoint address="" binding="netTcpBinding" name="NetTcpEndpoint" contract="AdmPwd.Service.IAdmPwdSvc">
    <identity>
      <servicePrincipalName value = "SVC/AdmPwd" />
    </identity>
  </endpoint>
  <endpoint address="mex" binding="mexTcpBinding" bindingConfiguration="" name="MexTcpEndpoint" contract="IMetadataExchange" />
  <host>
    <baseAddresses>
      <add baseAddress="net.tcp://localhost:61184/AdmPwdService" />
    </baseAddresses>
  </host>
</service>

Important: content of the config file is case sensitive. Please make sure you use the case as shown in sample above when making changes

Change of service account on server side must be supported by configuration of management tools side as well. In default configuration, management tools expect that service uses SPN HOST/<computername>. In configuration with domain account, management tools need to use service specific SPN SVC/AdmPwd when calling PDS.

This change of configuration of management tools can be done via registry using GPO as specified in Management tools configuration

Checklist for changing from NETWORK SERVICE account to domain account

Create account for service (service account) in domain

Register SPN SVC/AdmPwd on service account

Grant service account Read permission on PDS install folder (%ProgramFiles64%\AdmPwd\PDS) and Modify permission to CryptoKeyStorage folder (%ProgramFiles64%\AdmPwd\PDS\CryptoKeyStorage by default)

Grant service account PDS permission on AD via Set-AdmPwdPdsPermission PowerShell cmdlet

Grant service account permission to read/write SRV record in DNS; or turn off SRV record registration and maintain record manually

Configure Group Policy “PDS service runs using domain account” to Enabled and apply it to machines that are running management tools. This includes all machines that are running at least one of following:

  • PowerShell module
  • Fat client UI
  • Web UI

Set domain account as logon identity of PDS Win32 service and restart the service

Important: All installed PDS instances must use the same service account

Installers

The following installers are delivered with the solution:

  • CSE installer: AdmPwd.E.CSE.Setup.<platform>.msi
  • Management tools installer: AdmPwd.E.Tools.Setup..msi

Specifics for each installer are summarized below

CSE installer

Installs client side GPO extension that maintains password of local admin account. CSE is installed to%ProgramFiles%\AdmPwd\CSE folder

In addition, during CSE installation, the following actions can be performed:

  • Creation of custom local admin account
    • Account receives cryptographically random, complex password 16 characters long, and is made member of local Administrators group
    • Installer performs this action when value of property CUSTOMADMINNAME is set to value other than “__null__”
    • Value can be passed from command line, or via MST file created by tool of choice (such as Orca )
    • Example of command line that installs CSE and creates custom local admin account named CustomAdmin: msiexec /i /q AdmPwd.Setup.Adv.x64.msi CUSTOMADMINNAME=CustomAdmin
  • Reset password of built-in local admin account
    • Account receives cryptographically random, 16 characters long, complex password
    • Installer performs this action when value of property PROTECTBUILTINADMIN is set to “true”

Management tools installer

Installer is designed to install the following components:

  • Management tools:
    • Fat client UI
    • PowerShell module
    • ADMX templates for GPO editor
  • PDS

By default, setup installs just PowerShell module.

Specifics for installed components are described in paragraphs below.

PDS

Installs Password Decryption service. Service is installed to %ProgramFiles%\AdmPwd\PDS folder.

When installing PDS, the following actions are performed:

  • Windows Firewall exception is created, allowing AdmPwd.Service.exe to open endpoint
  • Subfolder CryptoKeyStorage is created under %ProgramFiles%\AdmPwd\Svc folder, and PDS service account (NETWORK SERVICE) receives read/write permission to this folder
    • This is necessary so as PDS could maintain encrfyption/decryption keyss in this folder
  • Registration of event message file PDS.Messages.dll for service with EventLog service
  • Event message file receives additional Read+Execute permission for LOCAL SERVICE. This is needed for Event Log service to be able to load the file

Unattended setup of PDS can be achieved by the following command line: Msiexec /i /q AdmPwd.Setup.Adv.<platform>.msi ADDLOCAL=PDS

Note: During uninstallation, installer does NOT remove any key pairs contained in CryptoKeyStorage folder

PowerShell module

PowerShell module name is AdmPwd.PS. It’s installed to $pshome\Modules\AdmPwd.PS folder.

Module is compiled for use with .NET Framework 4.0. Module is however compatible with .NET Framework 2.0 as well. In case that it needs to be run on machine with only .NET Framework 2.0 installed, custom powershell.exe.config needs to be created if necessary, and needs to create the following config section:

<?xml version="1.0"?> 
<configuration> 
    <startup useLegacyV2RuntimeActivationPolicy="true"> 
        <supportedRuntime version="v4.0.30319"/> 
        <supportedRuntime version="v2.0.50727"/> 
    </startup>
</configuration>

Unattended setup of PowerShell module can be achieved by the following command line: Msiexec /i /q AdmPwd.Setup.Adv.<platform>.msi ADDLOCAL=Management.PS

Fat client UI

Fat cient UI is installed to %ProgramFiles%\AdmPwd\UI.

Unattended setup of Fat client can be achieved by the following command line:

Msiexec /i /q AdmPwd.Setup.Adv.<platform>.msi ADDLOCAL=Management.UI

Fat client supports running from network share; to do so, all files contained in its install folder (without subfolders) need to be copied to network share.

ADMX templates

ADMX templates are installed to %SystemRoot%\PolicyDefinitions folder. Only English US language version of template is delivered as a part of the solution.

In case that organization uses Centralized ADMX template store , templates need to be copied to the Central store manually – the following files:

  • AdmPwd.E.admx
  • En-us\AdmPwd.E.adml

AMX templates deliver the following new UI to Computer part configuration of Administrative Templates GPO:

  • AdmPwd Enterprise: root container for configuration settings
    • Managed clients: configuration settings for managed clients
    • Administrative tools: Configuration settings for management tools

Unattended setup of PowerShell module can be achieved by the following command line:

Msiexec /i /q AdmPwd.Setup.Adv.<platform>.msi ADDLOCAL=Management.ADMX

Management tools

Configuration

In default configuration of solution, management tools do not require specific configuration to be able to communicate with PDS – PDS is automatically discovered using discovery process as described here

However, there may be deployment scenarios that require configuration of management tools. Management tools are configurable via configuration values stored in the following registry path:

HKLM\Software\Policies\Microsoft Services\AdmPwd

Currently the following configuration values are supported:

Value Type Meaning
UseSharedSPN REG_DWORD Setting to non-zero causes management tools to use SPN SVC/AdmPwd when authenticating with PDS
When set to zero or not present at all, management tools use SPN HOST/ when authenticating with the service.
See PDS configuration for more details on when and how to configure PDS to use specific SPN.
Managed by policy “PDS service runs using domain account”
SupportedForests REG_MULTI_SZ List of forests shown in Fat client UI and Web UI.
Managed by policy “AD forests shown in management tools”
PDSList REG_MULTI_SZ List of PDS instances to be used by administrative tools. When this value is specified, management tools do not USE DNS SRV records to discover PDS instances, and rather use instances specified here.
Supported format of values:
<Host FQDN>(Example: host.domain.com)
<Host FQDN>:<Port> (Example: host.domain.com:61185)The latter format can be used when PDS does not listen on default tcp port (61184).
PDS instances are used in order specified in the value
Managed by policy “PDS to be used”

Note: In GPO UI, all configuration settings related to configuration of CSE ale located under Computer configuration/Administrative Templates/LAPS Enterprise/Administrative Tools path

PowerShell module

PowerShell module implements cmdlets as specified in table below:

Cmdlet Description Note
Get-AdmPwdADSchema Returns information about solution specific attributes in AD schema. Useful when finding objectGUID of an attribute Communicates with Active Directory
No specific permissions needed.
Update-AdmPwdADSchema Creates new attributes in AD schema and adds them in may-contain set of computer class
Creates extended rights in configuration partition and makes them applied to computer class
Communicates with Active Directory
Needs Enterprise admin and Schema Admin permission
Get-AdmPwdPassword Retrieves password of local admin account for given computer, optionally with password history Communicates with PDS
Needs Read Admin Password permission
Audited by PDS
Reset-AdmPwdPasword Requests reset of password of local admin account for given computer Communicates with PDS
Needs Reset Admin Password permission
Audited by PDS
Set-AdmPwdSelfPermission Delegates permission to manage password of own local admin account to managed computers Communicates with Active Directory
Needs Write Permissions permission on target container
Set-AdmPwdPdsPermission Delegates permission to interact with AD to service account of PDS Communicates with Active Directory
Needs Write Permissions permission on target container
Set-AdmPwdPdsDeletedObjectsPermission Delegates permission to interact with Deleted Objects container in AD to service account of PDS Communicates with Active Directory
Needs Write Permissions permission on target container
Set-AdmPwdReadPasswordPermission Delegates permission to read local admin password Communicates with Active Directory
Needs Write Permissions permission on target container/object
Set-AdmPwdResetdPasswordPermission Delegates permission to reset local admin password Communicates with Active Directory
Needs Write Permissions permission on target container/object
Update-AdmPwdPasswordHistory Maintains (trims) password history record for given computer based on given criteria Communicates with Active Directory
Needs Read/Write + CONTROL_ACCESS permission on computer object
New-AdmPwdKeyPair Generates new key pair in PDS Communicates with PDS.
Needs Key Admin role in PDS
Audited in PDS
Get-AdmPwdPublicKey Retrieves public part of key pair with given ID from PDS Communicates with PDS
No special permission needed.
Not audited
Get-AdmPwdPublicKeys Retrieves public part of all key pairs managed by PDS Communicates with PDS
No special permission needed.
Not audited
Get-AdmPwdKeySize Gets list of supported key sizes from PDS Communicates with PDS
No special permission needed
Not audited
Get-AdmPwdKeyAdminRoleName Gets the name of AD group implementing Key Admin role Communicates with PDS
No special permission needed
Not audited
Get-AdmPwdUserPermissions Get information about solution permissions specific user has on specific computer object Communicates with PDS
No special permission needed
Not audited
Get-AdmPwdEnvironmentStatus Retrieves information about the environment Communicates with PDS
No special permissions needed
Not audited
Set-AdmPwdPdsManagedAccountsPermission Sets permissions necessary for PDS to manage password for Managed Domain Accounts Communicates with Active Directory
Needs Write Permissions permission on target container
Get-AdmPwdManagedAccountPassword Retrieves password of Managed Domain Account Communicates with PDS
Needs Read Admin Password permission
Audited by PDS
Reset-AdmPwdManagedAccountPassword Resets password of Managed Domain Account Communicates with PDS
Needs Read Admin Password permission
Audited by PDS

Note: For usage of PowerShell commands, refer to cmdlet help that comes with PowerShell module (Get-Help )