3.14 Configuring the Authentication Filter to Set Session-Based Identity Information for a User

The CloudAccess single sign-on login is designed to authenticate a user against an identity source and to share this authentication with other protected applications. The authentication process does not provide extended functions to add, remove, or manage a user’s identity information for the session. To address this need, CloudAccess provides the Authentication Filter tool.

The Authentication Filter integrates with the CloudAccess single sign-on process. After the user logs in, the filter intercepts the authentication process and sends the user’s identity information from the identity source to your custom authentication scripts. You can add, remove, or set values for supported identity attributes. You can also set a cookie. You can interact with the user to gather input for those changes. After all of the encoded rules and associations are complete, CloudAccess stores the modified identity information in the session cache for the web services and applications.

The Authentication Filter tool is compatible with the ExtAPI library and the ExtUI library. It works with multiple scripting languages including PHP, Java, and Perl.

For information about creating custom authentication scripts to use with the Authentication Filter, see the Technical Reference: Authentication Filter for NetIQ CloudAccess.

After you create your custom scripts, you must enable and configure the Authentication Filter tool in CloudAccess. The enabled filter automatically runs on each node in a CloudAccess cluster.

Before you enable the Authentication Filter, ensure that your enterprise environment meets the following requirements:

A CloudAccess 2.1 appliance, installed and configured
The Authentication Filter supports only applications and devices that use session-based protocols. The filter stores the altered identity attributes and values in the session attribute cache.

The Authentication Filter does not support applications and devices that use sessionless protocols, because there is no session attribute cache to store the altered identity attributes and values. For example:
- The OAuth protocol is a sessionless protocol. Thus, the Authentication Filter does not support applications use the OAuth Service Provider connector.
- Mobile devices use a token-based protocol, which reestablishes the session for each transmission. Thus, there is no session attribute cache for mobile sessions, whether the connector’s protocol is session-based or sessionless.
On the ExtAPI server, create a script that uses the ExtAPI library commands to apply session-based authentication rules to an authenticated user’s identity information. The Authentication Filter points to the URL for this file. The ExtAPI server is a web server that supports the programming language for the script file you create.
If the session-based identity changes require user interaction:
- On the ExtUI server, create a script that uses the ExtUI library commands to collect the user’s session-based identity information, and return control to CloudAccess. The ExtAPI script should redirect the authentication session to the URL for this file. The ExtUI server is a web server that supports the programming language for the script file you create.
- On the ExtAPI server, create a redirect file configured with the ExtUI script’s URL.

To enable the Authentication Filter:

Log in with an appliance administrator account to the CloudAccess administration console at https://appliance_dns/appliance/index.html.
Drag the Authentication Filter icon from the Tools palette and drop it in the Tools panel.
In the Tools panel, click the Authentication Filter icon, then click Configure.
In the Edit External Filter window, complete the following information:

Display name: Specify a name for the filter. This name appears on the main Admin page.

Connects to: Specify the URL to the script that you want to run during the user SSO login.

For example:
```
https://extapi_server_dns:port/path/extapi/index.php
```
Use HTTPS for secure SSL transfer of information. If you use an HTTP URL, information is not secure.

Basic Auth User: (Optional) If login is required to access the URL, specify the user name to use in the basic authentication header.

Basic Auth Password: (Conditional) If you specify a user name, specify the password for it.
Click OK to save and enable the filter settings.
On the Admin page, click Apply to activate the filter configuration.
Wait while the service is activated across all nodes in the cluster. Do not attempt other configuration actions until the activation completes successfully.

In the Appliances panel, a green gear icon spins on top of each node until the activation is complete across all nodes in the cluster. In the Tools panel, a green status icon appears on the lower-left corner of the service icon. A yellow status icon appears if the URL uses HTTP instead of HTTPS because the traffic is not secure.