Skip to content

IdP LDAP playbook

Jump to bottom Edit New page
Bruce Becker edited this page May 13, 2015 · 10 revisions

Playbook for deploying and configuring LDAP and Identity Provider

TL;DR ansible-playbook -i <inventory> idp-ldap.yml

These are notes on using the IdP/LDAP playbook.

Fitness for purpose

should you be using this playbook ?

This playbook has been designed for the deployment from quasi-initial-state of an LDAP server and Shibboleth Identity Provider, in the context of the ei4Africa project.

Prerequisites

You need two services - best placed on two different public IP's.

  1. LDAP server
  2. Shibboleth Identity Provider

Quick-start

If you'd like to get up and running quickly, here's a quick step-by-step guide to using the playbook.

  1. Get Ansible
  2. Define your inventory
  3. Define relevant variables for your site
  4. Install vanilla OS on target machines and ensure that networking is working.
  5. Execute the playbook

Below, we will describe in detail the steps.

Detailed guide to using the LDAP and IdP roles.

First, you would do well to do some background reading :

Get Ansible onto your control host.

You will need to run Ansible playbooks from a control machine This can be the machine you are trying to configure itself (using local connection), or on your laptop or some other trusted machine, using some form of ssh as remote connection. In general, Ansible only requires ssh to connect to the managed machines.

Read the Ansible documentation and decide on the best way to install Ansible on the machine that you will use for executing playbooks.

Define your inventory

An Ansible inventory is a prerequisite to running a playbook and defines not only the content, but also the topology of your servers. We provide a wide set of inventories for the various sites (and you can contribute yours) at https://github.com/AAROC/DevOps/tree/master/Ansible/inventories

As of v0.0.3, there are two different host groups that the playbook will act on -

  • ldap-server - the host which runs the LDAP directory.
  • shibboleth-idp - the host which runs the Shibboleth Identity Provider.

These may in principle be the same or different hosts. You also should tell Ansible which hosts are EL and Debian machines. A sample inventory looks like :

[ldap-servers]

[shibboleth-idps]

[CentOS-servers]

[Debian-servers]

[identity-all:children]
ldap-servers
shibboleth-idps

Define relevant variables at your site.

The power of Ansible comes from its ability to apply generic models to specific cases, with site customisation. This customisation comes primarily from the setting of variables, which get used to change file templates, service names, etc from host to host and from site to site. Before going on, take some time to read how Ansible deals with variables, especially how it deals with variable precendence.

The roles which we have developed have some sane defaults, but note : the playbooks will NOT work unless you provide correct variables for your site. While we make some effort to ensure that there is an almost-exhaustive list for you to refer to here, Ansible's power is also due to it's flexibility and there are many, many ways to customise playbooks through facts or extra variables. If you stick to the 'mandatory variables' below in getting started, you should be fine (if not, open a ticket).

Variables come from various places :

  • group_vars : variables assigned to groups of hosts as defined in your inventory
  • role-x/vars : roles that take precendence within the role being executed
  • role-x/defaults : default values of variables that are provided by the developer (usually insane).

Mandatory Variables

Variable descriptions are contained in the files themselves. If you need to customise these variables site-per-site, you can override them on the command line, or in the group_vars variable files relevant to your site. For example when wanting to customise an ldap installation, the playbook will take variables from https://github.com/AAROC/DevOps/blob/master/Ansible/roles/ldap/vars/main.yml. You can change these according to your site. Remember that variables in roles/x/vars/main.yml are only overridden by variables passed on the command line (which probably means we need to do a bit of cleaning up of the code, moving stuff from vars to defaults).

Install OS

We do not have playbooks for installing Operating Systems - you will have to do that yourself. The reason is that there is no generic way of doing this and sites differ widely on how they provision machines. We suggest using a cloud manager like OpenStack or OpenNebula to provision machines. We support EL6 and Debian 6 with these playbooks.

Note that you will need to have proper network communication between the hosts (if the services are running on separate hosts), which means :

  • DNS lookups should be working
  • ssh ports open
  • http access to the internet for package updates

Also, make sure that SELinux is disabled.

We have provided a playbook which will bring your vanilla machines to a state where the idp-ldap playbook can be run against them. See : https://github.com/AAROC/DevOps/blob/master/Ansible/bootstrap.yml and the bootstrap role. Note that this is not guaranteed to work and some of the tasks may run counter to site policies.

Execute the playbooks.

Once you have prepared the inventory, variables and hosts, you can run the playbook :

ansible-playbook -i <inventory> idp-ldap.yml

The playbook itself is very simple, acting on two hosts in the inventory, applying 4 roles:

---
- name: Configure the LDAP machine
  hosts: ldap-server
  remote_user: ansible
  sudo: true
  roles:
  - ldap

- name: Prepare the identity machine common environment
  hosts: shibboleth-idp
  remote_user: ansible
  sudo: true
  roles:
  - fmarco76.tomcat
  - shibboleth-idp
  - fmarco76.IDPPublic

The playbook uses a generic user ansible to connect to the machines, executing tasks on the remote side with sudo. This user is created and configured by the bootstrap play referred to above.

Congrats ! (best check though)

Well done, you have a working Shibboleth IdP and LDAP installation ! Now, there are some things you can check to satisfy your skepticism that things are actually working fine. The ticket for reporting or suggesting further testsis #98.

LDAP functional tests

These are some functional tests that should be run before putting the service into production[^WIP]

  1. Can you access the LDAP server locally ? 1. Check: run ldapsearch on the dc=local branche

Workarounds

Look, this is pretty awesome stuff, but nobody's perfect ! Given the limited manpower and time we can dedicate to this project, there are going to be some moments when you just need to make a minor tweak. If you end up running this playbook and - heaven forbid ! - you don't end up with a perfectly-configured shiny new identity service, 😲 then here are the workarounds that we have found to work.

Common Issues and Troubleshooting

During the course of a few installations, we have come across a few common issues that seem to be happening. You can find them here

[^WIP]: As of 02/2015 this is still a work in progress and we expressly state that these have to be done manually. Yes, robots will take over this in the future.

for more information on what's going on, see the ROC webpage.

Quick Links

Clone this wiki locally