Download Source

Downloading the Latest Release

In general, you should download the latest release. This will make it easier to track where your deployment is versus the current development work for purposes of reporting bugs, diagnosing issues, and understanding available features.

Download the COmanage Match source files somewhere into the file system. The location you put the files does not have to be the location from which the files are served by the web server. Create a symlink to the directory called match-current (or something similar):

$ mkdir /srv/comanage
$ cd /srv/comanage
$ wget https://github.internet2.edu/COmanage/match/archive/1.2.1.tar.gz
$ tar xzf 1.2.1.tar.gz
$ ln -s comanage-match-1.2.1 match-current

Downloading Develop

The develop branch is the bleeding edge of the code, and may be useful for getting early access to new features.

$ wget https://github.internet2.edu/COmanage/match/archive/develop.tar.gz

Configure Web Server

Deploy the COmanage Match directory wherever you like. Note that the user that the web server runs as needs to be able to read all the files.

Configure your web server to deliver the match files at a suitable URL such as https://some.edu/match. A simple strategy to accomplish this when running under the Apache web server is to create a symlink in the DocumentRoot named match that points to the directory .../match-current/app/webroot:

$ cd /var/www/html
$ ln -s /path/to/match-current/app/webroot match

The preferred path /var/www or /var/www/html may vary according to your operating system, distribution, or web server configuration.

Installation at /match Currently Required

COmanage Match currently assumes it is installed at the URL path /match. COmanage Match should be made available at https://some.edu/match.

Verify File Permissions

Verify that the web server will not deliver unprocessed files, especially configuration files such as the application configuration file (ie: https://some.edu/match/config/app.php). By default, these files will not be delivered.

Set Up Local State Directories

Two local state directories are required, a tmp directory for transient files (that need not persist long term), and a logs directory for log files (that might be worth keeping in accordance with your log retention policy). Select appropriate locations for these directories, and then link to them from the local directory. eg:

$ sudo mkdir -m 700 /var/cache/match/logs /var/cache/match/tmp
$ sudo chown $HTTPUSER /var/cache/match/logs /var/cache/match/tmp
$ cd match-current/local
$ ln -s /var/cache/match/logs logs
$ ln -s /var/cache/match/tmp tmp

Integrate Web Server Authentication

In order to integrate COmanage Match with your authentication system, configure your Web server to protect the directory match/app/webroot/auth/login. For example, under Apache your configuration may look something like

DocumentRoot /var/www
<Directory /var/www/match/auth/login>
  AuthType shibboleth
  ShibRequestSetting requireSession 1
  Require shib-session
</Directory>
<Location / >
  AuthType shibboleth
  Require shibboleth
</Location>

For Apache, it is recommended that you place this configuration in httpd.conf rather than .htaccess, to simplify future upgrades.

If you choose to use a SAML2 service provider (SP) such as the Shibboleth Native SP or SimpleSAMLPhP for authentication you may find the COmanage Registry Shibboleth Embedded Discovery Service Plugin useful.

Integrate Web Server Logout

COmanage Match uses a standard PHP session to track requests per user. Clicking the "Logout" button ends the PHP session but does not end any other session, such as those created during authentication by the web server authentication mechanism (eg: from the Shibboleth Native SP for Apache or mod_auth_openidc). The web server authentication mechanism should be configured so that any necessary session termination happens when the browser accesses match/auth/logout/logout.php.

For example, with Shibboleth the following configuration will terminate the Shibboleth session and then allow the browser to continue to access the Match logout URL: 

RewriteEngine On
RewriteCond %{QUERY_STRING} !after_redirect
RewriteRule ^/match/auth/logout.* https://%{SERVER_NAME}/Shibboleth.sso/Logout?return=https://%{SERVER_NAME}/match/auth/logout/?after_redirect [L,R]

Next Step

Match Installation - Database