You are viewing an earlier version of the admin guide. For the latest version, please visit EmpowerID Admin Guide v7.211.0.0.
Configuring the Web Application for the Agent
- Phillip Hanegan
- Anonymous
After creating the WAM applications for the AndysBeans Web application, the last step to enable EmpowerID to protect it is to add the necessary key/value pairs to the application's Web.config file as described below. Not all of these key/value pairs are used with AndysBeans. For example, the EidInitializeIdentityAssemblyInfo key is used to override the default logic of the Agent for setting the HttpContext Identity. However, these optional keys are included for your information.
This example makes adjustments to the AndysBeans Web.config file. If you prefer, you can add these values to the registry instead.
However, when protecting multiple Web applications, 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 and add your key/value pairs there.
To configure the Web application for the EmpowerID Agent
- In the navigation sidebar, expand Admin and click SAML.
- Search for AndysBeans and locate the ACS URL and the User Entered URL.
- Copy the GUID at the end of the ACS URL and the User Entered URL. You will need to add these values to the AndysBeans Web.config file.
- From Windows Explorer, navigate to your Web application folder and open the Web.config file with any text editor.
- 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 SAMLrequest 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:certificateThumbprintForToken - This is the thumbprint of the certificate that is linked to the person making the API calls.
The syntax for this setting is as follows:EidInitializeIdentityAssemblyInfo: This allows you to override the default logic for settingthe HttpContext Identity. (HttpContext is the object that contains all the information about an individualHTTP request.) To override this, create your own assembly with an interface that implements IInitializeUserIdentity and set this value to that of your custom assembly.
The syntax for this setting is as follows:EidIdpUrl: This specifies the URL to which users are redirected if they are not currentlyauthenticated.
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. In the case of AndysBeans, the value for "YourSSOConnection" is AndysBeans.
EidSlidingExpirationTimeout - This specifies the time in minutes that a session cookie remains valid. Users must reauthenticate once this time windows expires.
The syntax for this setting is as follows: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: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:EnableEventLogging - This is a Boolean that specifies whether Windows event logging is enabled or disabled for the agent. Set this to false when the agent is running in production.
The syntax for this setting is as follows: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:- 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 must match the type of identity used by the Web application being protected. Since AndysBeans uses Forms authentication, the value of this key is set to Forms.
The syntax for this setting is as follows:HTTPMODULEEnablePathAuthorization: This is a Boolean that specifies whether the agent enforces URL path authorization for the Protected Application URLs (PURLS) you created for the Web application. If the value is set to "false", the agent does not stop users without the appropriate delegations in EmpowerID from accessing the URL. So, for example, if you created the "employeemanager" PURL demonstrated in the Creating a WAM SSO Application for the Sample App topic, but set this value to "false," then any user with knowledge of the URL can access it, unless the application itself specifically sets access control parameters.
The syntax for this setting is as follows:HTTPModuleTokenMode - This is used to set whether the agent operates in reverse proxy or SAML mode. In reverse proxy mode, the agent assumes 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 specify SAML mode, set the value to "Saml." If you do not specify a value, the agent defaults to reverse proxy mode.
The syntax for this setting is as follows:HTTPMODULESchemeAndHostName - This is used to specify the host name and the scheme for the base URL of the application.
The syntax for this setting is as follows:HTTPMODULEApiPath - This is used to specify the path to the API endpoint for making access calls to EmpowerID.
The syntax for this setting is as follows:HTTPMODULEApiKey - This is used to specify the API key for the OAuth application created for the Web application.
The syntax for this setting is as follows:HTTPMODULEClientID - This is used to specify the Client ID for the OAuth application created for the Web application.
The syntax for this setting is as follows:HTTPMODULERBAC_REFRESH_INTERVAL_SECONDS - This is used to specify the interval in seconds that need to pass before the module makes an API call to refresh RBAC.
The syntax for this setting is as follows:HTTPMODULEErrorUrl - This is an optional setting that you can use to specify a custom page for displaying module errors to your end users. If this key is not added to the config file, then the agent displays the default error page.
The syntax for this setting is as follows, where/home/erroris the location of the custom error page on AndysBeans: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. If this key is not added to the config file, then the agent displays the default not authorized message.
The syntax for this setting is as follows: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 TargetURL you entered for the SSO Connection.
The syntax for this setting is as follows:
After you have completed the above, your <appSettings> section of your configuration file contains the following key/value pairs and looks similar to the image below.
In the config file, navigate to the <system.webServer> section and add the following under <modulesrunAllManagedModulesForAllRequests="true">. Make sure that the .NET version matches the version of the .NET assembly you received from EmpowerID (Net35 or Net45).
The <system.webServer> section now looks similar to the following image.
- Save your changes and reset IIS.
Now that we have configured the AndysBeans Web.config file for use with the agent only, we can Testing Web Access Management.