Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • 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. Download You can get the software from https://download.openathens.net and run the installer.You will need the same credentials you use to access the publisher dashboardour 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:

    Code Block
    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

    Anchor
    metadatareturn
    metadatareturn


  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:

      Code Block
      languagexml
      <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:

      Code Block
      languagexml
      <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:

    Code Block
    <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:

    Code Block
    languagexml
    <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:

    Code Block
    xml
    xml
    <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.

    Anchor
    pipeline
    pipeline

...

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.