EmpowerID Reverse Proxy Overview

Web Access Management (WAM) is a web-centric Identity Management strategy that focuses on securing enterprise resources accessible to Internet users. The key principles of WAM include enforcement of corporate security policies, prevention of unauthorized access to enterprise resources, and the enablement of Web single sign-on (SSO) for simpler access to cross-domain resources. WAM implementations typically realize these through the enactment of authentication and access control policies that funnel all Web application users through a single security gate, where decisions about the users are made and enforcement of those decisions occur. In WAM terminology, this security gate is known as the "Policy Decision Point" or "PDP." The PDP decides what users can or cannot do based on the information it reads from a "Policy Information Point" or "PIP," which is written and managed by administrators and other delegated users through a console known as a "Policy Administration Point" or "PAP." The decisions of the PDP are then enforced by a "Policy Enforcement Point" or "PEP."

The EmpowerID Reverse Proxy is a component of the EmpowerID WAM System that sits between clients and Web servers, restricting access to the resources served by those servers by intercepting all HTTP traffic bound for those servers and redirecting it to EmpowerID for security evaluation and processing. As a WAM component, the EmpowerID Reverse Proxy provides Web environments with seamless access to all of the identity management facilities of EmpowerID. This means organizations can employ the EmpowerID Reverse Proxy to provide the same level of security to the resources that live on their Web servers as they can to the resources that live in their directories and other such similar resource systems. These facilities work together to allow authorized users unhindered access to any and all resources to which they are entitled, while denying illegitimate users the ability to do the same. Once a user authenticates (using identities supplied by any number of accepted Identity Providers, including EmpowerID, Twitter, Facebook, Google, Salesforce, Paypal and so on), the EmpowerID RBAC engine controls all facets of access for that user in accordance with the policy applied to him. The below image shows the relationship of the EmpowerID Reverse Proxy to the other facilities of EmpowerID.

EmpowerID Reverse Proxy Components

If you look closely at the above image, you will notice a difference between how EmpowerID interacts with the resources contained in an account store or another type of resource system—such as a file server—and the HTTP resources within a Web server. Namely, EmpowerID connects to and inventories the former, but not the latter. This means EmpowerID has no implicit knowledge of the actual resources on a Web server or even of the Web server itself. This information must be supplied from a secondary source. In EmpowerID, you supply this information through the creation of a special SSO application known as a "Web Access Management" application, adding to that application special components known as "Application Subcomponents."

Web Access Management Applications

Web Access Management (WAM) applications represent the specific sites being protected by the EmpowerID Reverse Proxy. As such, each WAM application is a service provider represented in EmpowerID with a unique SAML SSO Connection. Representing protected Web sites with SSO Connections allows EmpowerID to maintain a link between those Web sites, the protected resources (URLs) on those sites, and the users authorized to access them. As a service provider, the reverse proxy responds to requests for resources in a manner familiar with most Web users: If the request is for a resource that is of a sensitive nature, users must prove their identities to EmpowerID and be authorized to access the requested resource before the request will be serviced. On the other hand, if the request represents an unrestricted resource that requires no identity proofs to access, then the reverse proxy will simply service the request without requiring users authenticate or, if already authenticated, checking to see if they have the appropriate delegations for the resource.

You create WAM applications in EmpowerID by navigating to the "Applications and Connections" page of the EmpowerID Web application and selecting "Create Application." Doing so opens the interface generic to all applications, allowing you to select the SSO Connection specific to WAM applications. This connection contains a form with a number of fields common to all SSO applications, such as the Name, Description, and Certificate fields, as well as an additional fields specific toWAM applications, including the Base URL field, as well as options for allowing anonymous access to unprotected paths and whether the target host name should be used when sending requests to the protected Web application. Of these fields, the Base URL field is important because this is where you specify the address of the Web site to be protected, such as "www.empowerid.com." You can have as many WAM applications as needed to protect your sites; however, each WAM application can only be mapped to one site. For example, if you have a Web site named "www.empowerid.net" and another named "www.empowerid.com," and you want to restrict access to resources on both, you must create two WAM applications with the appropriate Base URL value for each.

Application Subcomponents

With WAM applications, Application Subcomponents represent resources (URLs) you wish to protect on a given Web server. When you create a WAM application, you designate the path or paths on the Web server to be restricted by adding one Application Subcomponent for each path. Then when users first attempt to access the URL, the reverse proxy directs them to the EmpowerID Identity Provider, where they must log in and request access to the resource. Once access is granted, EmpowerID creates an account for that person that is linked to the appropriate SSO Connection (WAM application) via that Account Store ID for that connection.

EmpowerID provides a number of matching options for specifying these paths. The option you choose determines the scope of the Application Subcomponent and you can have more than one Application Subcomponent for a site. For example, you can have an Application Subcomponent for the base URL of a site and other Application Subcomponents for certain paths on that site. In this way, you can setup additional requirements for users accessing more sensitive URLs, such as requiring multi-factor authentication. The matching options for an Application Subcomponent are as follows:

• Exact Match - This option allows you to specify an exact URL to be restricted. For example, if you want to restrict access to a specific page such as www.empowerid.com/customers/reports.aspx, you enter www.empowerid.com/customers/reports.aspx in this field.
• Pattern Match - This option allows you to enter a javascript regular expression pattern specifying that any URLs matching the pattern be restricted. Regular expression patterns can be comprised of strings of simple characters, special characters, or combinations of both.
• Simple Characters - Specifying a string of simple characters causes any URLs with character sequences matching the string to be restricted, regardless of where those characters occur within a path. For example, if you wish to restrict access to any URL containing delete, such as in operation=delete and deletedreports, you enter delete as the pattern match. Then when users type a URL like www.empowerid.com/personid24/operation=delete or www.empowerid.com/view/deletedreports, they will be redirected to the EmpowerID Identity Provider to authenticate.
• Special Characters - If you are familiar with regular expressions, you can take advantage of special characters to add more power and flexibility to your matching patterns. For example, if you want to restrict access to all paths containing the words reports and accounts, you can add reports|accounts as the pattern match. In this way, if a user attempts to access a URL like www.empowerid.com/customers/reports/customerid=12 or a URL like www.empowerid.com/useraccounts, that user will be redirected to the login page for the EmpowerID Web application in your environment.
• Beginning Path - This allows you to specify that any URL with a specific beginning path appended to the Hostname of the associated Reverse Proxy Application be restricted. For example, if you have a Reverse Proxy application with a Hostname of www.empowerid.com and you want to restrict access to all paths beginning with customers, such as www.empowerid.com/customers/gold and www.empowerid.com/customers/australia you enter customers in this field.

EmpowerID Reverse Proxy Configuration File

In addition to creating the above two applications, you need to configure the EmpowerID Reverse Proxy for your specific environment. You do this by customizing the settings of the config.js file for the EmpowerID Reverse Proxy. This file is located in the top-level folder for the application, the node_httpProxy folder. A description of the file's settings follows.

• certificateThumbprintForEncryption - The EmpowerID Reverse Proxy requires a SQL login for an EmpowerID Person with a role that allows that identity to run the EmpowerID Reverse Proxy Windows service. In order to protect the login, you must create an encrypted passphrase file for it and have a certificate in the Personal certificate store of the EmpowerID server that can be used to encrypt and decrypt it. You add the thumbprint for the certificate here. When the EmpowerID Reverse Proxy starts, it will retrieve the value and look in the Personal certificate store for a match. If it finds a match, it uses the certificate to decrypt the passphrase encrypting the password of the SQL login.
• SESSION_DURATION_MINUTES - This value determines how long the cookie issued by the EmpowerID Reverse Proxy that identifies the user remains valid within a session. When the duration period reaches its end, the user must reauthenticate with the EmpowerID Identity Provider.
• RBAC_REFRESH_INTERVAL_SECONDS - This value determines how often in seconds the EmpowerID Reverse Proxy pulls RBAC data from the EmpowerID Identity Warehouse. This data allows the EmpowerID Reverse Proxy to enforce security policies and includes a relational mapping of all PersonIDs, Account Logins, Reverse Proxy Application Resource IDs and the URL patterns (ProtectedApplicationURL applications) associated with each.
• ALLOW_ANONYMOUS - This value determines whether access is allowed to specified target sites without requiring users authenticate against the EmpowerID Identity Provider. (These sites are added as values of the router object described below.) If the value is set to true and there are no paths on the site protected by a ProtectedApplicationURL application, users may access any path on the site without authenticating. If the value is set to false, users may not access any path on the site until they have authenticated against the EmpowerID Identity Provider. Additionally, users must know the path they want to reach in order to access the site. For example, if a PURL with a Beginning Path value of customers exists for a Reverse Proxy application with a Hostname value of www.empowerid.com, users will not be able to access www.empowerid.com until they authenticate for www.empowerid.com/customers. Once they authenticate for the PURL, they will be able to access the base site as well.

The following image depicts how this works. In the image, both users begin their sessions as anonymous users. User A attempts to access www.empowerid.com (indicated by the red 1). However, because ALLOW_ANONYMOUS is set to false, the user receives a 403 message indicating she needs is not authorized to view the resource. User B, however, knows the exact URL he wants to access—a URL for which a PURL exists—and navigates his browser to www.empowerid.com/customers (indicated by the blue 1). Because a PURL exists for this specific path, the EmpowerID Reverse Proxy redirects his browser to the Login page for the EmpowerID Web application, where he successfully authenticates against the EmpowerID IdP. The reverse proxy then fetches the requested resource for him. Later, within the same session, User B requests www.empowerid.com (indicated by the green 2). Because User B is already authenticated, and no further delegations are required for the URL, the reverse proxy fetches the resource and serves it to him.



• FILEPATH_PEM_VERIFY_CERT - This specifies the path on the server to the certificate used to verify the validity of the SAML signatures used to assert identities. The certificate should be the same as the certificate chosen when creating the Reverse Proxy application. To accomplish this, you can export the certificate from the Certificate store in base-64 encoded x.509 format.
• eventLogSourceName - The EmpowerID Reverse Proxy maintains a log of events for the application that can be viewed from the Windows Event Viewer. The default name for the application source of the log is EIDReverseProxy; however, you can change the name as desired by changing the value this variable.
• eventLogLogName - The EmpowerID Reverse Proxy maintains a log of events for the application that can be viewed from the Windows Event Viewer. The default name for the log is EIDReverseProxyLog; however, you can change the name as desired by changing the value this variable.
• sourceCertsByDomain - This specifies the path on the server to the certificate used by the EmpowerID Reverse Proxy for TLS communications. You can have multiple certificates if more than one domain is being protected. You must supply the domain name and provide the paths for the encrypted passphrase and .pfx files for each. The certificate must match the server certificate for each domain.
• extensionsToNotRedirect - This specifies the types of files that should not be returned to unauthenticated users. The default extensions include the following: .ico, .jpg, .jpeg, .gif, .js, .css, .png.
• numberProcesses - This specified how many processes the reverse proxy will run. This value normally matches the number of cores on the server. However, as each process caches RBAC data, for performance purposes it is important to ensure the server has enough RAM to accommodate multiple caches, especially for environments with large amounts of RBAC data.
• maxClientSocketsPerDomain - this specifies the number of sockets for the reverse proxy to open as a client for each domain. The number for optimal performance depends on typical response times from target sites.
• eidIdpUrl - This specifies the URL to the SAML authentication endpoint for the EmpowerID Identity Provider in your environment.
• sql - This specifies the SQL username for the EmpowerID Person with access rights to the EmpowerID Windows services as well as the path to the encrypted file for the password. In addition, you specify the name of the EmpowerID database and the FQN of the SQL Server in your environment.
• listeningPort - This specifies the port the reverse proxy listens to for traffic. This should reflect the port used for the protected Web site.
• useTlsForListen - This specifies whether the reverse proxy needs to use TLS.
• router - This is used by the reverse proxy to translate the URLs requested by clients to the URLs where those requests can be serviced. It is a colon-separated, single-quote enclosed value pair comprised of two sets of host, port and path combinations, such as 'www.andysbeans.com/customers : 10.0.0.4/customers', where www.andysbeans.com/customers represents the URL typed into a browser window by a user and 10.0.0.4/customers represents the destination where the user's request is to be serviced. When an HTTP request reaches the reverse proxy, the reverse proxy checks the router configuration for a match; if it finds one, it makes the translation, choosing the most specific path requested by the client. The router function gives you the ability to hide the true address of destination Web servers from users as well as allows you to redirect incoming traffic to any valid sites you may have in your environment.
You can have as many client request-server destination value pairs configured as needed; however, if more than one is supplied, you must separate them with a comma.
The reverse proxy requires at least one be set or an error will occur when starting the EmpowerID Reverse Proxy Windows service.

The following table provides some example router configuration settings. Each example shows a specific router setting and how that setting affects the translation. As can be seen, the reverse proxy makes the translation based on the most specific path supplied to it. So, for example, if the router is configured for 'www.andysbeans.com/customers : www.andysbeans.com/allcustomers' and a user types www.andysbeans.com/customers/oh into her browser, the reverse proxy will translate that request to www.andysbeans.com/allcustomers/oh.

Router Setting
'www.andysbeans.com : 10.0.0.4'
Client Request	Translated Request
www.andysbeans.com	10.0.0.4
Router Setting
'www.andysbeans.com/customers : www.andysbeans.com/allcustomers'
Client Request	Translated Request
www.andysbeans.com/customers/oh	www.andysbeans.com/allcustomers/oh
Router Setting
'www.andysbeans.com/customers : 10.0.0.4/customers', 'www.andysbeans.com/admin : 10.0.0.5/admin'
Client Request	Translated Request
www.andysbeans.com/customers/eu/gold	10.0.0.4/customers/eu/gold
www.andysbeans.com/admin	10.0.0.5/admin

Once the above three components are in place, the EmpowerID Reverse Proxy is ready to protect your Web resources from unauthorized access. The flow for this is depicted below.

1. The user requests a resource from a Web server that is protected by the EmpowerID Reverse Proxy.
2. The EmpowerID Reverse Proxy intercepts the request and redirects the browser to the EmpowerID Identity Provider Services.
3. The EmpowerID Identity Provider Services presents the EmpowerID Login page to the user.

4. The user submits credentials back to EmpowerID. As EmpowerID is able to be configured as an authentication hub that supports trusted relationships with all major Identity Providers (IdP), users can be given the ability to authenticate with credentials as diverse as a Salesforce login, a social media login, or an EmpowerID login. The only prerequisite is EmpowerID must be configured to trust the third-party IdP and users must have an EmpowerID Person that can be linked to the IdP account.

   When third-party Identity Providers are used, external Web applications need only to trust EmpowerID. EmpowerID verifies the identity of the user and passes as assertion of that identity to the application as an EmpowerID Person regardless of the method used for authenticating.
5. The user's credentials are verified against the EmpowerID Identity Warehouse.
6. The user's browser is redirected back to the EmpowerID Reverse Proxy server with a cookie containing the identifier information for the user. This information includes the PersonID of the EmpowerID Person, the Account Logons and SSO GUIDs for each SAML SSO Connection they have authenticated against.
7. The EmpowerID Reverse Proxy embeds a variable named "eid_user" with the EmpowerID Logon name of the authenticated user into the HTTP Header and directs the browser to the Web server in order to fetch the requested resource. The Web server, in turn, services the request and sends the response back to the EmpowerID Reverse Proxy.
8. The EmpowerID Reverse Proxy relays the response back to the user. Other than authenticating to EmpowerID, the entire process is transparent to the user.

• Related Topics

  Administrative Procedures:

  • Installing the EmpowerID Reverse Proxy
  • Registering WAM Applications in EmpowerID
  • Configuring WAM Applications for the EmpowerID Web Agent