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.