.NET Framework 4.5+ WebForms OpenID Connect example

Last updated: April 2025
.NET Framework version tested: 4.7.2

This tutorial takes you through the minimum steps needed to integrate a .NET WebForms application with OpenAthens Keystone using OpenID Connect. It is assumed that you have experience of developing applications using ASP.NET in Visual Studio.

Goal in this example

Authenticate a user and display all the received claims on a page. In the real world you would feed the claims into your authorisation / user-session management process, so that you can grant access only to your customers.

Instructions

Create project

Create a new project in Visual Studio, selecting the template “ASP.NET Web Application (.NET  Framework)”. At the second stage, select the Web Forms template option, and enable the “Configure for HTTPS” option if available. Don’t select any authentication options at this stage.

If “Configure for HTTPS” was not available in your version of the Visual Studio template, configure it manually:

In the solution explorer, select the project folder, then in the properties pane, change SSL Enabled to true. Copy the SSL URL that is created.

Right click the project and select properties, and in the Web tab, paste the https URL copied above into the Project Url field in place of the existing http URL.

Create connection in OpenAthens

Create a new OpenID Connect Application record in the OpenAthens Service Provider dashboard, using the SSL URL from the project as the Application URL (but with no trailing /). Copy the same URL (including the port number) to the Redirect URL, this time include the trailing /.

Add the Owin and OpenID Connect dependencies

Add the following packages:

Microsoft.AspNet.Identity.Owin

Microsoft.Owin.Host.SystemWeb

Microsoft.Owin.Security.OpenIdConnect

The OpenIdConnect package must be version 4.1.0 or later, to get support for the OpenID Connect Code flow, which OpenAthens uses.

Configuration

Add the following appSettings to Web.config:

CODE

<add key="oidc:Authority" value="https://connect.openathens.net" /> 
<add key="oidc:ClientId" value="{clientId from the OIDC application record created in the publisher dashboard}" /> 
<add key="oidc:ClientSecret" value="{clientSecret from the OIDC application created in the publisher dashboard}" /> 
<add key="oidc:RedirectUrl" value="{redirectUrl set in the publisher dashboard}" />

(You should keep the ClientSecret private. In the real world you would keep it out of source control and load it separately, from a file outside the application root or from an environment variable.)

Add a Startup class that initialises the OpenID Connect authentication via an Owin assembly binding. Following the convention used in other samples from Microsoft, this is a partial class split across two files. Firstly, Startup.cs in the project root:

CODE

[assembly: OwinStartup(typeof(<YourProjectName>.Startup))] 
namespace <YourProjectName> 
{ 
    public partial class Startup 
    { 
        public void Configuration(IAppBuilder app) 
        { 
            ConfigureAuth(app); 
        } 
    } 
}

Then add the implementation of ConfigureAuth in Startup.Auth.cs in the App_Start folder. You’ll need to remove “.App_Start” from the namespace in the created file so it matches the namespace in Startup.cs:

CODE

namespace <YourProjectName> 
{ 
    public partial class Startup 
    { 
        public static string OidcAuthority = ConfigurationManager.AppSettings["oidc:Authority"]; 
        public static string OidcRedirectUrl = ConfigurationManager.AppSettings["oidc:RedirectUrl"]; 
        public static string OidcClientId = ConfigurationManager.AppSettings["oidc:ClientId"]; 
        public static string OidcClientSecret = ConfigurationManager.AppSettings["oidc:ClientSecret"]; 
 
        public void ConfigureAuth(IAppBuilder app) 
        { 
            app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType); 
            app.UseCookieAuthentication(new CookieAuthenticationOptions()); 
 
            var oidcOptions = new OpenIdConnectAuthenticationOptions 
            { 
                Authority = OidcAuthority, 
                ClientId = OidcClientId, 
                ClientSecret = OidcClientSecret, 
                PostLogoutRedirectUri = OidcRedirectUrl, 
                RedeemCode = true, 
                RedirectUri = OidcRedirectUrl, 
                ResponseType = OpenIdConnectResponseType.Code, 
                Scope = OpenIdConnectScope.OpenId 
            }; 
 
            app.UseOpenIdConnectAuthentication(oidcOptions); 
        } 
    } 
}

Configure global security settings

If you are using an (unsupported) .NET runtime version less than 4.6.2, you'll need to add a line to Application_Start in Global.asax.cs to enable TLS 1.2:

CODE

void Application_Start(object sender, EventArgs e) 
{ 
... 
    // Not needed for .NET 4.6.2 and later: TLS 1.2 is already enabled: 
    ServicePointManager.SecurityProtocol |= SecurityProtocolType.Tls12; 
}

Add login and logout

Add login and logout links by adding the following code block immediately after the existing <ul>...</ul> navigation links in Site.Master:

CODE

<asp:LoginView runat="server" ViewStateMode="Disabled"> 
    <AnonymousTemplate> 
        <ul class="navbar-nav navbar-right"> 
            <li class="nav-item"> 
                <a class="nav-link" 
                    runat="server" 
                    href="Site.Master" 
                    onserverclick="login_Click">Login</a> 
            </li> 
        </ul> 
    </AnonymousTemplate> 
    <LoggedInTemplate> 
        <ul class="navbar-nav navbar-right"> 
            <li class="nav-item"> 
                <asp:LoginStatus class="nav-link" 
                    runat="server" 
                    LogoutAction="Redirect" 
                    LogoutText="Logout" 
                    LogoutPageUrl="~/" 
                    OnLoggingOut="Unnamed_LoggingOut" /> 
            </li> 
        </ul> 
    </LoggedInTemplate> 
</asp:LoginView>

and add the following handler methods in Site.Master.cs:

CODE

protected void login_Click(object sender, EventArgs e) 
{ 
    if (!Request.IsAuthenticated) 
    { 
        HttpContext.Current.GetOwinContext().Authentication.Challenge(); 
    } 
} 
 
protected void Unnamed_LoggingOut(object sender, EventArgs e) 
{ 
    if (Request.IsAuthenticated) 
    { 
        Context.GetOwinContext().Authentication.SignOut(CookieAuthenticationDefaults.AuthenticationType); 
    } 
}

Login and logout should now be working. Run the site, and check that Login takes you to OpenAthens, where you can log in with a personal account (create one in the Admin area https://admin.openathens.net/ if you haven't already done so). Logout should work as well.

Add Claims page

The next step is to add a protected page that shows the OpenID Connect claims for the logged in user. Add a new web form called Claims with the following content:

CODE

<%@ Page Title="Claims" Language="C#" MasterPageFile="~/Site.Master" AutoEventWireup="true" CodeBehind="Claims.aspx.cs" Inherits="<YourProjectName>.Claims" %> 
<%@ Import Namespace="System.Security.Claims" %> 
 
<asp:Content ID="Content1" ContentPlaceHolderID="MainContent" runat="server"> 
    <h2>OpenID Connect Claims</h2> 
    <dl> 
        <asp:DataList runat="server" ID="dlClaims"> 
            <ItemTemplate> 
                <dt><%# ((Claim) Container.DataItem).Type %></dt> 
                <dd><%# ((Claim) Container.DataItem).Value %></dd> 
            </ItemTemplate> 
        </asp:DataList> 
    </dl> 
</asp:Content>

and update the Page_Load method in Claims.aspx.cs as follows:

CODE

protected void Page_Load(object sender, EventArgs e) 
{ 
    if (!Request.IsAuthenticated) 
    { 
        HttpContext.Current.GetOwinContext().Authentication.Challenge(); 
    } 
 
    var claims = ClaimsPrincipal.Current.Claims; 
    dlClaims.DataSource = claims; 
    dlClaims.DataBind(); 
}

Add a link to the Claims page inside the LoggedInTemplate you added to Site.Master earlier:

CODE

<li> 
    <a class="nav-link" runat="server" href="~/Claims">View claims</a> 
</li>

Now you can log in and view the claims. At this stage, you only have a limited set of claims, which are included in the initial response OIDC response. These claims don’t tell you enough about the user to know whether to grant them access. To do this, you need to fetch additional claims from the OpenID Connect userinfo endpoint.

Fetch additional claims

The Microsoft .NET Framework implementation of OpenID Connect does not fully implement the OpenID Connect protocol. Specifically, it does not support fetching additional user claims from the userinfo endpoint. If you were using .NET Core, you would just need to set GetClaimsFromUserInfoEndpoint = true in the config, but the .NET Framework implementation doesn’t support this. We need to write our own method to retrieve the additional claims. Add a new method in the Startup.Auth.cs:

CODE

private async Task GetUserInfoAsync(SecurityTokenValidatedNotification<OpenIdConnectMessage, OpenIdConnectAuthenticationOptions> notification) 
{ 
    var accessToken = notification.ProtocolMessage.AccessToken; 
    var backchannel = notification.Options.Backchannel; 
    var identity = notification.AuthenticationTicket.Identity; 
    var metadataAddress = notification.Options.MetadataAddress; 
 
    var configuration = await OpenIdConnectConfigurationRetriever.GetAsync(metadataAddress, new CancellationToken()); 
    var request = new HttpRequestMessage(HttpMethod.Get, configuration.UserInfoEndpoint); 
    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken); 
    var responseMessage = await backchannel.SendAsync(request); 
    responseMessage.EnsureSuccessStatusCode(); 
    var response = await responseMessage.Content.ReadAsStringAsync(); 
    var userInfo = JObject.Parse(response); 

    // Add claims we don't already have 
    foreach (var pair in userInfo) 
    { 
        var claimValue = userInfo.TryGetValue(pair.Key, out JToken value) ? value.ToString() : null; 
        if (!identity.HasClaim(pair.Key, claimValue)) 
        { 
            identity.AddClaim(new Claim(pair.Key, claimValue, ClaimValueTypes.String)); 
        } 
    } 
}

Then wire this up by adding a Notifications property to the existing oidcOptions:

CODE

var oidcOptions = new OpenIdConnectAuthenticationOptions 
{ 
    ..., 
    Notifications = new OpenIdConnectAuthenticationNotifications 
    { 
        SecurityTokenValidated = GetUserInfoAsync 
    } 
};

Re-run the application and access the claims page again. You should now see a much longer list of claims.

The claims you will be most interested in are:

urn:oid:1.3.6.1.4.1.5923.1.1.1.9, also known as scopedAffiliation. Use this to decide whether the allow the user into your application, based on your customer database.

urn:oid:1.3.6.1.4.1.5923.1.1.1.10, also known as targetedID. This is a persistent, pseudonymous identifier for the user. Use this as the key for storing user personalisation.

In the real world you would use the scopedAffiliation to decide whether to grant access to protected content.

Be aware that claims can be multi-valued and may be returned as either a string or an array, depending on the number of values available for the user. For example, urn:oid:1.3.6.1.4.1.5923.1.1.1.9 could be returned in either of these forms:

"member@<domain>"

["member@<domain>", "student@<domain>"]

You will need to allow for this when parsing the claims.

For more information about the attributes available from OpenAthens, and how to map them to OpenID Connect claims. See: