This space contains the old OpenAthens SP documentation and is no longer maintained.
OpenAthens SP software is already out of support and will reach end of life in May 2020.

Check out OpenAthens Keystone instead. It's supercool and makes dealing with SAML much easier.

Search

Skip to end of metadata
Go to start of metadata

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:

  • An OpenAthens customer domain and access to the OpenAthens admin area (https://admin.openathens.net)
  • An OpenAthens personal account under that customer domain for testing
  • The EntityID for your doman - this can be found in the OpenAthens admin area under Management > Connections
  • Access to a Linux server that uses the rpm package manager - e.g. RHEL, CentOS, etc. We used CentOS 7 VM in the preparation of this guide

For the demo I have set up the following pages:

Simple Web Page Structure
/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:

Public Page
<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>
Private Page Showing OA Attributes
<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:

  • Click the register new application button and choose OpenAthens SP in the dialogue box
  • Name your application. Eventually this will be customer facing, but for now it can be anything
  • Application URL: this is the root web address of the application - e.g: https://sp.yourdomain.com
  • Leave 'users in my domain' ticked, but keep the other options unticked
  • Click the create button. This creates the application record and a connection

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:

  • Click Applications
  • Select your newly created application
  • Open the Configuration tab
  • Under "Discovery Method" select "Use default identity provider" and in the text box below put the Entity ID you obtained earlier
  • Click "Save Changes"
  • Back on your server, restart Apache httpd to get it to reload the configuration

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.

 

  • No labels