This is a simple "Hello, world" guide to getting started as a Service Provider with OpenAthens using the Apache httpd module.

We'll use a simple Web site with two pages - a welcome page and a page that will be protected by OpenAthens at a different path on the Web server. The same principles apply with a complex dynamic site or even a CMS provided the content is served using Apache httpd.

Before you begin you will need:

For the demo I have set up the following pages:

/var/www/html/index.php - unprotected home page content
/var/www/html/secrets/index.php - content you need to log in to see

and they are simple php pages:

<html>
  <head>
    <title>OpenAthens SP Hello World</title>
  </head>
  <body>
    <h1>OpenAthens SP Hello World</h1>
    <p>This is a public page. If you have an account you can view the
       <a href="/secrets"> protected pages</a>.</p>
    <hr />
  </body>
</html>
<html>
  <head>
    <title>OpenAthens SP Hello World</title>
  </head>
  <body>
    <h1>OpenAthens SP Top Secret Hello World Pages</h1>
    <p>This is a private page.</p>
    <p>You are logged in as <?php print getenv('OA_USERNAME') ?></p>
    <hr />
    <?php
     // OpenAthens attributes are set as environment variables when using
     // Apache and they are prefixed "OA" - let us see what we get!
     foreach($_SERVER as $key => $value) {
        if(substr($key, 0, 2) == 'OA') {
          print "<b>$key</b> -&gt; $value <br />\n";
        }
      }
    ?>
  </body>
</html>

What are we going to do?

Your OpenAthens customer domain will act as Identify Provider in this example and you may use this for testing. Your Web server will act as the Service Provider.

You are going to register your Service Provider as an Application in the Publisher dashboard and then use OpenAthens SP software to protect your content.

Create the application in the OpenAthens publisher dashboard

Go to https://sp.openathens.net, sign in and follow these steps:

Follow the dashboard guide

Assuming that all went well you are now presented with a guide on your next steps.

At the top of the page is a drop-down that lets you choose which version of OpenAthens SP you want to use.

For this guide, ensure that "Apache" is selected and follow the instructions provided.

After the dashboard guide

We're not done yet - we must also associate the new Application with an identity provider. We will use your OpenAthens customer domain as identity provider for testing and you'll need the Entity ID of the Identity Provider. This can be found in the OpenAthens admin area under Management > Connections.

Armed with your entity ID open the OpenAthens publisher dashboard and do the following:

Try it

Visit your protected pages and you should be redirected to OpenAthens.

Log in with the personal account you created and you should be logged in.

What next?

At the moment your service provider is only connected to your customer domain. For very small applications that may be all you need, but it is more likely you'll want to join the federation as soon as possible and for that you will need to get production ready.

If things do not go quite to plan

Sometimes Apache may not start once you've installed OpenAthens SP and configured httpd. If this happens check the httpd configuration for typos, etc.

If it looks good, check to see if the folders for the logs and OA temp directory referenced in the configuration exist and are writable by the httpd process.

Also try curl or wget to the configuration server - referenced in the OAConfig directive - if that fails, the error may indicate a network problem, firewall block, etc.

 

If you get the error:

Unable to locate entity in metadata: (null)

When visiting the protected pages, then ensure you have changed the Discovery Method as mentioned above (After install section).

Finally you may, if you are very lucky or very experienced with SAML, find something useful in the log files as configured in the httpd configuration.

If you are still having issues our service desk will be happy to help.