Support

Subscribe to ae-dir-users and get informed about news.
If you need more help please consider commercial support.

Prerequisites

Make yourself familiar with the system architecture.
Install Æ-DIR servers with one of the supported operating systems. Currently the ansible playbooks support fully automated installation/configuration on…
- openSUSE Tumbleweed
- openSUSE Leap 15.0+
- SUSE Linux Enterprise Server 15 (to be tested)
- Debian Stretch using OpenLDAP packages from Debian APT repository of LTB project
- CentOS 7.4+ using OpenLDAP packages from YUM repository of LTB project
If you want to tweak the ansible roles to install on another OS make sure a recent OpenLDAP 2.4.44+ with overlay slapo-deref is available for your OS platform. Older releases are explicitly not recommended!
The ansible roles needs the following software packages on all target machines to be installed:
- Python 2.x
- python-xml
- lsb_release command (package lsb-release)
Install on your admin workstation (the ansible controller):
- ansible 2.4+ (Use Jinja2 2.8.x! ansible has some issues with 2.9+!, see issue 20063)
- git
- dnspython
Simple approach:
```
      # virtualenv-2.7 /opt/ansible
      # /opt/ansible/bin/pip2 install --upgrade ansible Jinja2==2.8.1 dnspython paramiko
    
```
Create DNS entries for all your Æ-DIR servers following best practices for hostnames.
Configure time synchronisation (NTP) required for reliable replication.
Prepare to have SSH access to all Æ-DIR servers as user root (via su or sudo)
Make yourself familiar with how to use command-line options for ansible become.
Check whether you can access the hosts with ansible setup:
```
/opt/ansible/bin/ansible all -i 'hostname.example.com,' -m setup
```
The trailing comma after the FQDN is needed when using a hostname!

Get the ansible playbooks and roles:

git clone --recurse-submodules https://gitlab.com/ae-dir/ansible-example-site myenv

Issue X.509 TLS server certificates with appropriate CN and subjectAltName values for all replicas with your existing PKI's certificate authority.
The anti-security concept of wild-card certificates is not compatible with Æ-DIR's security concept! Therefore these cannot be used!
If you don't have a PKI yet you can setup a test certificate authority (CA) with shell scripts found in tools/pki-scripts/.

Installation

Edit ansible inventory file myenv/hosts to match your hosts/VMs/containers of your installation environment.
Read comments in file myenv/roles/ae-dir-server/defaults/main.yml and adjust ansible group and host vars to match your environment.
Invoke ansible play in sub-directory ansible/ (here using command su):
```
/opt/ansible/bin/ansible-playbook ae-dir-servers.yml -i myenv/hosts --become -K --become-method=su --extra-vars='{"aedir_init":True, "openldap_keygen":True}'
```
- At first run this will generate TLS server key and signed CSR file and stops with a message where to find the CSR files on your local ansible controller.
- After signing the CSRs with your CA place the server certificate file(s) into directory ae-dir/ansible/myenv/files/.
- Invoke ansible-playbook command above again to proceed with installation.
Log into one provider system become user root and run the following commands to fully initialize your directory:
1. Add the basic Æ-DIR entries with OpenLDAP command-line tool:
  - On SUSE / openSUSE:
```
ldapmodify -f /opt/ae-dir/etc/ae-dir-base.ldif
```
  - On Debian and CentOS:
```
/usr/local/openldap/bin/ldapmodify -f /opt/ae-dir/etc/ae-dir-base.ldif
```
2. Set the user password of an initial Æ admin (here msin):
```
/opt/ae-dir/bin/ae-passwd.py msin
```
Check the systems' health by invoking as root the monitoring script on all Æ-DIR servers. By default it is installed to:
```
/opt/ae-dir/sbin/slapd_checkmk.sh
```

For PAM/NSS client self-integration invoke ansible play in sub-directory ansible/ (here using command su):

/opt/ansible/bin/ansible-playbook ae-dir-clients.yml -i myenv/hosts --become -K --become-method=su -l ae-dir-servers

Two-factor authentication (OATH-LDAP)

You can easily use the built-in two-factor authentication based on OATH-LDAP.

This is enabled by setting ansible variable oath_ldap_enabled: True and then play the complete configuration to the Æ-DIR servers. Of course you set this flag also before the first run. This installs an additional web app and the so-called bind listeners on providers and consumers.

Afterwards you have to generate at least one master key pair for protecting the token shared secrets (OTP seeds):

# oathldap-tool genkey --key-path /opt/ae-dir/etc/oath-master-keys/
Generating RSA-2048 key pair...

wrote /opt/ae-dir/etc/oath-master-keys/oathldap_master_key_201806141818.priv
wrote /opt/ae-dir/etc/oath-master-keys/oathldap_master_key_201806141818.pub

Correct the permissions if needed which would also be done by next ansible play:

# chmod 640 /opt/ae-dir/etc/oath-master-keys/oathldap_master_key_201806141818.*

Then store the new public key in the OATH parameters entry:

# ldapmodify <<EOF
dn: cn=oath-policy-hotp-users,cn=ae,ou=ae-dir
changetype: modify
replace: oathEncKey
oathEncKey:< file:/opt/ae-dir/etc/oath-master-keys/oathldap_master_key_201806141818.pub

EOF

Copyright & License

  Licensed under the Apache License, Version 2.0 (the "License"); you may
  not use files and content provided on this web site except in compliance
  with the License. You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.

Software / technology used