###############################################################################
Ansible Deploy Script for Master Portal
###############################################################################


What are these scripts for?
-------------------------------------------------------------------------------

These scripts are for deploying a Master Portal, Credential Store and SSH host.
To find out more about what this setup is useful for take a look at:
https://wiki.nikhef.nl/grid/RCauth.eu_and_MasterPortal_overview.

You can use these scripts to deploy a Master Portal, Credential Store and SSH
host on different hosts, or on one single host.

Note: the SSH interface consists of 3 parts:
- MasterPortal: an API inside the mp-oa2-server, consisting of two endpoints.
  Managed via roles/masterportal/templates/ssl.conf.j2
- SSH Key portal: like the VO portal, co-hosted a separate TomCat servlet.
  Managed via roles/masterportal/tasks/sshkey-portal.yml and dep-tomcat.yml
- SSH host: typically running on a separate server, the actual SSH server
  contacting the MasterPortal for the list of keys and the credential store for
  obtaining the proxies.
  Managed via separate sshhost.yml playbook.


How to use these scripts?
-------------------------------------------------------------------------------

There are three different plays you can execute. One for the Credential Store
called 'credstore.yml', one for the SSH host call 'sshhost.yml' and one for the
Master Portal called 'masterportal.yml'.

All three plays include the basic role, which takes care of setting up the
environment for these components, including the ip(6)tables rules for all three
hosts. Feel free to further tweak the template, but make sure to keep the
different services reachable. See ./roles/basic/templates/

1. credstore.yml

    This play configures the Credential Server host. Basically, it provides a
    MyProxy Server installation with some configuration.

2. sshhost.yml

    This play configures the special ssh account (and host) that can be used to
    obtain proxy certificates.

3. masterportal.yml

    This play configures the rest of the MasterPortal, including the web
    frontend.

Make sure to check recommended modifications below before starting each play!

In case just the host credentials (hostcert, key and/or CA) are updated, you can
run the notebooks with an extra flag --tags=hostcreds.


Prerequisites
-------------------------------------------------------------------------------

 1. Before you begin executing plays you need to decide whether you're
    deployment will use separate hosts for Master Portal, Credential Store and
    SSH host, or a single host.
    Fill in you machine hostname(s) into the 'hosts.inventory' file accordingly.
    You can set a configdir variable in the inventory, which will be used as
    prefix when including the different _env.yml files described below. This
    makes it easy to have different configurations describing different layouts
    for different inventory files, while still using the same playbooks.
    The hostname(s) set in the invertory files will be set on the target
    machine(s).

 2. You need to have host certificates ready for this deployment. Place your PEM
    formatted certificate(s) and key(s) files in the 'roles/basic/files/'
    directory, with names derived from the inventory_hostname. The basic role
    will take care of deploying these into the target machine.
    It is assumed that your host certificates are issued by the 'TERENA eScience
    SSL CA 3'. If not, you will have to make some modifications to these scripts
    before executing them!

 3. Provide Online CA tar file or RPM for the credstore:
    For using the RCauth CA, make sure to specify ca_RCauth-Pilot-ICA-G1 under
    the trust_anchor_packages in the 'credstore_env.yml' file in the configdir.
    In case of a demo CA, make or get a tarball from that Online CA in pem
    format, together with subject_hash links and signing_policy. It must also
    contain the signing policy, since MyProxy will not work without it.
    Note: the resulting tarball should contain these files at the top level,
    without any directory structure. The tarball should be placed under
    'roles/credstore/files/' and specified under trust_anchor_tarballs.

 4. For supporting pre-selected VOs in the vo-portal, myproxy-server (credstore)
    and sshhost, add the relevant vomses configuration in a directory
    'roles/basic/files/vomses/'. The basic role will take care of copying the
    contents to the host(s) and into /etc/vomses/.

 5. Make sure you have replaced all the relevant .war and .jar .PLACEHOLDER
    files in 'roles/masterportal/files/' with the actual files. See
        https://github.com/rcauth-eu/aarc-master-portal
        https://github.com/rcauth-eu/aarc-vo-portal
        https://github.com/rcauth-eu/aarc-ssh-portal
        https://github.com/rcauth-eu/keyutil
    You can either use the prebuilt released artefacts or rebuild from source.
    For this version of these ansible scripts use the v0.2.1 release of the
    aarc-* components.

 6. The current scripts are using java-1.8.0-openjdk-headless. You can also use
    Oracle Java 8.

 7. You need to create a JSON Web Keys file to replace mp.jwk.PLACEHOLDER file
    in 'roles/masterportal/files/':
    - Create a dummy config file:
       cat > tmp.conf << EOF
       <config>
       <service disableDefaultStores="false"/>
       </config>
       EOF
    - Run the oa2-cli tool locally:
       java -jar ./roles/masterportal/files/oa2-cli.jar -cfg tmp.conf
    - Choose "use keys" then run "create"
    - Choose as filename './roles/masterportal/files/mp.jwk'
      (if you use a different name, set the corresponding name via
      mp_server_jwk_input_file in masterportal_env.yml in the configdir)
    - exit the commandline tool (enter 'exit' twice)
    - remove the 'tmp.conf' and 'log.xml' files
    Lookup the 'kid' in the created file, use e.g. the RS256 key and enter the
    value as 'mp_server_jwk_key_id' in 'masterportal_env.yml'

 8. You need to create the passphrases for the different components.
    This can be done using the secrets.yml playbook. Run it using
        ansible-playbook -e configdir=<path-to-config-dir> secrets.yml
    or set already the right configdir in your inventory file and run
        ansible-playbook -i hosts.inventory secrets.yml

 9. Register a new client in the delegation server of the online CA (i.e. RCauth
    CA or demo CA).
    Go to
        {{ deleg_server_auth }}/register
    where deleg_server_auth should match the URL as set in
    config/*/masterportal_env.yml.
    Use as Callback URL
        https://MASTERPORTAL/mp-oa2-client/ready
    where MASTERPORTAL should match the host as set in the inventory.
    Fill in the resulting client_id and client_secret as mp_client_id and
    mp_client_secret in the secrets_env.yml file in the configdir (see above).

 10. Note that you also will have to fill in the client ID and secret for
    the VO-portal and/or SSH keys portal (when applicable). They can
    obviously only be obtained once the MasterPortal has been installed.
    Hence, after running these scripts for the first time, register two clients
    via
        https://MASTERPORTAL/mp-oa2-server/register
    and choose as Callback URL respectively
        https://MASTERPORTAL/vo-portal/ready
        https://MASTERPORTAL/sshkeys/ready
    where MASTERPORTAL should match the host as set in the inventory
    For the VO portal you want to select the scopes
        email
        edu.uiuc.ncsa.myproxy.getcert
        openid
        profile
        org.cilogon.userinfo
    while for the sshkeys portal you want to select
        openid
        profile
        org.cilogon.userinfo
        eu.rcauth.sshkeys
    Afterwards you can re-run ansible, starting from the task
    "sshkeyportal config file" or "voportal config file"

 11. Make sure to fill in any other required environment variables for each role
     in the configdir _env.yml files.