37.3 Reverse Proxy Based Single Sign-On

You can configure Access Manager to provide protected access to the Identity Manager web resources (identity applications and Identity Reporting) by using a domain-based proxy service and single sign-on access by using a form fill policy.

You can either use an existing reverse proxy and add a new proxy service for protecting the web resources or configure a new reverse proxy. While configuring the reverse proxy, create domain-based services for the servers hosting OSP and SSPR, identity applications, and Identity Reporting to enable single sign-on. You must configure these web resources as protected resources and specify the authentication procedures and the policies that should be used to enforce protection.

This section discusses a domain based proxy-service method with an example configuration. For more information about these proxy-service methods, see the NetIQ Access Manager 4.5 Administration Guide. Use information from the following table to understand the configuration required for different deployment scenarios.

NOTE:In a distributed environment, if your applications do not have a common domain name and reverse proxy is configured, then you cannot access the applications even after adding the com.netiq.oauth.domain parameter in ism-configuration-properties file.

Table 37-1 Sample Configuration

Deployment Scenario

Published DNS Name

Web Server Host Name

HTML Rewriting

Protected Resources

Form Fill

All components on the same server

rbpm.mycompany.com

rbpm.privatedns.com

Enable the following:

  • Rewrite Inbound Query String Data

  • Rewrite Inbound Headers

  • Enable Rewrite Actions

/*

Or

/osp/*

/sspr/*

/idmdash/*

/idmadmin/*

/IDMPROV/*

Page Matching Criteria <title>NetIQ Access</title>

Required only for OSP.

OSP and SSPR on a different server

osp.mycompany.com

osp.privatedns.com

Enable the following:

  • Rewrite Inbound Query String Data

  • Rewrite Inbound Headers

  • Enable Rewrite Actions

/osp/*

/sspr/*

Page Matching Criteria <title>NetIQ Access</title>

Required only for OSP.

Identity Applications on a different server

identityapplications.mycompany.com

identityapplications.privatedns.com

Enable the following:

  • Rewrite Inbound Query String Data

  • Rewrite Inbound Headers

  • Enable Rewrite Actions

/idmdash/*

/idmadmin/*

/IDMPROV/*

 

Identity Reporting on a different server

RPT.mycompany.com

RPT.privatedns.com

Enable the following:

  • Rewrite Inbound Query String Data

  • Rewrite Inbound Headers

  • Enable Rewrite Actions

/IDMRPT/*

/IDMDCS/*

 

You must be familiar with NetIQ Access Manager capabilities to understand the context of the content in this section. For more information about NetIQ Access Manager, see the Access Manager documentation website.

37.3.1 Creating and Configuring the Proxy Service

This section assumes that you have installed:

  • NetIQ Access Manager and a NetIQ Access Manager Access Gateway

  • All identity applications components on a single server (first scenario in Table 37-1)

You will first create a reverse proxy, for example rbpm, and then configure it to include domain-based multi-homed proxy services.

Remember that for the Web Server IP Address setting of the proxy service, you need to specify the IP Address for the identity applications server, and for the Web Server Host Name setting of the proxy service, you need to specify the DNS name of the identity applications web server.

  1. Log in to the Administration Console. For example, https://idmnam.acmeinfotech.com/nps.

  2. Click Devices > Access Gateways > AG-Cluster > NAM-RP.

  3. Generate a certificate key by using the Access Manager CA:

    1. Click Auto-generate Key, then click New twice.

    2. Specify a name for the certificate. For example, certificate_proxy_wildcard.

    3. Click Edit on the Subject line and specify Common name as *.acmeinfotech.com.

    4. Click OK twice, then click the name of the certificate.

    5. Click OK to ensure that all CA certificate chains of the selected certificate are added to the appropriate trust stores.

  4. In the Proxy Service List section, click New.

    1. Specify the following information:

      Proxy Service Name: Specify a name that intuitively identifies this service on your Access Gateway server. For example, specify rbpm.

      Multi-Homing Type: Select Domain-Based. The Access Gateway will use this method to identify the proxy service.

      Published DNS Name: Specify the DNS name you want the public to use to access the web server. This DNS name must resolve to the IP address you set up as the listening address. For example, rbpm.mycompany.com

      Web Server IP Address: Specify the IP address of the web server you want this proxy service to manage. You can specify additional Web server IP addresses by clicking the Web Server Addresses link when you have finished creating the proxy service.

      Host Header: Specify the Web Server Host Name option. This allows the HTTP header to contain the published DNS name.

      Web Server Host Name: Specify the DNS name of the server hosting the application to which the Access Gateway should forward requests. This entry matches what you specify in the Published DNS Name field.

      NOTE:If OSP and Identity Applications are installed in a distributed environment, perform these actions for each service. In this case, the published DNS Name will be different for each service.

    2. Click OK.

  5. Click the newly added proxy service (rbpm), then select the Web Servers tab.

    The Web servers added to this list must contain identical web content. Configuring your system with multiple servers with the same content adds fault tolerance and increases the speed for processing requests.

    For caching to work correctly, the web servers must be configured to maintain a valid time. They should be configured to use an NTP server.

    1. To enable SSL connections between the proxy service and its web servers, select Connect Using SSL and select Do not verify or Import SSL Mutual Certificate for the Web Server Trusted Root option.

      Use Do not verify when you want the information between the Access Gateway and the identity applications server encrypted, but you do not need the added security of verifying the certificate of the identity applications server.

      Use Import SSL Mutual Certificate to set up mutual authentication so that the identity applications server can verify the proxy service certificate.

    2. In the Connect Port field, specify the port that the web server uses for SSL communication. This is the port that the identity applications server is listening from Access Gateway. For example, by default, the listening port is 8180.

      If the identity applications server is listening on an SSL port, ensure that you specify that port and enable Connect Using SSL.

      If identity applications are listening on a non-SSL port, ensure that you configure that port and verify that Connect Using SSL is disabled.

    3. Leave the other settings unchanged.

    4. Click OK.

    5. Under Access Gateway Servers, click Update All for AG-Cluster to apply changes of reverse proxy service created.

37.3.2 Creating Protected Resources

After creating the proxy service, create protected resources with resource paths to all applications that are configured. The protected resource configuration specifies the authentication procedures and the policies that should be used to enforce protection.

To create a resource for the identity applications:

  1. Log in to the Access Manager Administration Console.

  2. In the console, click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Domain-Based Proxy Service or Primary Proxy Service] > Protected Resources.

  3. Create a protected resource.

    1. Select New, then specify a display name for the new resource you want to protect.

      For example, to create a resource that you want to use to represent all identity applications resources, you can name the resource as osp_protected_resources.

      When you create the display name, the Overview page for the new resource is displayed.

    2. Fill in the fields to configure the resource:

      Description: Specify a description for the protected resource. You can use it to briefly describe the purpose for protecting this resource.

      Authentication Procedure: Select Name/Password -Form from the drop-down list. This specifies a form-based authentication over HTTP or HTTPS, using the Access Manager login form.

      URL Path List: Remove the /* path and add paths for Published DNS Name, rbpm.mycompany.com.

      For example, include the following paths for OSP and SSPR protected resource:

      /osp/*
      /sspr/*

      For the identity applications protected resource, include the following paths:

      /idmdash/*
      
      /idmadmin/*
      /IDMPROV/*

      For Identity Reporting protected resource, include the following path:

      /IDMRPT/*
      /IDMDCS/*

      Click OK.

    3. Click the Protected Resources breadcrumb at the top of the Overview page to return to the Protected Resources page.

    4. In the Protected Resource List, ensure that the protected resources you created are enabled.

    5. To apply your changes, click Devices > Access Gateways, then click Update.

  4. Continue with Creating a Form Fill Policy for the newly created protected resources.

37.3.3 Creating and Assigning a Form Fill Policy to a Protected Resource

You must create a Form Fill policy and assign it to the OSP protected resource. This Form Fill policy will match the OSP login form and fill the user credentials for single sign-on. The policy also includes a failure policy which will redirect the identity applications logout request to also do the Access Gateway logout.

Form Fill policy must be applied to only the OSP protected resource and not for identity applications or Identity Reporting protected resources because these applications will be automatically redirected to the OSP login page if a user is not logged in.

To create a Form Fill Policy for the OSP protected resource:

  1. In the Administration Console, click Policies > Policies.

  2. Select the policy container, then click New.

  3. Specify a name for the policy, select Access Gateway: Form Fill as the type of the policy, then click OK. For example, osp_form_fill

  4. (Optional) Specify a description for the Form Fill policy. This is useful if you plan to create multiple Form Fill policies.

  5. In the Actions section, click New, then select Form Fill.

  6. In the Form Selection section, perform the following actions:

    1. Select Form Name Specify the name of the form. For example, IDPLogin.

    2. Select Page Matching Criteria. This causes the Access Gateway to search the HTML page for the specified text. If the specified text is found on the page, the page is a match for the policy. If it is not found, the page is not a match for the policy and the policy is not applied. For example, suppose your HTML page has the following string within the <FORM> element:

      <title>NetIQ Access</title>

      If you enter this string in the Page Matching Criteria box, the Access Gateway searches the form for this string. If it finds the string, it knows it has a match (get this unique tag from page source of OSP Login screen).

  7. In the Fill Options section, create an entry for all the input fields and select options in the form. For each input field or select option, you need to specify the following information:

    • Input Field Name: Specifies the name of the field or option. This is the name attribute of the element on the form. For example, Ecom_User_ID

    • Input Field Type: Specifies the type attribute for the input field or select option in the form. Select Text.

    • Input Field Value: Specify the value for the field. You must specify the data type, then enter the value. Select Credential Profile: LDAP Credentials: LDAP User Name

    1. Click New and specify the values for the following fields:

      • Input Field Name: Ecom_Password

      • Input Field Type: Password

      • Input Field Value: Credential Profile: LDAP Credentials: LDAP User Name

  8. In the Submit Options section, select Auto Submit.

    This action indicates you want the form submitted to the Web server without having the user confirm the submission by clicking a Submit button. If this option is not selected, Form Fill can fill in the data, but the user must click the Submit button before the data is sent to the Web server. When the form is not auto submitted, all the JavaScript on the form is executed.

  9. To create a login failure policy, click New in the Actions section, then select Form Login Failure.

  10. In the Form Selection section, perform the following actions:

    1. Select CGI Matching Criteria. This allows the Access Gateway to evaluate the query string in the URL (the portion after the question mark) to differentiate pages that have the same URL. Type logout.

  11. In the Login Failure Processing section, specify the Access Gateway URL in the following field:

    • Redirect to URL: Specify https://idmnam.mycompany.com/AGLogout.

      When an LDAP or NSS error occurs, the user is redirected to the URL you specify in the text box.

  12. Use the up-arrow button to move the Form Login Failure policy to the top of the policy list.

    You want the failure policy to execute first on login failure.

  13. Click OK.

  14. Click OK, then click Apply Changes and close the Policies window.

  15. To enable the policy you just created (osp_form_fill), click Enable.

  16. Click OK in the Protected Resources tab.

  17. Continue with configuring HTML rewriting for the proxy service.

37.3.4 Configuring a Rewriter Profile

The changes you make to the NetIQ Access Gateway configurations for the protected resources require HTML rewriting because the web servers hosting the protected resources are not aware that the Access Gateway system is obfuscating their DNS names. URLs contained in these pages must be checked to ensure that these references contain the DNS names that the client browser understands. On the other end, the client browsers are not aware that the Access Gateway is obfuscating the DNS names of the resources they are accessing. The URL requests coming from the client browsers that use published DNS names must be rewritten to the DNS names that the identity applications web servers expect. For more information, see Configuring HTML Rewriting in the NetIQ Access Manager 4.4 Administration Guide.

When you configure the HTML rewriter for a proxy service, these values are applied to all the resources protected by this proxy service. Keeping everything as default, enable Rewrite Inbound Query String Data, Rewrite Inbound Headers, and Enable Rewrite Actions in this profile and then move this custom profile above the Default profile and save the configuration. Perform this action for all the services in a distributed setup.

  1. Log in to the Access Manager Administration Console.

  2. Click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] > HTML Rewriting.

  3. Click HTML Rewriter Profile List to create a profile.

    New: Specify a display name for the profile. For example, idmnamrewriter_custom.

    Word: Select Word for Search Boundary. A Word profile searches for matches on words. For example, “get” matches the word “get” and any word that begins with “get” such as “getaway” but it does not match the “get” in “together” or “beget.”

  4. Navigate to the rewriter profile that you created from HTML Rewriter and ensure the following fields are selected:

    • Rewrite Inbound Query String Data

    • Rewrite Inbound Headers

    • Enable Rewrite Actions

  5. Click OK.

  6. In HTML Rewriter Profile List, move the Word profile to be the first profile in the list.

  7. To save your changes, click OK.

  8. To update the Access Gateway, the cached pages affected by the rewriter changes must be updated on the Access Gateway. Click OK to purge all cache.To apply your changes, click the Access Gateways link, then click Update > OK.

37.3.5 Configuring Identity Providers

User stores are LDAP directory servers to which end users authenticate. You must specify an initial user store when creating an Identity Server configuration. You use the same procedure for setting up the initial user store, adding a user store, or modifying an existing user store.

  1. Log in to NetIQ Access Management Administration Console. For example, https://idmnam.mycompany.com/nps.

  2. Navigate to Devices > Identity Servers > AG-Cluster > Edit > Local.

  3. In User Stores, click New to add a user store. This is the Identity Vault used by your Identity Manager.

  4. Fill in the following fields:

    Name: The name of the user store for reference. For example, acmeidm

    Admin Name: The distinguished name of the admin user of the LDAP directory, or a proxy user with specific LDAP rights to perform searches. For the LDAP extension to work, the proxy user requires write rights on the ACL. Administrator-level rights are required for setting up a user store. This ensures read/write access to all objects used by Access Manager.

    For example, cn=admin,ou=sa,o=system

    Admin Password and Confirm Password: Specify the password for the admin user and confirm it.

    Directory Type: The type of LDAP directory. Select eDirectory.

    If eDirectory has been configured to use Domain Services for Windows, eDirectory behaves like Active Directory. When you configure such a directory to be a user store, its Directory Type must be set to Active Directory for proper operation.

  5. To specify a server replica, click New, then fill in the following fields:

    For an eDirectory server, you must use a replica of the partition where the users reside. Ensure that each LDAP server in the cluster has a valid read/write replica. One option is to create a users partition (a partition that points to the OU containing the user accounts) and reference this server replica.

    Name: Specify the name of the Identity Vault used by the Identity Manager server.

    IP Address: The IP Address of the Identity Vault used by the Identity Manager server. If your eDirectory is replicated on multiple servers, use this name to identify a specific replica.

    Use secure LDAP connections: Specifies that the eDirectory server requires secure (SSL) connections with the Identity Server.

    This is the only configuration we recommend for the connection between the Identity Server and the eDirectory server in a production environment. If you use port 389, usernames and passwords are sent in clear text on the wire.

    Name: The display name for the eDirectory server. If your eDirectory is replicated on multiple servers, use this name to identify a specific replica.

  6. To import the trusted root certificate from the eDirectory server, click Auto import trusted root.

  7. Click OK to confirm the import.

    The Root CA Certificate and Server Certificate are imported into the Access Manager server keystore.

  8. To add a search context, click New under Search Contexts and define the search context o=context (for example: o=data) and define the search scope as Subtree.

    The search context is used to locate users in the directory when a contract is executed.

  9. Click Finish.

  10. Navigate to Local > Methods and select the following authentication class:

    Secure Name/Password - Form: Form-based authentication over HTTPS.

  11. Locate the user store that you just created (acmeidm) under User stores and move it under Available user stores.

  12. Click Apply and OK.

  13. If prompted to restart Tomcat, click OK. Otherwise, update the Identity Server. Open the Identity Servers window > Servers > Update All > IDPCluster and apply the changes and ensure it is current and green.

37.3.6 Configuring Additional Redirect URLs in OSP Configuration File

  1. Install the latest OSP version.

  2. Stop the Tomcat services (systemctl status netiq-tomcat.service).

  3. Edit the ism-configuration.properties file from tomcat/conf and append ‘additional.redirect.urls’ entries in the file based on the published DNS names. For this example, the entries can look like below:

    ospservice:/opt/netiq/idm/apps/tomcat/conf # cat ism-configuration.properties | grep redirect
    com.netiq.idmdash.redirect.url = https://rbpm.mycompany.com:8543/idmdash/oauth.html
    com.netiq.idmdash.additional.redirect.urls = https://rbpm.privatedns.com/idmdash/oauth.html
    com.netiq.rbpm.redirect.url = https://rbpm.mycompany.com:8543/IDMProv/oauth
    com.netiq.rbpm.additional.redirect.urls = https://rbpm.privatedns.com/IDMProv/oauth
    com.netiq.rpt.redirect.url = https://RPT.mycompany.com:8543/IDMRPT/oauth.html
    com.netiq.rpt.additional.redirect.urls = https://RPT.privatedns.com/IDMRPT/oauth.html
    com.netiq.sspr.redirect.url = https://osp.mycompany.com:8543/sspr/public/oauth
    com.netiq.sspr.additional.redirect.urls = https://osp.privatedns.com/sspr/public/oauth
  4. Start the Tomcat service (systemctl status netiq-tomcat.service).

IMPORTANT:If you have configured additional redirect URLs, you may observe a redirect URL mismatch error in the logs after upgrading to Identity Manager 4.8.6. You will be unable to log in to the application.

To resolve this issue, remove the following entries in the ism-configuration.properties file:

com.netiq.idmdash.additional.redirect.urls = https://rbpm.privatedns.com/idmdash/oauth.html
com.netiq.rpt.additional.redirect.urls = https://RPT.privatedns.com/IDMRPT/oauth.html

Save the file and start the Tomcat service.

37.3.7 Testing the Single Sign-On

  1. Open a browser and launch the NAM URL protecting the identity applications.

    For example: https://rbpm.privatedns.com/IDMProv/

    Ensure that the URLs are resolvable either through the host entries or DNS.

  2. On the authentication prompt, provide the user credentials in Secure Name/Password - Form. For example, uaadmin and password.

  3. Upon submitting the credentials you should be able to view Identity Applications Dashboard.

  4. Access other pages also and you can observe the SSO experience.

    For example: https://rbpm.privatedns.com/idmadmin