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:
The syntax for this setting is as follows:
<add key="certificateThumbprintForEncryption" value="c9daa74ecdb026dc3ee98737b02a5f652f452114"/>
The syntax for this setting is as follows:
<add key="EidAuthMode" value="Forms"/>
The syntax for this setting is as follows:
<add key="EidAuthTokenMode" value="Saml"/>
The syntax for this setting is as follows:
<add key="EidInitializeIdentityAssemblyInfo" value="AssemblyTest, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"/>
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"/>
The syntax for this setting is as follows:
<add key="EidSlidingExpirationTimeout" value="60"/>
The syntax for this setting is as follows:
<add key="EventLogSourceName" value="EIDHttpModule"/>
The syntax for this setting is as follows:
<add key="EventLogSourceName" value="EIDHttpModuleLog"/>
The syntax for this setting is as follows:
<add key="EnableEventLogging" value="false"/>
The syntax for this setting is as follows:
<add key="HTTPMODULEAuthorizationEncryptionSalt" value="11021"/>
The syntax for this setting is as follows:
<add key="HTTPMODULEIdentityPrincipalType" value="Forms"/>
The syntax for this setting is as follows:
<add key="HTTPMODULEEnablePathAuthorization" value="true"/>
The syntax for this setting is as follows:
<add key="HTTPMODULEErrorUrl" value="https://sso.empowerid.com/andysbeans/home/error"/>
The syntax for this setting is as follows:
<add key="HTTPMODULENotAuthorizedUrl" value="https://sso.empowerid.com/andysbeans/home/unauthorized/>
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>
<add name="EidAuthenticationHeaderModule" type="TheDotNetFactory.EmpowerID.Web.Core.Modules.EidAuthenticationHeaderModule,
TheDotNetFactory.EmpowerID.Web.Net45.Modules, Version=4.0.0.0, Culture=neutral"/>