Overview of the EmpowerID Application Gateway

The EmpowerID Application Gateway is a dockerized KONG module that is a key component of any Zero Trust or microservices security architecture. As a component of the EmpowerID WAM System, the Application Gateway stands in front of protected Web applications and Docker containers, restricting access to the resources served by those applications by intercepting all HTTP traffic bound for those applications, evaluating and processing each request using EmpowerID's hybrid RBAC / ABAC / PBAC engines.

As a WAM component, the EmpowerID Application Gateway provides Web environments with seamless access to all of the identity management facilities of EmpowerID. This means that organizations can use the EmpowerID Application Gateway to provide the same level of security to the resources that live on their Web servers and API endpoints 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 users authenticate using OpenID Connect to our IdP, the EmpowerID RBAC / ABAC engine controls all facets of access for those users in accordance with the policy applied to them.

EmpowerID Application Gateway Components

The EmpowerID Application Gateway controls access to web applications and APIs without requiring the installation of an agent. To configure the Application Gateway, an OpenID Connect OAuth application record is created in EmpowerID with an associated SAML connection linked to it for use in defining attribute statements. The Application Gateway does not communicate with the SQL back-end and uses this OAuth connection when making API calls to the EmpowerID REST endpoints to retrieve its configuration and for real-time ABAC access checks. Web applications protected by the Application Gateway are created in EmpowerID as web applications with their protected URLs and paths registered as "Application Subcomponents." RBAC and ABAC policies can be applied to determine who may have access to these subcomponents/URL paths. After creating the appropriate Application Gateway components in the EmpowerID Web interface, you configure the Application Gateway files with the appropriate information for your environment. The below diagram shows all the components and configuration files associated with the EmpowerID Application Gateway. A description of each follows the diagram.

Web Access Management Applications

Web Access Management (WAM) applications represent the specific sites protected by the EmpowerID Application Gateway. As such, each WAM application is a service provider represented in EmpowerID with a unique SAML 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 Application Gateway responds to requests for resources in a manner familiar to 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 is serviced.
On the other hand, if the request represents an unrestricted resource that requires no identity proofs to access, then the Application Gateway services the request without requiring users authenticate or checking to see if they have the appropriate delegations.

You create WAM applications in EmpowerID by navigating to the Applications and Connections page of the EmpowerID Web application and selecting Create Application. This opens a generic interface for all applications where you can select the SSO Connection specific to WAM applications.

This connection offers a form with a number of fields common to all SSO applications, such as the Name, Description, and Certificate fields, as well as additional fields specific to WAM applications. These include:

the Base URL field,
options to allow anonymous access to unprotected paths, and
options to use the target host name when sending requests to the protected Web application.

The Base URL field is important because this is where you specify the address of the Web site to protect and the GUID of the SAML connection for that Web site, such as www.empowerid.com/5a1c4be2-4854-4bd5-b1a8-3d166afaa7c8. You can have as many WAM applications as needed to protect your sites; however, each WAM application can only be mapped to one SAML connection.

So 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 the paths on the Web server you want to protect. When you create a WAM application, you designate the path or paths on the Web server to restrict by adding an Application Subcomponent for each path.

When users first attempt to access a protected path, the Application Gateway checks to see if there are any directs them to the EmpowerID Identity Provider, where they must log in. Once authenticated, the Application Gateway makes an API call for all the resources on the Web server the user has access to. The EmpowerID RBAC / ABAC engine returns a real-time list of access back to the Application Gateway, where it is cached for a specified period of time and then updated. Caching times default to five minutes for RBAC data and two minutes for ABAC data.

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 set up additional requirements such as multi-factor authentication for users accessing more sensitive URLs. The matching options for an Application Subcomponent are as follows:

The default path for an Application Subcomponent is /. This specifies everything on the Web server. To control access to everything on the server, create the Application Subcomponent without specifying a matching option.

Full URL (Exact Match Path) — Specify an exact URL to restrict. For example, to restrict access to a specific page such as www.empowerid.com/customers/reports enter www.empowerid.com/customers/reports in this field.
Pattern Match Path — Enter a JavaScript regular expression pattern to restrict any URLs matching the pattern. Regular expression patterns can be strings of simple characters, special characters, or combinations of both.
- Simple Characters — Specify a string of simple characters to restrict any URLs with character sequences matching the string, regardless of where those characters occur within a path.
  
  For example, to restrict access to any URL containing delete, e.g. operation=delete and deletedreports, enter delete as the pattern match. When users enter a URL like www.empowerid.com/personid24/operation=delete or www.empowerid.com/view/deletedreports, they are 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, to restrict access to all paths containing the words reports and accounts, you can add reports|accounts as the pattern match. If a user attempts to access a URL like www.empowerid.com/customers/reports/customerid=12 or a URL like www.empowerid.com/useraccounts, the user is redirected to the login page for the EmpowerID Web application.
Starting Path — Restrict any URL with a specific beginning path appended to the Hostname of the associated Application Gateway application.

For example, if you have a Application Gateway 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.

For step-by-step guidance on creating WAM applications, see Creating WAM Applications.

OAuth Application

As mentioned above, the Application Gateway makes API calls to EmpowerID to collect RBAC data on each person in your environment. In order to make the necessary API calls, the SAML connection for the WAM application must have an OAuth application with an owner who has the access to make those calls. When you create the application, EmpowerID generates an API Key, a Client ID (Key), and a Client Secret that you use when you configure the Application Gateway

EmpowerID Application Gateway Configuration Files

In addition to creating the above applications in EmpowerID, you need to configure the EmpowerID Application Gateway for your specific environment. To do this, you can do one of two things, you can create a directory on your linux machine and create the appropriate files with hard-coded values or you can pass those values at runtime, using environment variables (e.g. env CLIENT_ID). The below code shows what the default proxy.nginx file looks like with elements to enable the modsecurity module. The modsecurity module protects against such Layer 7 attacks as SQL injection (SQLi) and cross-site scripting (XSS).

A description of the settings follows the code.

load_module modules/ngx_http_modsecurity_module.so;   
worker_processes 1;

error_log logs/error.log debug;

events {
	 multi_accept   on;
    worker_connections 1024;
}

env CLIENT_ID;
env CLIENT_SECRET;
env EMPOWERID_API_KEY;
env CERTIFICATE_THUMBPRINT;
env CERT_FILE_PASSPHRASE;
env SERVICE_PROVIDERS_GUIDS;
env DISCOVERY;
env HASACCESSTOPAGE_ENDPOINT;
env GET_RESULTS_ENDPOINT;
env TOKEN_ENDPOINT;
env SCHEMA_HOST_PORT;

http {
    tcp_nodelay off;
    tcp_nopush on;

    upstream backend_hosts {
    server 35.153.255.7;
}

    resolver 8.8.8.8 ipv6=off;
    # cache for discovery metadata documents
    lua_shared_dict discovery 1m;
    # cache for JWKs
    lua_shared_dict jwks 1m;
    lua_shared_dict sessions 10m;
    lua_shared_dict empowerid_proxy_config 10m;

    init_worker_by_lua_block {
        local opts = {
            redirect_uri_path = "/oauth2callback",
			ssl_verify="no",
			logout_path = "/logout",
			cert_file="/usr/local/openresty/nginx/conf/file.pem",
			oauth_grant_type="urn:ietf:params:oauth:grant-type:jwt-bearer",

            discovery = os.getenv("DISCOVERY),
            client_id =  os.getenv("CLIENT_ID),
			client_secret = os.getenv("CLIENT_SECRET"),
            service_providers_guids = os.getenv("SERVICE_PROVIDERS_GUIDS"),
            hasaccesstopage_endpoint = os.getenv("HASACCESSTOPAGE_ENDPOINT"),
            empowerid_api_key = os.getenv("EMPOWERID_API_KEY"),
            get_results_endpoint = ("GET_RESULTS_ENDPOINT"),
			token_endpoint = OS.GETENV("TOKEN_ENDPOINT"),
            certificate_thumbprint=os.getenv("CERTIFICATE_THUMBPRINT"),
			cert_file_passphrase=os.getenv("CERT_FILE_PASSPHRASE"),
			schema_host_port=os.getenv("SCHEMA_HOST_PORT")
        }
        require"empowerid.proxy"(opts)
    }



    server {
		server_name FQDN of your EmpowerID server
        listen 443 ssl;

		modsecurity on;
		modsecurity_rules_file/usr/local/openresty/nginx/conf/main.conf

		ssl_certificate/usr/local/openresty/nginx/conf/certificate.crt;
		ssl_certificate_key/usr/local/openresty/nginx/conf/keyfileencrypted.key
		ssl_password_file/usr/local/openresty/nginx/conf/global.pass;

		location~\.(gif|png|js|css|ico|woff|woff2)${
		expires 1y;
		proxy_pass http:/backend_hosts;

        location / {
            set $session_storage shm;

            access_by_lua_block {
                require"empowerid.proxy"()
            }
            proxy_http_version 1.1;
            proxy_redirect off;
            proxy_set_header X-Forwarded-Host $host;
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header Connection "";

            proxy_pass http://backend_hosts;
        }
    }    
}

load_module modules/ngx_http_modsecurity_module.so
- Specifies that the Application Gateway use the modsecurity module and specifies the path to it.
env CLIENT_ID
- Environmental variable that specifies the Client ID of the OAuth application linked to the SAML connection you created for the WAM application.
env CLIENT_SECRET
- Environmental variable that specifies the Client Secret of the OAuth application linked to the SAML connection you created for the WAM application.
env EPOWERID_API_KEY
- Environmental variable for the API Key of the OAuth application.
env CERTIFICATE_THUMBPRINT
- Environmental variable for the thumbprint of the STS certificate used in your EmpowerID deployment.
env CERT_FILE_PASSPHRASE
- Environmental variable for the passphrase used to encrypt the certificate file.
env SERVICE_PROVIDERS_GUIDS
- Environmental variable for the GUID(s) of the SAML connection(s) created for the WAM application. You can have up to 10 service provider GUIDS. If more than one is specified, they must be comma separated.
env DISCOVERY
- Environmental variable that specifies the path to OpenID Connect configuration data in your environment. To specify the path, change the FQDN in the file to that for your environment. Once you have specified the correct path, you can navigate to it in your browser to view the supported OpenID configuration data.
env HASACCESSTOPAGE_ENDPOINT
- Environmental variable that specifies the API endpoint the Application Gateway calls to determine whether the user making the request for a resource is authorized to view it. To set this value, you change the default FQDN to that for your environment.
env GET_RESULTS_ENDPOINT
- Environmental variable that specifies the API endpoint the Application Gateway calls to retrieve the RBAC / ABAC data. To set this value, you change the default FQDN to that for your environment. The data returned by the endpoint includes the following.
  - PersonIDs,
  - Account Logins,
  - Application Gateway Application Resource IDs, and
  - the URL patterns (ProtectedApplicationURL applications) associated with each.
env TOKEN_ENDPOINT
- Environmental variable that specifies the endpoint for the OAuth token. To set this value, you change the default FQDN to that for your environment.
env SCHEMA_HOST_PORT
- Environmental variable that specifies the audience URL in the access token request.
proxy_pass
- Backend_hosts specifies the IP address of the EmpowerID server you are trying to protect. If forwarding is specified, the corresponding listening point must be specified.
modsecurity_rules_file — Specifies the location of the main.conf file. The main.conf file contains the configuration data for loading the modsecurity.conf file, the crs-setup.conf file, as well as other CRS rules. main.conf contains the below code:
- Include /usr/local/openresty/nginx/conf/modsecurity.conf — Specifies the location of the modsecurity.conf file. EmpowerID copies this file into the specified location when the container runs.
- Include /usr/local/openresty/nginx/conf/crs-setup.conf — Specifies the location of the crs-setup.conf file. EmpowerID copies this file into the specified location when the container runs.
- Include /usr/local/owasp-modsecurity-crs-3.0.0/rules/REQUEST*.conf — Owasp rules set is included in the @/usr/local/owasp-modsecurity-crs-3.0.0/rules/ container. In this example, we are specifying that modsecurity include all files that start with REQUEST.
- Include /usr/local/owasp-modsecurity-crs-3.0.0/rules/RESPONSE*.conf — Owasp rules set is included in the @/usr/local/owasp-modsecurity-crs-3.0.0/rules/ container. In this example, we are specifying that modsecurity include all files that start with RESPONSE.

As mentioned above, EmpowerID supports the use of variables that you can pass in the docker command to run the Application Gateway versus hard-coding those values in the proxy.nginx or ssl.nginx files. When passing variables at runtime the command would look similar to that depicted below. The values would be substituted for those in your environment.

Variables must be passed using -e followed by key/value pairs.

sudo docker run -d -p 80:80 --name empowerid_proxy -e "CLIENT_ID=6c3e74b6-7dfb-441f-ac2e-519ceb353a70"  -e "CLIENT_SECRET=a7aefdf6-1077-485d-bc03-e33b7a4c0229"  -e "APIKEY=6510a7ea-fcf5-4d16-90c9-c0734ed720d9"   
-e "CERTIFICATE_THUMBPRINT="C190A8D464E891EE7A7EDCE1EDFFA79BC9034C94" -e "CERT_FILE_PASSPHRASE=passphrase" -e "SERVICE_PROVIDER_GUIDS=C56B1255-42AF-4734-8D6D-EDF17460DA30" -e "DISCOVERY=https://sso.empoweriam.com/oauth/.well-known/openid-configuration" -e "HASACCESSTOPAGE_ENDPOINT=https://sso.empoweriam.com/api/services/v1/hasaccess/hasaccesstopage" -e "GET_RESULTS_ENDPOINT=https://sso.empoweriam.com/api/services/v1/ReverseProxy/GetResults" 
-e "TOKEN_ENDPOINT=https://sso.empoweriam.com/oauth/v2/token"  empowerid/nginx_preconf

Putting it all together

Once all components are in place, the EmpowerID Application Gateway is ready to protect your Web resources from unauthorized access. Here is the flow for this.