Getting started with .NET, OpenAthens SP and the dashboard

This is a simple "Hello, world" guide to getting started as a Service Provider with OpenAthens using .NET.

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 (in the OpenAthens admin area go to Accounts > Add > Personal)
The EntityID for your domain - this can be found in the OpenAthens admin area under Management > Connections
Access to a .NET environment running IIS (we are assuming local machine for this guide)

Assumptions:

$ATACAMA_HOME is C:\Program Files (x86)Eduserv\OpenAthens.Net
Application pool Managed Pipeline Mode is in 'Integrated' mode and 'Enable 32-Bit applications' is set to true in Advanced Settings.

What are we going to do

For this example we'll first register our application with the Publisher Dashboard and then build a page to enable for access with OpenAthens SP.

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. In the real world this would 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

At this point you're presented with a getting started guide in the dashboard that should provide you with enough to implement OpenAthens SP on your .NET Web application.

Hello world

Any basic .NET application page will do for this - e.g. after creating a relevant folder under C:\inetpub\wwwroot\:

File: New Project -> Visual C# - ASP.NET Web Application -> Give it a name and click OK (leave the 'Create directory for solution' checkbox selected).
Create a new page to protect: right-click on the project name from the Solution Explorer and select Add -> New Item.
Ensure ‘Web’ is selected from the ‘Installed Templates’ menu, then select ‘Web Form’ from the central menu.
Rename the file to be 'ProtectedPage.aspx’ and click the ‘Add’ button.
Paste the following code into ProtectedPage.aspx and save:

<%@ Page Language="C#" AutoEventWireup="true" 
CodeBehind="ProtectedPage.aspx.cs" 
Inherits="ProtectedPage.ProtectedPage" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
        <h1>Hello World!</h1>
    </div>
    </form>
</body>
</html>

Now add the OpenAthens bits to the Web.config

From the Solution Explorer double-click on the file Web.config and paste this in, updating the OpenAthens configuration URL and Access Key on the line near the end:

<?xml version="1.0"?>
<!--
  For more information on how to configure your ASP.NET application, please visit
  http://go.microsoft.com/fwlink/?LinkId=169433
  -->
<configuration>
  <configSections>
    <section name="openAthens" type="Eduserv.OpenAthens.OpenAthensConfigSection"/>
  </configSections>

  <connectionStrings>
   
 <add name="ApplicationServices" connectionString="data 
source=.\SQLEXPRESS;Integrated 
Security=SSPI;AttachDBFilename=|DataDirectory|\aspnetdb.mdf;User 
Instance=true" providerName="System.Data.SqlClient"/>
  </connectionStrings>

  <system.web>
    <compilation debug="true" targetFramework="4.0">
      <assemblies>
        <add assembly="atacama.net, Version=2.1.3.0, Culture=neutral, PublicKeyToken=6E679382149F5665"/>
        <add assembly="OpenAthens.Net, Version=1.0.0.0, Culture=neutral, PublicKeyToken=17390934318F9B06"/>
      </assemblies>
    </compilation>
    <!-- <authentication mode="Windows"/> -->
    <authentication mode="None"/>
    <httpModules>
      <!--  <add name="OpenAthensServerModule" type="Eduserv.OpenAthens.ServerModule"/>-->
    </httpModules>
    <membership>
      <providers>
        <clear/>
       
 <add name="AspNetSqlMembershipProvider" 
type="System.Web.Security.SqlMembershipProvider" 
connectionStringName="ApplicationServices" 
enablePasswordRetrieval="false" enablePasswordReset="true" 
requiresQuestionAndAnswer="false" requiresUniqueEmail="false" 
maxInvalidPasswordAttempts="5" minRequiredPasswordLength="6" 
minRequiredNonalphanumericCharacters="0" passwordAttemptWindow="10" 
applicationName="/"/>
      </providers>
    </membership>
    <profile>
      <providers>
        <clear/>
       
 <add name="AspNetSqlProfileProvider" 
type="System.Web.Profile.SqlProfileProvider" 
connectionStringName="ApplicationServices" applicationName="/"/>
      </providers>
    </profile>
    <roleManager enabled="false">
      <providers>
        <clear/>
       
 <add name="AspNetSqlRoleProvider" 
type="System.Web.Security.SqlRoleProvider" 
connectionStringName="ApplicationServices" applicationName="/"/>
       
 <add name="AspNetWindowsTokenRoleProvider" 
type="System.Web.Security.WindowsTokenRoleProvider" 
applicationName="/"/>
      </providers>
    </roleManager>
  </system.web>

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

<!--
	ATTENTION! AWOOGA! AUFMERKSAMKEIT! SYLW! ETC... 
	UPDATE THE CONFIGURATION URL AND ACCESS KEY IN THE NEXT BIT.
	DATA IN PUBLISHER DASHBOARD > APPLICATIONS > CONFIGURATION TAB
 -->
 
  <openAthens atacamaConfig="<insert configuration URL>" accessKey="<insert accessKey>" logConfig="C:\Program Files (x86)\Eduserv\OpenAthens.Net\conf\defaultLogConfig.xml"/>

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

Publish to IIS
- Edit > Publish Profiles.
- Ensure the Publish method is set to
  - 'File system' (testing on local machine).
  - Target Location is the folder you created under C:\inetpub\wwwroot\
  - leave 'Replace matching files with local copies' selected. Click Publish
Restart IIS

Try it

Visit your protected page in a browser 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.