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

Prerequisites

  • A server running .NET and IIS
  • Server time synced with NTP or equivalent
  • Familiarity with your chosen platform
  • Access to the publisher dashboard.

Method

The application is 32bit. For brevity, all quoted file-paths assume a 64bit environment and default install location.

  1. Install OpenAthens software

    1. You can get the software from our service desk (athenshelp@eduserv.org.uk) 

  2. Generate or install a metadata signing certificate - most federations allow these to be self-signed and last several years. To generate a key-pair, run the script in the keys folder:

    C:\Program Files (x86)\Eduserv\OpenAthens.Net\keys\gen_self_signed_cert.bat

    For details, or to import a pre-existing key pair, see: Install metadata signing certificates on .NET

  3. If you have not already done so, create an application in the publisher dashboard. You will have the opportunity to paste in the signing certificate you generated in the previous step.when you set it up

    1. If this is for an existing application, open the application details and go to the getting started tab of the application details to add this certificate.

  4. The dashboard will provide text to copy and paste in these two areas of your web.config file:


    1. Referencing the OpenAthens.Net.dll assembly in the <compilation> section, e.g:

      <compilation>
        <assemblies>
          <add assembly="OpenAthens.Net,Version=1.0.0.0, Culture=neutral, PublicKeyToken=17390934318f9b06"/>
          <add assembly="atacama.net, Version=2.1.3.0, Culture=neutral, PublicKeyToken=6E679382149F5665"/>
        </assemblies>
      </compilation>
      
    2. Referencing your OpenAthens configuration published by the publisher dashboard in the <configuration> section (in a single line), e.g:

      <openAthens atacamaConfig="https://sp.openathens.net/configurations?id=XxXxXxXxXxXxXxXxXx" accessKey="xxxxxxx-xxxxxx-xxxxxx-xxxxxx" logConfig="C:\Program Files (x86)\Eduserv\OpenAthens.Net\conf\defaultLogConfig.xml"/>
  5. Still in the web.config file, define an openAthens section name under <configSections> - e.g:

    <configSections>
      <section name="openAthens" type="Eduserv.OpenAthens.OpenAthensConfigSection"/>
    </configSections>
  6. You can then define the OpenAthens enabled area in the <configuration> section of your web.config file, e.g:

    <location path="Protected.aspx">
      <openAthens>
        <authentication enabled="true"/>
      </openAthens>
      <system.web>
        <authorization>
          <deny users="?"/>
        </authorization>
      </system.web>
    </location>

    (The enabled section could be the whole restricted section of your site, but might just be necessary to integrate part of your existing authorisation section, depending on whether your existing code will handle returning the user to the target page they were originally trying to access) 

  7. Next integrate OpenAthens SP with the ASP.NET pipeline. How this is done will depend on the version of IIS and which mode it is in. We will assume integrated mode here, as that is most common, and that it is set such that all requests are channelled through the pipeline. In such cases you need only add a line to your web.config in the <system.webServer> section to include OpenAthens SP, e.g:

    <system.webServer>
      <modules runAllManagedModulesForAllRequests="true">
        <add name="OpenAthensServerModule" type="Eduserv.OpenAthens.ServerModule"/>
      </modules>
    </system.webServer>

    If you need to use classic mode, see: Integrating OpenAthens with the ASP.NET pipeline in IIS classic mode

  8. Check folder permissions to ensure the IIS user can access them:

    1. OpenAthens software, typically in C:\Program Files (x86)\Eduserv\OpenAthens.Net. The IIS_USERS group will need to list, read and execute.

    2. Program data, typically in C:\ProgramData\Eduserv\OpenAthens\. The IIS_USERS group will need modify, read and list.

  9. Finally, restart IIS to download the configuration from the publisher dashboard and start using it.

Configure your application

See OpenAthens SP common

Advanced

When there will be more than one organisation accessing by this method, such as in a federation, you would usually restrict access by checking the users' scope. See: Example .NET scope check.

SP can be used under a child application in IIS. You would just need to include the child's path in the application prefix and logout path on the configuration tab of your application in the publisher dashboard - e.g. the application path might change from /oa to /mychildapp/oa.

  • No labels