Skip to content

Installation steps to deploy OpenConext on a single system other than the Vagrant VM centOS7

Jump to bottom Edit New page
Thijs Kinkhorst edited this page Jun 20, 2018 · 40 revisions

Introduction

This document describes how to deploy the OpenConext platform to a host of your own choice. The deployment is done using Ansible, which is run from your local workstation. The host should be provisioned with either Redhat Enterprise 7 or CentOS 7 and needs at least 6 GB of RAM.

Please make sure you have these characteristics of your setup available before you start:

  • target_ip = The ip address or hostname of your target machine, e.g. 192.168.66.100
  • environment = A unique name you are deploying for, e.g. ocdemo, test, qa, acc, prod
  • domain = The domain domain part of your deployment, for example "openconext.org"

Installation steps

  • Prepare your machine
  • Install Ansible
  • Clone Openconext-deploy repository
  • Adapt Ansible hosts hosts-file + setup connectivity to Ansible-target.
  • Create new certificates and passwords
  • Prepare run-books etc
  • Deploy to target
  • Finalize

Prepare your machine

Make sure you have a fresh install of CentOS7, fully updated. Make sure that the firewall is allowing traffic to port 22 (SSH) and 443 (HTTPS) from your local workstation.

Install Ansible

A standard ansible installation must be performed on your local workstation.

Clone Openconext-deploy repository

On your local workstation:

git clone https://github.com/OpenConext/OpenConext-deploy.git

Setup connectivity to the destination host

Make sure you can connect via ssh from the Ansible host to the Ansible target. Preferably using ssh-keys.

Create a new environment

A script is available to provision a new environment. It will create the a new environment directory under environments/ and it will create all necessary passwords and (self-signed) certificates

Replace with the name of the target. Replace with the domain of the target.

./prep-env <environment> <domain>

Prepare run-books etc

cp provision-template.yml  provision-<environment>.yml
cp environments/<environment>/host_vars/template.yml environments/<environment>/host_vars/<target_ip>.yml (where <target_ip> is the ip address or hostname of your target machine, whatever is set in your inventory file)

Change in environments/<environment>/group_vars/<environment>.yml:

  • IP-addresses (search and replace 192.168.66.100)

Change in environments/<environment>/inventory:

  • change all references from %target_host% to <target_ip>

Deploy to target

ansible-playbook -v -i "environments/<environment>/inventory" -u "<username-on-target>" -K provision-<environment>.yml  --extra-vars="secrets_file=environments/<environment>/secrets/<environment>.yml"

Minimal Installation Feature

The deploy playbook contains a feature to forego installation of secondary applications and only install the basic EngineBlock, ServiceRegistry and Profile applications. These form the core of the OpenConext ecosystem. Apply this feature by adding 'minimal_install=1' to the 'extra-vars' when invoking ansible-playbook. For example,:

ansible-playbook -v -i  "environments/<environment>/inventory" -u "<username-on-target>" -K provision-<environment>.yml  --extra-vars="secrets_file=environments/<environment>/secrets/<environment>.yml minimal_install=1"

This feature will prevent the installation of the Shibboleth, Teams, Mujina (IdP and SP), Authz and Voot applications. This also means the basic support for Java and Tomcat is not required (so not installed).

Using this Minimal Installation feature installs the ServiceRegistry application without a federated login enabled. The 'example-auth' module of the embedded SimpleSamlPHP library is enabled and allows local login using the default 'admin' user and the add password as specified in the relevant secrets file under 'janus_ssp_auth_admin_password'.

After specifying a correct IdP in the ServiceRegistry and enabling this IdP for at least the EngineBlock, Profile and ServiceRegistry SPs, the federative-login can be enabled by setting the 'auth' option in /opt/openconext/OpenConext-serviceregistry/simplesamlphp/modules/janus/app/config/config_janus_core.yml from 'example-auth' to 'default-sp'. Optionally, the 'example-auth' module can be removed from the relevant modules directory and from the simplesamlphp/config/authsources.php specification.

Finalize

If you use a public domain, you can add the following entries to the DNS:

welcome.<domain>
apis.<domain>
api.<domain>
authz-admin.<domain>
authz-playground.<domain>
authz.<domain>
db.<domain>
engine-api.<domain>
engine.<domain>
grouper.<domain>
ldap.<domain>
manage.<domain>
mujina-idp.<domain>
mujina-sp.<domain>
multidata.<domain>
oidc.<domain>
pdp.<domain>
profile.<domain>
serviceregistry.<domain>
static.<domain>
teams.<domain>
voot.<domain>

If you want to use your hosts file edit /etc/hosts on target and the machine from which the target is accessed:

<ip-address> welcome.<domain>
<ip-address> aa.<domain> apps.<domain> authz-admin.<domain>
<ip-address> authz-playground.<domain> authz.<domain> db.<domain>
<ip-address> engine-api.<domain> engine.<domain> grouper.<domain> 
<ip-address> lb.<domain> ldap.<domain> mujina-idp.<domain>
<ip-address> mujina-sp.<domain> multidata.<domain> oidc.<domain>
<ip-address> pdp.<domain> profile.<domain> serviceregistry.<domain>
<ip-address> static.<domain> teams.<domain> voot.<domain>

If you are configuring these hosts in DNS, please do not configure IPv6 adresses as the stand alone VM has no v6 configuration.

After 1st run change provision-template.yml on the ansible host:

  • Comment (r41) role: vm_only_provision_eb_sr
  • Comment (r55) vm_only_bootstrap_ldap_attributes
  • Comment (r57) vm_only_bootstrap_ldap_attributes

Please check your firewall settings (iptabels -L) as these were not modified by the install. Access to port 443 is required to use the platform. If your setup did (yet) not allow access to port 443, you may need to restart the Shibboleth service to allow it to fetch metadata from the https://engine.<target>.<domain>

Reboot the target system to make sure all changes has been activated. You should now be able to connect to https://welcome.<domain> to get the OpenConext VM portal page which provides access to all components.

Adding new https certificates to your already installed OC box

Adding a new certificate to the OC box is not too difficult. Even though OC deploys several services, https is terminated at the HAproxy loadbalancers. We only need to update the certificates there.

  • Get yourself a new certificate with either *.yourdomain.org or with all the names in use for the OC services as subject altnames. Having separate certificates on a per service basis is not recommended for a VM setup
  • Make sure you have 1 file containing both the certificate as well as the (intermediate) CA certificate(s), in that order.
  • Copy the file with certificate and CA to the files directory in your environment, environments/<domain>/files/certs. Make sure the cert is named star.<environment>.pem
  • Copy the key of your certificate to the secret file in your environment, environments/<environment>/secrets/<environment>.yml, by replacing the value of the https_star_private_key key. Take care to maintain the indentation of 2 spaces or your yml file will no longer be correctly formatted!
  • Rerun the Ansible deployment scripts for the loadbalancer only, by adding "--tags lb" to the ansible-playbook script
Add a custom footer
Add a custom sidebar
Clone this wiki locally