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:
and they are simple php pages:
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:
- 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
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.
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 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:
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.