Child pages
  • COmanage Registry Installation (CentOS)
Skip to end of metadata
Go to start of metadata

Overview

The steps listed here are the minimum required to get a functional instance of COmanage Registry up and running, so you can see how it works with the Shibboleth SP. If you're interested in deploying COmanage Registry in production, please refer to the official documentation.

 

Download and Install COmanage Registry

  • Download a stable release of COmanage Registry (note: version 2.0 is now available, but not yet tested with these instructions):

    cd
    curl -LO https://github.com/Internet2/comanage-registry/archive/1.0.6.tar.gz
  • Extract the tar file:

    cd /opt
    tar xzvf /root/1.0.6.tar.gz

    You should now have a directory /opt/comanage-registry-1.0.6, which contains all of the files in the distribution. Next, create a couple of symbolic links to facilitate configuration and make the application visible to the web server:

    ln -s /opt/comanage-registry-1.0.6 /opt/registry-current
    ln -s /opt/registry-current/app/webroot /var/www/html/registry
  • COmanage Registry needs a temporary directory to store cached files, logs, etc. The directory must be writable by the web server. Set a temporary directory up as follows:

    cd /opt/registry-current/app
    cp -r tmp.dist /var/cache/registry
    chown -R httpd /var/cache/registry
    chmod 700 /var/cache/registry
    cd /opt/registry-current/local
    ln -s /var/cache/registry tmp

Install Prerequisite Packages

COmanage Registry is written in PHP, and requires several PHP modules, as well as a local database. For this installation, we'll use MariaDB, which is a drop-in replacement for MySQL that ships with CentOS 7.

yum install php-xsl php-mysql php-ldap mariadb mariadb-lib mariadb-server

Next, start the database server and run the mysql_secure_installation script:

systemctl enable mariadb
systemctl start mariadb
mysql_secure_installation

The script will prompt you to set a password for the 'root' database user. Choose a secure password, and remember it for later. You can accept the default option at each of the subsequent prompts.

Configure the Web Server

Edit /etc/httpd/conf/httpd.conf, and add the following sections.

<Directory "/var/www/html/registry">
    Options Indexes FollowSymLinks
    DirectoryIndex index.php
    AllowOverride all
    Order allow,deny
    Allow from all
</Directory>

This section enables Shibboleth authentication:

<Directory "/var/www/html/registry/auth/login">
    AuthType shibboleth
    ShibRequestSetting requireSession 1
    require valid-user
</Directory>

Finally, add a redirect to handle logout:

Redirect /registry/users/logout https://my.special.name/Shibboleth.sso/Logout?return=https%3A//my.special.name/registry/

Don't forget to substitute your chosen hostname for my.special.name in the above example.

 

Configure the Database

First, you'll need to create a database for the registry tables. Don't forget this step, or you will get an unhelpful error message when you run the script to populate the schema.

mysql -p -e "create database registry"

Next, create a local copy of the default database configuration file:

cd /opt/registry-current/app
cp Config/database.php.default ../local/Config/database.php

Then, edit the resulting database.php file, and make the following changes:

  • Set 'login' to 'root' (Note: for a production installation, you'll want to create a separate, non-privileged user.)
  • Set 'password' to the top-secret password you chose when you ran the mysql_secure_installation script earlier
  • Set 'database' to registry

Finally, run the script to create the database schema:

./Console/cake database

You should see the message "Database schema update successful", possibly intermingled with other output.

Set Up an Administrative User

Almost finished! Now, we just need to "bootstrap" the registry by adding an administrative user. As you did earlier, you'll be logging in via the InCommon Training IdP, which has three pre-existing users: student1, staff1, and faculty1. Choose any of these (it doesn't matter which you use).

COmanage checks the identity of the authenticated user by looking at the REMOTE_USER environment variable. For this demonstration, we'll want to make sure that REMOTE_USER is populated with the user's eduPersonPrincipalName (ePPN). The ePPN is just the user's login name with a "scope" appended, e.g. "user@scope". The training IdP uses example.org as its scope, so typical ePPNs will look like student1@example.org, staff1@example.org, or faculty1@example.org.

You may recall that the SP can be configured to populate REMOTE_USER with any attribute it receives from the IdP. ePPN is the default, but to be safe, you should verify this. It's configured in /etc/shibboleth/shibboleth2.xml, in the <ApplicationDefaults> element. Look for the REMOTE_USER attribute, and ensure that "eppn" is the first item in the space-delimited list:

<ApplicationDefaults entityID="https://my.special.name/shibboleth
                     REMOTE_USER="eppn persistent-id targeted-id">

When you're ready, run the registry configuration script. You can enter any values for given name and family name, but make sure the login username is of the form username@example.org. It needs to match the ePPN that the IdP sends in the assertion.

cd /opt/registry-current/app
./Console/cake setup
Enter administrator's given name
> Joe
Enter administrator's family name
> Student
Enter administrator's login username
> student1@example.org
Enable organization identity pooling? (Yes/No)
[No] > No

 

Test the Installation

You're now ready to test the installation:

  • Restart Apache (systemctl restart httpd)
  • Browse to https://my.special.name/registry
  • Click the "Login" link
  • Log in via the Training IdP, using the username that you configured as the administrative user

If all goes well, you should see the COmanage Registry Dashboard, with the logged-in user identified in the top right corner of the page.

Resources

  • No labels