Configuring .NET Web applications for the EmpowerID Web Agent

The EmpowerID Web Agent is used in systems where resources need to be protected, but exposing the Web server that serves up those resources to HTTP traffic from external users is not necessarily an issue. In this case, the EmpowerID Web Agent can be deployed without the EmpowerID Proxy Server or in conjunction with it. The EmpowerID Agent is an HTTP module that can be plugged in to the authentication pipeline in IIS for a .NET application. This allows organizations to load the agent in their Web applications so that each time a request for authentication against those Web applications occur, the code within the EmpowerID Agent is called to determine whether the user is authenticated to EmpowerID. If the user is not authenticated, the user is directed to the EmpowerID Login page where she must provide her credentials and be authenticated by the EmpowerID IdP in order to access the application serviced by the EmpowerID Web Agent. After the user successfully authenticates, EmpowerID passes the credentials for that user to the application. The EmpowerID Web Agent does not determine what the user can or cannot do in the application; that is determined by the application itself.

The EmpowerID Web Agent can be configured for two different authentication modes, Reverse Proxy mode and SAML mode. Depending on which mode is used, the mechanism for retrieving the identity of users differs. In Reverse Proxy mode, identity information is passed to the application via an HTTP variable set in the HTTP Header, eid_user. This variable contains the user's EmpowerID login name. When configured for Reverse Proxy mode, the agent assumes that a trusted reverse proxy (the EmpowerID Proxy Server) is making the request to the Web application and has set the identity in the HTTP Header variable. In SAML mode, the agent reads the SAML assertion generated by the EmpowerID IdP, pulls out the Name Identifier from that assertion and passes it to the application.

The EmpowerID Web Agent can be set for either forms-based or claims-based authentication. These modes are used to determine the identity type used by the .NET Web application being protected, enabling EmpowerID to run the appropriate code to set the identity of the user. Once users authenticate, the next time they try to access the application within the same session, the agent passes the identity information to the application. There is no need to authenticate a second time.

When using EmpowerID to enforce access control policies on a .NET Web application, you must modify the Web application to integrate it with the EmpowerID Web Agent. Modifying your Web application in this way involves adding the EmpowerID Web Agent dll to the bin folder of your Web application, adding a reference to the assembly in your Web application project and modifying the Web application's configuration file appropriately.

This topic demonstrates how to do this and is divided into the following activities:

To add the EmpowerID Web Agent dll to the Web application's bin folder

  1. On your Web server, navigate to your application folder and place the DLL for agent you received from EmpowerID in the application's bin folder. Depending on the version you received, the name of the file will either be TheDotNetFactory.EmpowerID.Web.Net45.Modules.dll or TheDotNetFactory.EmpowerID.Web.Net35.Modules.dll.

  2. Open your Web application project and add a reference to the Web agent assembly you just placed in the bin folder.
  3. Ensure your Web application contains references to the following additional assemblies:
    • EmpowerID.Web.Core.Shared
    • Newtonsoft.Json
    • System
    • System.IndentityModel
    • System.Net
    • System.Net.Http
    • System.Net.Http.Formatting
    • System.Net.Http.Webrequest
    • System.Web
    • System.Xml
    • TheDotNetFactory.Framework.SAML

To edit the Web config file

If desired, you can add these values to the registry instead of the Web application's config file. However, when protecting multiple Web applications, you should avoid using the registry and make your adjustments for each application in that application's config file. To alter the registry, open Registry Editor, navigate to the TheDotNetFactory\EmpowerID key and add a subkey named "WebSettings." You can then add your key/value pairs there.
  1. From Windows Explorer, navigate to your Web application folder and open the Web.config file with any text editor.
  2. In the Web.config file, navigate to <appSettings> and add the following key/value pairs:
    • certificateThumbprintForEncryption - This is the thumbprint of the certificate that the SAML request uses to deserialize the requested URL when the agent is in SAML mode. This thumbprint must be from the certificate used when creating the SSO Connection for your Web application.

      • The syntax for this setting is as follows: 


      <add key="certificateThumbprintForEncryption" value="‎c9daa74ecdb026dc3ee98737b02a5f652f452114"/>
    • EidAuthMode - This specifies whether the identity of HttpContext is set to "Forms" or "Claims." If the value is set to "Forms", the agent calls the FormsAuthentication.SetAuthCookie() method and sets the forms authentication cookie. If the value is set to "Claims," the agent sets HttpContext.Current.User to a generic identity. This setting is only valid if you are not overriding the default functionality of the agent with a customized setting applied to EidInitializeIdentityAssemblyInfo key mentioned above.

      • The syntax for this setting is as follows:

      <add key="EidAuthMode" value="Forms"/>
    • EidAuthTokenMode - This is used to set whether the agent operates in reverse proxy or SAML mode. In reverse proxy mode, the agent will assume the EID_USER variable inserted into the HTTP header is authenticating the user; otherwise, it looks for a SAML redirection response. To specify reverse proxy mode, set the value to "Forms." To specifiy SAML mode, set the value to "Saml." If you do not specify a value, the agent defaults to reverse proxy mode.
      • To use reverse proxy mode, you must first register your Web application in EmpowerID.

      The syntax for this setting is as follows: 

      <add key="EidAuthTokenMode" value="Saml"/>
    • EidInitializeIdentityAssemblyInfo - This allows you to override the default logic for setting the HttpContext Identity. (HttpContext is the object that contains all the information about an individual HTTP request.) To override this, you need to create your own assembly with an interface that implements IInitializeUserIdentity and then set this value to that of your custom assembly.

      • The syntax for this setting is as follows:


      <add key="EidInitializeIdentityAssemblyInfo" value="AssemblyTest, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"/>
    • EidIdpUrl - This specifies the URL to which users are redirected if they are not currently authenticated.

      • The syntax for this setting is as follows, where "YourWebServer" is the fqdn of the server hosting your Web application and "YourSSOConnection" is the name of the SSO Connection you created for your protected Web application: 


      <add key="eidIdpUrl" value="https://YourWebServer/EmpowerIDWebIDPForms/Login/YourSSOConnection"/>
    • EidSlidingExpirationTimeout - This specifies the time in minutes that a session cookie remains valid. Users will need to reauthenticate once this time windows expires.

      • The syntax for this setting is as follows:

      <add key="EidSlidingExpirationTimeout" value="60"/>
    • EventLogSourceName - This is an optional setting that allows you to specify a log source name for logging entries related to the agent.

      • The syntax for this setting is as follows:

      <add key="EventLogSourceName" value="EIDHttpModule"/>
    • EventLogLogName - This is an optional setting that allows you to specify a log name for logging events related to the agent.

      • The syntax for this setting is as follows: 

      <add key="EventLogSourceName" value="EIDHttpModuleLog"/>
    • EnableEventLogging - This is a Boolean that specifies whether Windows event logging is enabled or disabled for the agent. This should be set to false when the agent is running in production.

      • The syntax for this setting is as follows: 

      <add key="EnableEventLogging" value="false"/>
    • HTTPMODULEAuthorizationEncryptionSalt - This is used to encrypt and decrypt the EmpowerID cookie containing the user identity and SSO Application IDs that person has authenticated against. This value can be arbitrary.

      • The syntax for this setting is as follows:

      <add key="HTTPMODULEAuthorizationEncryptionSalt" value="11021"/>
    • HTTPMODULECustomAuthenticationAssembly - This is an advanced optional setting that specifies the fully qualified name of the dll/type to load to implement custom authentication and authorization logic.
    • HTTPMODULEIdentityPrincipalType - This determines the type of identity set by the agent. The values can be either "Forms" or "Claims" and should match the type of identity used by the Web application being protected.

      • The syntax for this setting is as follows:

      <add key="HTTPMODULEIdentityPrincipalType" value="Forms"/>
    • HTTPMODULEEnablePathAuthorization - This is a Boolean that specifies whether the agent  will enforce URL path authorization for the URL Subcomponents (protected URLS or paths) you created for the Web application. If the value is set to "false", the agent will not stop users who have authenticated but do not have the necessary delegations to view the resource from doing so. Thus, if you have created a PURL for a "Payroll" page and have a user named "Joe" who is authorized to access your site, but does not have permission to view the Payroll page on that site, and this is set to false, Joe will be able to access the page.

      • The syntax for this setting is as follows:

      <add key="HTTPMODULEEnablePathAuthorization" value="true"/>
      This value must be set to false when the agent is running in reverse proxy mode.
    • HTTPMODULEErrorUrl - This is an optional setting that you can use to specify a custom page for displaying module errors to your end users.

      • The syntax for this setting is as follows:

      <add key="HTTPMODULEErrorUrl" value="https://sso.empowerid.com/andysbeans/home/error"/>
    • HTTPMODULENotAuthorizedUrl - This is an optional setting that you can use to specify a custom page for displaying messages to users who do not have the delegations to view a requested page.

      • The syntax for this setting is as follows:


      <add key="HTTPMODULENotAuthorizedUrl" value="https://sso.empowerid.com/andysbeans/home/unauthorized/>
    • RedirectUrlGuid - This specifies the GUID that EmpowerID generated for the SSO Connection linked to your Web application when you created it. EmpowerID appends this GUID to the Base URL you entered for the SSO Connection. You can locate this URL from the SAML Connections grid, which you access from the Navigation Sidebar by expanding Admin > SSO Connections and clicking on the SAML node. You then search for the SSO Connection, as shown by the below image. The Assertion Consumer URL field displayed in the grid contains the value you need to add to the key. (See the below image.)

      • The syntax for this setting, based on the value of the Assertion Consumer URL in the below image, is as follows: 

      <add key="RedirectUrlGuid" value="39aadc3c-23e8-4376-b78b-79b27d27cab0"/>

      After you have completed the above, the EmpowerID key/value pairs in the <appSettings> section of your configuration file should look similar to the following: 

      <appSettings>
        <add key="certificateThumbprintForEncryption" value="‎c9daa74ecdb026dc3ee98737b02a5f652f452114"/>  
        <add key="EidAuthMode" value="Forms"/>        
        <add key="EidAuthTokenMode" value="Saml"/>
        <add key="EidInitializeIdentityAssemblyInfo" value=AssemblyTest, Version=1.0.0.0, Culture=neutral, PublicKeyToken="null"/>
        <add key="eidIdpUrl" value="https://sso.empowerid.com/EmpowerIDWebIDPForms/Login/AndysBeans"/>
        <add key="EidSlidingExpirationTimeout" value="60"/>
        <add key="EventLogSourceName" value="EIDHttpModule"/>
        <add key="EventLogSourceName" value="EIDHttpModuleLog"/>
        <add key="EnableEventLogging" value="true"/>
        <add key="HTTPMODULEIdentityPrincipalType" value="Forms"/>
        <add key="HTTPMODULEEnablePathAuthorization" value="true"/>
        <add key="RedirectURlGuid" value="5778dc3b-cedb-466c-9e88-2c1ff47e8390" />
        <add key="webpages:Version" value="2.0.0.0" />
        <add key="webpages:Enabled" value="false" />
        <add key="PreserveLoginUrl" value="true" />
        <add key="ClientValidationEnabled" value="true" />
        <add key="UnobtrusiveJavaScriptEnabled" value="true" />
    </appSettings>
  3. In the config file, navigate to the <system.webServer> section and add the following under <modules runAllManagedModulesForAllRequests="true">. Make sure the Net version matches the version of the .NET assembly you received from EmpowerID (Net35 or Net45). 

    4. <add name="EidAuthenticationHeaderModule" type="TheDotNetFactory.EmpowerID.Web.Core.Modules.EidAuthenticationHeaderModule,
          TheDotNetFactory.EmpowerID.Web.Net45.Modules, Version=4.0.0.0, Culture=neutral"/>
  4. Save your changes and reset IIS.