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
- An OpenAthens personal account under that customer domain for testing
- The EntityID of the IdP for your doman - this can be found in the OpenAthens admin area under Management -> Connections
- Access to a RedHat, CentOS or other yum-based Linux distribution (I'm using a CentOS 7 VM) running httpd and serving content you wish to protect
For the demo I've 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.
We 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
Open the OpenAthens publisher dashboard, 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 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 obtained from the Admin Area
- Click "Save Changes"
- Back on your server, restart Apache httpd to get it to reload the configuration
Now for the moment you've been waiting for!
Visit your protected pages and you should be redirected to OpenAthens.
Log in with the personal account you created and you should be logged.
Congratulations on getting this far! 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. You'll need to get production ready!
If things do not go quite to plan
Sometimes Apache httpd 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.
When creating this guide I ran into a number of issues involving use of certificates and downloading configurations and metadata from HTTPS URLs but we think these are now resolved.
If you get the error:
When visiting the protected pages, then ensure you have changed the Discovery Method as mentioned above (After install section) and also check to see if the EntityID configured has leading or trailing whitespace and remove any you find (this is a beta!).
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 please get in touch and we'll do our best to help you out!