Skip to content

README.md

Latest commit

 

History

History
103 lines (80 loc) · 8.53 KB

README.md

File metadata and controls

103 lines (80 loc) · 8.53 KB
Raw

LAPS4LINUX Runner

The runner is responsible for automatically changing the admin password of a Linux client and updating it in the LDAP directory. This assumes that Kerberos (krb5-user) is installed and that the machine is already joined to your domain using Samba's net ads join, PBIS' domainjoin-cli join or the adcli join command (recommended). realm join is also supported as it internally also uses adcli resp. Samba.

A detailed domain join guide is available on my website (attention: only in German).

The runner should be called periodically via cron (example). This does not mean that the password will be rotated every time the cron job runs - it decides by the expiration time stored in the LDAP directory when the password needs to be changed.

Please make sure that usermod (for changing the password in the local database) is in you crontab $PATH (this is the default in Debian and Ubuntu based systems, but may not in other distros).

Installation

It is recommended to use the installation package provided on the Github releases page.

Manual installation in a Python venv:

# install available python modules globally to avoid duplicate install in venv
apt install python3-venv python3-pip python3-setuptools python3-gssapi python3-dnspython krb5-user libkrb5-dev

python3 -m venv venv --system-site-packages
venv/bin/pip3 install .

venv/bin/laps-runner

Configuration

Please configure the runner by editing the configuration file /etc/laps-runner.json.

Configuration Values
  • server: Array of domain controllers with items like {"address": "dc1.example.com", "port": 389, "ssl": false}. Leave empty for DNS auto discovery.
  • domain: Your domain name (e.g. example.com). Leave empty for DNS auto discovery.
  • ldap-query: LDAP filter for getting the computer object, default: (&(objectClass=computer)(cn=%1)). %1 is replaced by the computer name.
  • use-starttls: Boolean which indicates wheter to use StartTLS on unencrypted LDAP connections (requires valid server certificate).
  • ca-certs-file: Path to a CA root certificates file (for TLS validation).
  • tls-validate: TLS validation mode (default: 2 (ssl.CERT_REQUIRED). Valid options are 1 (ssl.CERT_OPTIONAL) or 0 (ssl.CERT_NONE) ).
  • client-keytab-file: The Kerberos keytab file with the machine secret.
  • cred-cache-file: File where to store the kerberos ticket for the LDAP connection.
  • native-laps: true to store the password as JSON string in the LDAP attribute, as specified by Microsoft (Native LAPS). false to store it as plaintext (Legacy LAPS).
  • security-descriptor: The security descriptor (SID) for pasword encryption (Native LAPS only). Leave empty (set to null) to disable encryption. Important: if you enable encryption, you should also change ldap-attribute-password to msLAPS-EncryptedPassword!
  • history-size: The amount of password entries to keep in history. If not set or 0, no password history will be written.
  • ldap-attribute-password: The LDAP attribute name where to store the generated password. Must be a string, not a list.
  • ldap-attribute-password-history: The LDAP attribute where to store the password history. Must be a multi-value text field. If empty, no password history will be written.
  • ldap-attribute-password-expiry: The LDAP attribute where to store the password expiration date. Must be a string, not a list.
  • hostname: The hostname used for Kerberos ticket creation. Leave empty to use the system's hostname.
  • password-change-user: The Linux user whose password should be rotated.
  • password-days-valid: The amount of days how long a password should be valid.
  • password-length: Determines how long a generated password should be.
  • password-alphabet: Determines the chars to use for password generation. Can be either just a character string or a list of character strings. In the latter case, the password contains at least one character from each string.
  • hooks: Dict of commands to execute after password change. The dict key should be a string (displayed in log output) and the value should be an array of parameters. Parameter $PASSWORD$ and $USERNAME$ will be replaced accordingly. Have a look at the sample config file for example hooks. You can use this feature to align other passwords with the local admin/root, e.g. your BIOS/UEFI password or the password of local database admin accounts.
  • pam-services: Array of PAM service names to trigger password rotation (see section "Automatically Rotate Password After Logout" for more info).
  • pam-grace-period: Grace period in seconds after PAM event (e.g. login, logout) until password rotation.

Important:

  • If native-laps is false, you should set ldap-attribute-password to ms-Mcs-AdmPwd and ldap-attribute-password-expiry to ms-Mcs-AdmPwdExpirationTime.
  • If If native-laps is true and security-descriptor not set or null, you should set ldap-attribute-password to msLAPS-Password and ldap-attribute-password-expiry to msLAPS-PasswordExpirationTime.
  • If If native-laps is true and security-descriptor is set to a valid SID in your domain, you should set ldap-attribute-password to msLAPS-EncryptedPassword and ldap-attribute-password-expiry to msLAPS-PasswordExpirationTime.
  • While it is technically possible to save the password history unencrypted, Microsoft did not designated this. By default, in Active Directory, the only password history attribute is msLAPS-EncryptedPasswordHistory. Therefore, you should only configure the runner to store a password history when using password encryption too.

You can call the runner with the -f parameter to force updating the password directly after installation. You should do this to check if the runner is working properly.

Automatically Rotate Password After Logout

If LAPS4LINUX should automatically change the password after logout, you need to add the following line into your PAM config. The exact config file depends on your Linux distribution, e.g. /etc/pam.d/common-session (use /etc/pam.d/common-session-noninteractive if you like to rotate the password on sudo usage too).

session   optional   pam_exec.so type=close_session seteuid quiet /usr/sbin/laps-runner --pam

For Ubuntu, you should use a separate PAM config instead: /usr/share/pam-configs/laps.

Name: LAPS4LINUX configuration
Default: yes
Priority: 0

Session-Type: Additional
Session-Interactive-Only: yes
Session:
        optional pam_exec.so type=close_session seteuid quiet /usr/sbin/laps-runner-pam

Use Session-Interactive-Only: no if you like to rotate the password on sudo usage too.

Then, run pam-auth-update to automatically generate the files under /etc/pam.d/ with the necessary line for LAPS.

You can add login to the array pam-services in the config file if you do not want to change the password on sudo -i usage. Since this config option is an array, this allows you to trigger LAPS on multiple, specific PAM service events.

If you want the runner to wait a certain time after logout until the password should be changed, set pam-grace-period in the runner config to the desired number of seconds, e.g. 300 for 5 minutes.

Hostnames Longer Than 15 Characters

Computer objects in the Microsoft Active Directory can not be longer than 15 characters. If you join a computer with a longer hostname, it will be registered with a different "short name". You have to enter this short name in the config file (setting hostname) in order to make the Kerberos authentication work. You can find out the short name by inspecting your keytab: sudo klist -k /etc/krb5.keytab.

Set the hostname option to null (default) to use the system's normal host name.

Troubleshooting

If the script throws an error like kinit -k -c /tmp/laps.temp SERVER$ returned non-zero exit code 1, please check what happens when you execute the following commands manually on the command line.

sudo kinit -k -c /tmp/laps.temp COMPUTERNAME$
sudo klist -c /tmp/laps.temp

Please replace COMPUTERNAME with your hostname, but do not forget the trailing dollar sign.

Support

If you like LAPS4LINUX please consider making a donation using the sponsor button on GitHub to support further development.

You can hire me for commercial support or adjustments for this project. Please contact me if you are interested.