Registering WAM Applications

Custom Web applications can be registered for use with EmpowerID through the EmpowerID Web Access Management system (WAM). This allows organizations with custom Web-based resources to leverage EmpowerID for the same end-to-end level of security EmpowerID provides for directory-based resources.

This topic demonstrates how to configure WAM applications for use with EmpowerID.

In this example, we demonstrate registering a .NET Web application that has been has been configured with assemblies from EmpowerID to pass user identities to the application via HTTP Headers. For information on configuring .NET Web applications for integration with the EmpowerID Agent see Configuring .NET Web Applications for the EmpowerID Agent.

To register a WAM app in EmpowerID

  1. From the Navigation Sidebar, navigate to the Application Management page by expanding Applications and clicking Manage Applications.
  2. From the Actions pane of the Application Management page, click the Create Application action.

    3. This opens the Application Details form, which contains various tabs and fields for creating the application.

  3. From the General tab of the Application Details form, do the following:
    1. Type an appropriate name, display name and description for the application in the Name, Display Name and Description fields, respectively.
    2. Leave the Icon field set to its default value.
    3. Select or deselect Allow Access Requests to specify whether to allow access requests. When this option is selected, the application appears in the IT Shop, allowing users to request or claim an account in the application.
    4. Select or deselect Allow Claim Account to specify whether to give users the ability to claim an account they have in the application. When this option is selected, users can claim their accounts and gain instant access after passing the requisite identity proofs.
    5. Select or deselect SSO Enabled to specify whether the application is an SSO app. This should be selected.
    6. Select or deselect Requires Account For SSO to specify whether users must have an account in the application for SSO. This should be selected.
    7. Select or deselect Allow Request Account to specify whether to allow users to request an account in the application. When this option is selected and Allow Access Requests is selected, users can request an account in the application.
    8. Select or deselect Login Is Email Address to specify whether the login for the application is an email address. This setting is necessary for passing the appropriate identity assertion to the application when logging in from EmpowerID.
    9. Select or deselect Make me the Application Owner to specify whether you are the owner of the application. Application owners have the ability to manage the application and approve or deny access requests.
    10. Configure Advanced Claim and Request Account Options - Select this option and then provide the appropriate advanced configuration information if you have custom pages and workflows configured in EmpowerID for processing access requests as well as for managing any accounts linked to the application's (internal to EmpowerID) account directory.
  4. Click the Single Sign-On tab and select Web Access Management (HTTP Header) from the Single Sign-On Connection Type drop-down.

    5. This opens the WAM Connection Information section of the form. You use this section to build the SSO Connection for the Web application. A description of the fields in this section follows.

    • Display Name - Specifies the name for the WAM SSO Connection that you want to appear to users in the EmpowerID user interfaces. By default EmpowerID adds the Display Name value for the SSO application to this field. You can change it as desired.
    • Base URL - Specifies the URL you want users to type in their browsers to access the Web application you are registering. This is the URL the Proxy Server intercepts, not necessarily the real address of the protected application. For example, if you want users to type sso.empowerid.com/andysbeans to reach a Web application located at www.example.com/andybeans, you would enter sso.empowerid.com/andysbeans here.
    • Description - Specifies a description for the WAM SSO Connection.
    • Allow Anonymous Access to Unprotected Paths - Specifies whether access is allowed to specified target sites without requiring users authenticate against the EmpowerID Identity Provider.
      • As a best practice, you should not allow anonymous access to unprotected paths.
    • Use Target Hostname in Requests - Specifies whether the EmpowerID Reverse Proxy should alter the Host Header to include the target host name rather than the URL typed in to the browser's address bar by users. By default, the EmpowerID Reverse Proxy passes the URL typed by users to the Web application; however, in situations where the target Web application expects to see the target host name in any requests sent to it, you can select this option to have the Reverse Proxy modify the Host Header accordingly.
    • Certificate - Specifies the certificate for signing SAML assertions in your environment.
    • Routes - Routes are used by the EmpowerID Reverse Proxy to translate the URLs requested by clients to the URLs where those requests can be serviced on the Web application. Each route is comprised of a Target URL/Source URL value pair comprised of two sets of host, port and path combinations, such as "www.andysbeans.com/customers" and "10.0.0.4/customers," where www.andysbeans.com/customers represents the Source URL typed in to a browser window by a user and 10.0.0.4/customers represents the destination or Target URL where the user's request is to be serviced. When an HTTP request reaches the proxy server, 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. Routes 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. Table 1 below shows a number of Target URL/Source URL pairing combinations.
      • You can have as many Target URL/Source URL value pairs configured as needed; however, you must always have at least one that represents the Base URL of the Web application or the proxy server will error.
      Table 1: Source URL/Target URL Value Pairs in WAM Routes
      WAM Routes
      Source URL (Client Request) Target URL (Translated Value)
      www.andysbeans.com 10.0.0.4
      www.andysbeans.com/customers www.andysbeans.com:8080/allcustomers
      www.andysbeans.com/customers/oh www.andysbeans.com:8080/allcustomers/oh
      www.andysbeans.com/customers 10.0.0.4/customers
      www.andysbeans.com/admin 10.0.0.5/admin
      www.andysbeans.com/customers/eu/gold 10.0.0.4/customers/eu/gold
      www.andysbeans.com/admin 10.0.0.5/admin
    • To add a WAM Route
      1. Click the Add WAM Routes (+) button on the Routes grid.

        2. This opens the WAM Routes dialog, which is where you specify the routes to be protected. A description of the fields follows the image.

        • Name - Specifies the name of the Route.
        • Display Name - Specifies the name for the Route that you want to appear to users in the EmpowerID user interfaces.
        • Description - Specifies a description for the Route.
        • Source URL - Specifies the actual location on the Web application to which the Proxy Server is to fetch resources on behalf of clients. This value is a translation of the above Target URL.
        • User Entered URL - Specifies the URL to which you want users or clients to navigate via their browsers to access given resources on the Web application.
        • Max Connections - For future implementation.
        • Is Base URL - Specifies whether the route is the base URL of the Web application. At least one route must be a Base URL route and you can more than one route translate to the same Source URL. This is helpful for situations where load-balancing is needed. When this is the case, and more than one route is configured for a User Entered URL, the Reverse Proxy Server will service the requests in a round-robin fashion.
        • Is Offline - Specifies whether the route is offline. If a route is offline, the Reverse Proxy Server will not service it.
        • Use Sticky Sessions - For future implementation.

        The following image shows what the Base URL WAM Route for an application in our environment looks like. In the image, we have configured the route to translate the Source URL," http://www.andysbeans.com/andysbeans," typed by clients in their browsers to "http://sso.empowerid.com:8080/andysbeans", which is the real location of the application's base URL.

      2. After filling in the fields for the WAM Route, click Add.

        3. You should see the Added flag update from 0 to 1. Clicking on the flag allows you to review the WAM route you are adding to the application.

        You can remove a WAM Route by clicking the Undo button to the right of the route.

      3. Repeat the above for each WAM Route you wish to add to the application.

  5. Click the Users tab and choose whether to create an new account directory for the application or select an existing account directory from which to add accounts for the application. If you choose to create a new account directory, EmpowerID creates a special type of account store internal to EmpowerID, known as a "tracking-only" account store. A tracking-only account store account exists as a container within EmpowerID for storing user and group records for SSO or attestation without making a connection to the external directory associated with the application. Opting to create a new account store when registering applications in EmpowerID is advantageous in that doing so creates a one-to-one correlation between the account store and the application, as well as the SSO connection for the application. In this example, we are opting to create a new account directory.
    6. If you create a new Account Directory, EmpowerID names the directory after the name of the application. So, if you register a Web application named "Andys Beans," the account directory will be named "Andys Beans" as well.

  6. Click the Application Subcomponents tab and add any URLs (paths) on the Web application you want to be RBAC-protected. These URL subcomponents represent the resource you wish to protect on a given Web application. When you add a URL subcomponent to an application, you designate the path or paths on the Web server to be restricted. Then when users first attempt to access the path, they are directed to the EmpowerID Identity Provider, where they must log in and request access to the path. Once access is granted, EmpowerID creates an account for that person that is linked to the WAM application via the Account Store ID for the application's Account Directory.

    • To add a URL Subcomponent
      1. Click the Add New Subcomponents (+) button.

        2. This opens the Name Information dialog for the subcomponent, which is where you specify the URLs to be protected. A description of the fields follows.

        • Name - Specifies the name of the subcomponent.
        • Display Name - Specifies the name for the subcomponent that you want to appear to users in the EmpowerID user interfaces.
        • Description - Specifies a description for the subcomponent.
        • Icon - Specifies the path to the image that represents the subcomponent, if any.
        • Allow Access Requests - Specify whether to allow access requests. When this option is selected, the application appears in the IT Shop, allowing users to request or claim an account in the application.
        • Full URL (Exact Match Path) - 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 type www.empowerid.com/customers/reports.aspx in this field.
        • Starts With Path - This allows you to specify that any URL with a specific beginning path appended to the Hostname of the associated Web application be restricted. For example, if you have a Web 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 type customers in this field.
        • Pattern Match Path - 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.

        The below image shows an example of what a URL subcomponent for a Web application looks like. In the image, we are adding a URL subcomponent that protects all paths on the Web application beginning with "employees." For the details on adding Application Subcomponents to an application, see the topic Adding Application Subcomponents to Applications.

      2. After filling in the fields for the URL subcomponent, click Add.

        3. You should see the Added flag update from 0 to 1. Clicking the flag allows you to review the URL subcomponent you are adding to the application.

        You can remove a subcomponent by clicking the Undo button to the right of the subcomponent.

      3. Repeat for each URL Subcomponent you wish to add to the application.

  7. Optionally, click the Groups tab and add any groups to the application. For more information on adding groups, see the Group Settings section of the Overview of Application Configuration Settings topic.
  8. After you have completed adding the settings for the application, click the Add to cart button at the bottom of the page to add the WAM application to your shopping cart.
  9. Click the My Cart link located at the top of the page and in the Cart dialog that appears type a reason for creating the application and then click Submit.