Skip to content
This repository has been archived by the owner on Apr 11, 2023. It is now read-only.

Home

Jump to bottom
Jeremy Nicklas edited this page Jul 12, 2016 · 24 revisions

Documentation Guide

The Open OnDemand Project is an open-source software project, based on the Ohio Supercomputer Center's proven "OSC OnDemand" platform, that enables HPC centers to install and deploy advanced web and graphical interfaces for their users. More information can be found in the paper http://dx.doi.org/10.1145/2949550.2949644.

Components

Details of the components that make up the Open OnDemand infrastructure.

Proxy and PUN

The core of the infrastructure includes a proxy layer that all traffic passes through using the securely encrypted SSL protocol on port 443. The Apache proxy parses the URI and dynamically determines where to route the traffic to. In most cases the traffic will be routed to the per-user NGINX (PUN) web server.

The PUN is described as an NGINX server instance running as a system-level user listening on a Unix domain socket. File and directory permissions are used to restrict access to this Unix domain socket such that only the proxy daemon can communicate with the PUN.

Component Description
ood-portal-generator Generates an Open OnDemand portal config for an Apache server that defines the proxy interface.
mod_ood_proxy An Apache httpd module implementing the Open OnDemand proxy API.
nginx_stage Stages and controls the per-user NGINX (PUN) instances.

Authentication and Authorization

There is no required authentication mechanism built-into Open OnDemand, but we do provide a recommended solution. The recommended solution utilizes the mod_auth_openidc module within the Apache proxy to authenticate users against an OpenID Connect Provider for federated authentication.

After the user authenticates with their OpenID Connect Provider authorization is granted by mapping the user's authenticated username to a local system username. The Apache proxy handles this by calling a script that handles the user mapping lookup. If the mapping fails, the user can be taken to a registration page where he or she can set up a mapping.

Component Description
mapdn Scripts to setup/maintain mappings between Distinguished Names (DNs) to local usernames.
ood_auth_map The user mapping script employed by OSC for OnDemand and AweSim.
ood_auth_discovery Open ID Connect Discovery page for OSC OnDemand.
ood_auth_registration OSC OnDemand Open ID Connect registration page.

Installation Guide

Work in Progress

Assumes you are using Software Collections

Generate Apache Config for Open OnDemand Portal

In this section we will generate an Open OnDemand Portal config file used by the Apache server. This can be done manually or using the ood-portal-generator.

  1. We clone the ood-portal-generator repo to the local disk:

    git clone [email protected]:open-ondemand/ood-portal-generator.git
cd ood-portal-generator

  2. Check out the version of the generator you intend on using:

    # A list of versions & details can be viewed in the CHANGELOG.md
# As of writing this the latest version is `v0.0.1`
git checkout tags/v0.0.1

  3. Now we build the Apache config using environment variables to modify any of the default settings:

    scl enable rh-ruby22 -- rake

    Documentation on the available options can be found at:

    https://code.osu.edu/open-ondemand/ood-portal-generator#default-options

    SUBDOMAIN -- If a subdomain or different IP address is used (assuming the SSL certificates are setup as well for this subdomain):

    scl enable rh-ruby22 -- rake OOD_IP=<ip> OOD_SERVER_NAME=<subdomain>

# Example:
scl enable rh-ruby22 -- rake OOD_IP='xxx.xxx.xxx.xxx' OOD_SERVER_NAME='ondemand.osc.edu'

  4. Confirm the Apache config is to your liking by viewing the config file generated:

    cat build/ood-portal.conf

  5. Install it to its global location:

    sudo scl enable rh-ruby22 -- rake install
# => /opt/rh/httpd24/root/etc/httpd/conf.d/ood-portal.conf

  6. If using recommended OOD authentication, be sure to setup the OpenID Connect Discovery Provider information needed by the mod_auth_openidc Apache module:

    https://code.osu.edu/open-ondemand/ood-portal-generator#cilogon-setup

    For CILogon you will need to register a new redirect URI for every host machine you install an OOD Portal on.

Note: This package references the location of mod_ood_proxy, nginx_stage, and osc-user-map. It is the source of knowledge for the locations of the various OOD infrastructure pieces. Be sure to update these locations if you change the PREFIX for any installation of the corresponding package.

Install Open OnDemand Proxy Module for Apache

An Apache module written in Lua is the primary component for the proxy logic. It is given by the mod_ood_proxy project.

  1. We clone the mod_ood_proxy repo to the local disk:

    git clone [email protected]:open-ondemand/mod_ood_proxy.git
cd mod_ood_proxy

  2. Check out the version of the generator you intend on using:

    # A list of versions & details can be viewed in the CHANGELOG.md
# As of writing this the latest version is `v0.0.1`
git checkout tags/v0.0.1

  3. Install it to its global location:

    sudo scl enable rh-ruby22 -- rake install
# => /opt/ood/mod_ood_proxy

Install the PUN Utility

The PUNs are manipulated and maintained by the nginx_stage utility. This tool is meant to by run by root or a user with sudoers privileges.

  1. We clone the nginx_stage repo to the local disk:

    git clone [email protected]:open-ondemand/nginx_stage.git
cd nginx_stage

  2. Check out the version of the generator you intend on using:

    # A list of versions & details can be viewed in the CHANGELOG.md
# As of writing this the latest version is `v0.0.7`
git checkout tags/v0.0.7

  3. Install it to its global location:

    sudo scl enable rh-ruby22 -- rake install
# => /opt/ood/nginx_stage

  4. Modify /opt/ood/nginx_stage/config/nginx_stage.yml and /opt/ood/nginx_stage/bin/ood_ruby.

    In particular, opt into metrics reporting in nginx_stage.yml and use Software Collections in ood_ruby.

    Note: These files will not be overwritten the next time you update nginx_stage.

  5. If not already done, give the apache user sudo privileges to run this tool:

    # /etc/sudoers

Defaults:apache     !requiretty, !authenticate
apache ALL=(ALL) NOPASSWD: /opt/ood/nginx_stage/sbin/nginx_stage

[Authentication] Install User Mapping Script

If you are using the OOD recommended authentication procedure you will need to map the Apache authenticated user to the local system user. This is done with the simple tool: ood_auth_map.

  1. We clone the ood_auth_map repo to the local disk:

    git clone [email protected]:open-ondemand/ood_auth_map.git
cd ood_auth_map

  2. Check out the version of the generator you intend on using:

    # A list of versions & details can be viewed in the CHANGELOG.md
# As of writing this the latest version is `v0.0.1`
git checkout tags/v0.0.1

  3. Install it to its global location:

    sudo scl enable rh-ruby22 -- rake install
# => /opt/ood/ood_auth_map

The principle behind this script is that you call it with a URL encoded REMOTE_USER user name as the only argument, and it will return the mapping to the local system user name if it exists. This requires the availability of the /etc/grid-security/grid-mapfile (more information).

[Authentication] Deploy the Discovery Page

Before a user is authenticated, the user is presented with a discovery page where he/she can choose the OpenID Connect Provider. For the ood_auth_discovery repo it is a branded page with a link to CILogon.

  1. We clone the ood_auth_discovery repo to the local disk:

    git clone [email protected]:open-ondemand/ood_auth_discovery.git

  2. Install it to its global location:

    # create the /var/www/ood directory if it doesn't already exist

# copy this repo to its default location
sudo cp -r ood_auth_discovery /var/www/ood/discover

[Authentication] Deploy the Registration Page

After a user is authenticated and it is determined that no mapping exists to a local system user, they are redirected to the ood_auth_registration branded page. Here the user is required to enter their local system credentials and the mapping is generated.

  1. We clone the ood_auth_registration repo to the local disk:

    git clone [email protected]:open-ondemand/ood_auth_registration.git

  2. Install it to its global location:

    # create the /var/www/ood directory if it doesn't already exist

# copy this repo to its default location
sudo cp -r ood_auth_registration /var/www/ood/register

  3. This repo makes use of a securely encrypted ldaps://... server for authenticating a user to the local system. This requires the appropriate OpenLDAP Certificate Authority files be hosted on the local machine:

    /etc/openldap/cacerts/*

  4. This repo also generates a proper user mapping after the user authenticates successfully on the local system. So the apache user will need permissions to generate this mapping on behalf of the user. This requires granting the apache user sudo privileges to the respective mapdn script.

    # /etc/sudoers

apache      ALL=(ALL) NOPASSWD:  /usr/local/bin/add-user-dn.real, \
                                 /usr/local/bin/delete-user-dn.real, \
                                 /usr/local/bin/list-user-dns.real

[Authentication] Deploy Mapping Helper Scripts

FIXME

App Deployment Strategy

Clone this wiki locally