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

Introduction

This document describes how to deploy the OpenConext platform to a host of your own choice. The deployment is done using Ansible. The host should be provisioned with either Redhat Enterprise 7 or CentOS 7 and needs at least 4 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

• 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

Install Ansible

A standard ansible installation must be performed.

Clone Openconext-deploy repository

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)

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

• IP-addresses (search and replace 192.168.66.100)
• Email-address (search and replace root@localhost)

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"   

Allow access to authz-admin interface

If you plan to use the OAuth component, you need administrative access to the authz-admin interface (accessible at https://authz-admin.. You need to manually create a team in order to be able to access it with the name authz_admins. To do this, please follow these steps:

• Login to the teams web interface. Go to https://teams., and click "login". Enter admin/admin in Mujina and continue
• Click on "add team".
• Use "authz_admins" as team name, and tick the two checkboxes.
• Click on create, and you should now be member of the team "authz_admins"
• You can now access the authz_admin administrative interface.

This will be automated in the future.

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..

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

Adding new https certificates to you 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 servcies as subject altnames. Having seperate vertificates on a per service basis is not recommended for a VM setup
• Make sure you have 1 file containing both the certificate as wel as the (intermediate) CA certificate(s), in that order.
• Copy the file with certificate and CA to the files directory in your environment (environments//files/certs). Make sure the cert is named .pem
• Copy the key of your certificate to the secrest file in your environment (environments//secrets/.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