Novell Doc: Novell Access Manager 3.1 SP2 Access Gateway Guide

1.3 Configuring Protected Resources

A protected resource configuration specifies the directory (or directories) on the Web server that you want to protect. The protected resource configuration specifies the authorization procedures and the policies that should be used to enforce protection. The authentication procedures and the policies (Authorization, Identity Injection, and Form Fill) enable the single sign-on environment for the user. The type of protection a resource requires depends upon the resource, the Web server, and the conditions you define for the resource.

You can select from the following types of protection:

Authentication Procedures: Specifies the type of credentials the user must use to log in (such as name and password or secure name and password). You can select None for the procedure, which allows the resource to be a public resource, with no login required.

In addition to selecting the contract, you can also configure how the authentication procedure handles subsequent authentication requests from an application.

Authorization Policy: Specifies the conditions a user must meet to be allowed access to a protected resource. You define the conditions, and the Access Gateway enforces the Authorization policies. For example, you can assign roles to your users, and use these roles to grant and deny access to resources.

Identity Injection Policy: Specifies the information that must be injected into the HTTP header. If the Web application has been configured to look for certain fields in the header and the information cannot be found, the Web application determines whether the user is denied access or redirected. The Web application defines the requirements for Identity Injection. The Identity Injection policies allow you to inject the required information into the header.

Form Fill Policy: Allows you to manage forms that Web servers return in response to client requests. Form fill allows you to prepopulate fields in a form on first login and then securely save the information in the completed form to a secret store for subsequent logins. The user is prompted to reenter the information only when something changes, such as a password.

These policies allow you to design a custom access policy for each protected resource:

Resources that share the same protection requirements can be configured as a group. You set up the policies, and then add the URLs of each resource that requires these policies.
A resource that has specialized protection requirements can be set up as a single protected resource. For example, a page that uses Form Fill is usually set up as a single protected resource.

To configure a protected resource:

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

The Resource View of the Protected Resource List is used to create new protected resources or manage existing protected resources. The Policy View is used to see which policies are being used by multiple protected resources. For more information about the Policy View, see Section 1.3.7, Assigning a Policy to Multiple Protected Resources.
Select one of the following actions:

New: To create a new protected resource, click this option and specify a display name for the resource. For configuration information, see Section 1.3.1, Setting Up a Protected Resource.

Delete: To delete a protected resource, select a protected resource, then click Delete.

Enable: To enable a resource so that the Access Gateway protects it, select a protected resource, then click Enable.

Disable: To disable protection for a resource, select a protected resource, then click Disable. After a resource is disabled, its path no longer has special protection. For example, you can set up a resource that allows access to all pages (for example /*) and another resource with special protection for a subpath. If you disable the subpath, make sure the security requirements of the /* resource are sufficient for the subpath.

Also, when a protected resource is disabled, the resource no longer shows up in the Path List for a path-based multi-homing proxy.
Select the name of a protected resource to perform the following tasks:

1.3.1 Setting Up a Protected Resource

Click Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] > Protected Resources.
Either click the name of an existing resource or click New, then specify a display name for the resource.
(Optional) Specify a description for the protected resource. You can use it to briefly describe the purpose for protecting this resource.
Select the type of contract to use for the authentication procedure. The contract determines the information a user must supply for authentication. By default, the Administration Console allows you to select from the following contracts and options when specifying whether a resource requires an authentication contract:

None: If you want to allow public access to the resource and not require an authentication contract, select None.

Any Contract: If the user has authenticated, this option allows any contract defined for the Identity Server to be valid, or if the user has not authenticated, it prompts the user to authenticate, using the default contract assigned to the Identity Server configuration.

Name/Password - Basic: Specifies basic authentication over HTTP, using a standard login pop-up provided by the Web browser.

Name/Password - Form: Specifies a form-based authentication over HTTP or HTTPS, using the Access Manager login form.

Secure Name/Password - Basic: Specifies basic authentication over HTTPS, using a standard login pop-up provided by the Web browser.

Secure Name/Password - Form: Specifies a form-based authentication over HTTPS, using the Access Manager login form.

The contract also determines the session timeout for inactive connections. If you have some resources that need to time out quickly to protect sensitive data and other resources that don’t need this kind of protection, you need to configure contracts for these resources. For more information about this feature, see Section 1.3.6, Assigning a Timeout Per Protected Resource.

If no contracts are available, you have not configured a relationship between the Access Gateway and the Identity Server. See Section 1.1, Managing Reverse Proxies and Authentication.
(Conditional) To modify how the authentication procedures are handled for a specific resource and contract, click the Edit Authentication Procedures icon.

For configuration information, see Section 1.3.2, Configuring an Authentication Procedure for Non-Redirected Login.
Configure the URL Path.

The default path is /*, which indicates everything on the Web server. Modify this if you need to restrict access to a specific directory on your Web server. If you have multiple directories on your Web server that require the same authentication contract and access control, add each directory as a URL path.

New: To add a path, click New, specify the path, then click OK. For example, to allow access to all the pages in the public directory on the Web server, specify the following path:
```
/public/*
```
To allow access to all the files in a directory, but not to the subdirectories and their files, specify the following:
```
/?
```
```
/public/?
```
The /? allows access to the root directory, but not the subdirectories. The /public/? allows access to the files in the public directory, but not the subdirectories.

To allow access to files of a specific type, specify the following:
```
/public/*.pdf
```
This allows access to all the files in the public directory that have a PDF extension. Access to other file types and subdirectories is denied.

To use this protected resource to protect a single page, specify the path and the filename. For example, to protect the login.html page in the /login directory, specify the following:
```
/login/login.html
```
This is the type of URL path you want to specify when you create a Form Fill policy for a protected resource. The URL Path List normally contains only this one entry. If you have multiple pages that the Form Fill policy applies to, list each one separately in the list. For optimum speed, you want the Access Gateway to be able to quickly identify the page and not search other pages to see if the policy applies to them.

For more information on how a user’s request is matched to a protected resource, see Understanding URL Path Matching.

For more information on using a query string, see Using a Query String in the URL Path.

Modify: To modify a path, click the path link, then modify the URL Path.

Delete: To delete a path, select the path, then click Delete.
Click OK.
In the Protected Resource List, ensure that the protected resource you created is enabled.
(Optional) To add policies for protecting this resource, continue with one of the following:
To apply your changes, click the Access Gateways link, then click Update > OK.

Understanding URL Path Matching

The URL path determines which protected resource is used for a user request. Suppose you create one protected resource with the following URL paths:

/*
/test/*
/test/

You create a second protected resource with the following path:

/test/*.php

Users then send the following paths in their access requests:

/test/ 
/test/1/2/3/file.php
/file.php
/test/file.php
/test/file.php?param1=1234

The first three requests (/test/, /test/1/2/3/file.php, and /file.php) match the first protected resource, and the last two requests (/test/file.php and /test/file.php?param1=1234) match the second protected resource.

You then add the following URL path to the first protected resource:

/test/?

This URL path in the first protected resource causes all the requests to match the first protected resource, and the second protected resource is ignored. The ? wildcard, which matches all content in the current directory, takes precedence over the more specific wildcard (*.php).

URL paths are case insensitive. If your Web server has two paths (/public/current and /public/Current), a URL path of /public/current matches both.

Using a Query String in the URL Path

You can specify a query string in the URL path of a protected resource. For example:

URL path: /test/index.html?test=test

When the requested URL has a query string, the Access Gateway searches for a protected resource with a matching URL path and query string. If it can’t find a match, the request returns a resource not found error.

The Access Gateway Appliance allows you to configure the URL matching process so that it ignores the query string in the URL path. The Access Gateway Service does not have this option. If you want the query string ignored, you must remove it from the URL path of the protected resource.

On the Access Gateway Appliance, you can remove the query string from the URL path or you can create the following touch file:

/var/novell/.prWithOutQuestionMark

You need to then restart the Access Gateway Appliance to activate the touch file. When this touch file is used, the Access Gateway Appliance ignores the query string and uses just the path to find a match.

1.3.2 Configuring an Authentication Procedure for Non-Redirected Login

When a contract is created, it is assigned an authentication procedure that allows the user to be redirected to the Identity Server for authentication. Some applications, such as AJAX and WebDAV applications, do not support redirection for authentication. You can change the authentication behavior of a contract so that redirection does not occur.

When non-redirected login is enabled, the Access Gateway prompts the user to supply basic authentication credentials. The SOAP back channel between the Access Gateway and the Identity Server is used to complete the authentication on the user's behalf rather than a redirect. The SOAP back channel is also used for the session renewals.

Non-redirected login has the following restrictions:

Password Expiration Services: When you modify the authentication procedures to use non-redirected login, you cannot also use a password expiration service. Even when the Password expiration servlet and Allow user interaction options are configured, users are not redirected when their passwords are expiring and they are not prompted to change their passwords.
Locked Shared Secrets: When non-redirected login is enabled, users are not prompted for their passphrase for locked shared secrets.
Session Limits: Non-redirected login can cause the user to create more than one session with the Identity Server because the SOAP back channel uses a different process than authentication requests that are directed to the Identity Server. Therefore, do not limit your users to one session. Session limits are set by clicking Devices > Identity Servers > Edit.

If the contract you are going to use for non-redirected login is also assigned to protected resources that do not require non-redirected login, you should create a new authentication procedure for the resource requiring non-redirected login. Multiple authentication procedures can be configured to use the same contract.

To configure an authentication procedure:

Click Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] > Protected Resources > [Name of Protected Resource].
On the Authentication Procedure line, click the Edit Authentication Procedure icon.

The Authentication Procedure List displays all available contracts, the name of the authentication procedure they are assigned to, the protected resources that the authentication procedure has been assigned to, and whether the procedure has been enabled for non-redirected login.
Select one of the following actions:
- To create an new authentication procedure, click New, specify a name, then click OK. Continue with Step 4.
- To modify an existing authentication procedure, click the name of the procedure. Continue with Step 4.
- To delete an existing authentication procedure, select the procedure, then click Delete. Continue with Step 7.
  
  If the procedure is used by a resource, it cannot be deleted until it is not being used to protect resources. An authentication procedure must exist for each contract. If you delete an authentication procedure for a contract without also deleting the contract, the system automatically re-creates an authentication procedure for the contract.
To specify the method for obtaining the credentials, fill in the following fields:

Contract: Select the contract that you want to use for this protected resource. This needs to be a contract that supports basic authentication credentials such as Name/Password- Basic or Secure Name/Password-Basic.

Non-Redirected Login: Select this option to use the SOAP back channel to verify the user’s credentials rather than a redirected request to the Identity Server.

Realm: Specify a name that your users can use to identify the site that they are authenticating to. This could be your company name or the name of the application. The realm is displayed as a heading when the application requests a basic authentication.

Redirect to Identity Server When No Authentication Header Is Provided: The response should provide an authentication header. If the first request does not contain the authentication header, you can select this option to allow the first request to be redirected to the Identity Server.
Click OK.
For the Authentication Procedure, select the authentication procedure you created or modified in Step 4.
Click OK.
Click Devices > Access Gateways, then update the Access Gateway.
(Optional) For some configuration scenarios that use this feature, see

1.3.3 Assigning an Authorization Policy to a Protected Resource

An Authorization policy specifies conditions that a user must meet in order to access a resource. The Access Gateway enforces these conditions. The policy can specify the criteria a user must meet either to allow access or to deny access.

Click Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] > Protected Resources > [Name of Protected Resource] > Authorization.

The Authorization Policy List contains all the Access Gateway Authorization policies that have been created on this Administration Console for the selected policy container.
Select one of the following:
- To enable an existing policy, select the policy, then click Enable. Continue with Step 4.
- To disable an existing policy, select the policy, then click Disable. Continue with Step 4.
- To edit an existing policy, click the name of the policy. Remember that policies can be assigned to multiple protected resources. If you modify the policy, you are also affecting how this policy protects those resources. For configuration information, see Creating Access Gateway Authorization Policies in the Novell Access Manager 3.1 SP2 Policy Guide.
  
  When you have completed your policy modifications, continue with Step 4.
- To create a new policy, click Manage Policies. On the Policies page, click New, specify a display name, select Access Gateway: Authorization as the type, then click OK. For configuration information, see Creating Access Gateway Authorization Policies in the Novell Access Manager 3.1 SP2 Policy Guide.
  
  When you have created your policy, continue with Step 3.
To enable the policy you just created, select the policy, then click Enable.

Only the policies that are enabled are applied to this resource. All available Authorization policies are listed. If you use the same policy for multiple protected resources, use the policy description field to indicate this.
To save your changes to the browser cache, click OK.
To apply the changes, click the Access Gateways link, then click Update > OK.

1.3.4 Assigning an Identity Injection Policy to a Protected Resource

The Web application defines the requirements for Identity Injection. If a Web application has been configured to look for certain fields in the header and the information cannot be found, the Web application determines whether the user is denied access, granted access, or redirected. You configure an Identity Injection policy to inject into the HTTP header the information that the Web application requires.

Click Access Gateways > Edit > [Reverse Proxy Name] > [Name of Proxy Service] > Protected Resources > [Name of Protected Resource] > Identity Injection.

The Identity Injection Policy List contains all the Identity Injection policies that have been created on this Administration Console for the selected policy container.
Select one of the following:
- To enable an existing policy, select the policy, then click Enable. Only the policies that are enabled are applied to this resource. Continue with Step 4.
- To disable an existing policy, select the policy, then click Disable. Continue with Step 4.
- To edit an existing policy, click the name of the policy. Remember that policies can be assigned to multiple protected resources. If you modify the policy, you are also affecting how this policy protects those resources. For configuration information, see Creating Identity Injection Policies in the Novell Access Manager 3.1 SP2 Policy Guide.
  
  When you have finished your policy modifications, continue with Step 4.
- To create a new policy, click Manage Policies. On the Policies page, click New, specify a display name, select Access Gateway: Identity Injection as the type, then click OK. For configuration information, see Creating Identity Injection Policies in the Novell Access Manager 3.1 SP2 Policy Guide.
  
  When you have created your policy, continue with Step 3.
To enable the policy you just created, select the policy, then click Enable.

Only the policies that are enabled are applied to this resource. If you use the same policy for multiple protected resources, use the policy description field to indicate this.
To save your changes to the browser cache, click OK.
To apply your changes, click the Access Gateways link, then click Update > OK.

IMPORTANT:If you enable an Identity Injection policy for a protected resource that has been assigned to use a contract that does not prompt the user for a password and the Identity Injection policy injects the user’s password, single sign-on cannot be enabled because the password is not available. However, you can create a contract that retrieves the user’s password when the user is not prompted for a password when authenticating. See Configuring Password Retrieval in the Novell Access Manager 3.1 SP2 Identity Server Guide.

1.3.5 Assigning a Form Fill Policy to a Protected Resource

Some client requests cause the Web server to return a form. Sometimes this form contains a request to log in. If you create a Form Fill policy, you can have the Access Gateway fill in the form. When a user first logs in, the Access Gateway prepopulates some fields and prompts the users for the others. The Access Gateway securely saves the information, so that on subsequent logins, the Access Gateway can fill in the form. The user is only prompted to fill in the form when something changes, such as a password expiring.

Form Fill uses two components: the HTML form and the Form Fill policy. The HTML form is created with HTML tags and consists of form elements such as fields, menus, check boxes, and buttons. The Form Fill policy is created by specifying the following:

Which information is entered automatically and not displayed to the user.
Which information is displayed so that the user, at least the first time, can enter the information.
What is done with the information (for example, whether it is saved so that the user doesn't need to enter it when accessing the form again).

You must create the policy before you can assign it to a resource (see Creating Form Fill Policies in the Novell Access Manager 3.1 SP2 Policy Guide). To assign a Form Fill policy to a protected resource:

In the Administration Console, click Devices > Access Gateways > Edit > [Reverse Proxy Name] > [Name of Proxy Service] > Protected Resources > [Name of Protected Resource].
Examine the entries in the URL Path List.

Ideally, the URL to which you are assigning a Form Fill policy should be a single HTML page or a few HTML pages. If possible, it should not be a URL that ends in a wildcard (for example, an asterisk) and therefore matches many pages.

IMPORTANT:When the URL ends in a wildcard, the Access Gateway must search each page that matches the URL and check to see if it contains the form. This adds extra processing overhead for all the pages that match the URL, but do not contain the form. For more information on the performance problems this can cause, see Creating a Form Matching Rule in the Novell Access Manager 3.1 SP2 Policy Guide.
(Conditional) If the URL is not specific, click the name of the path and modify it.
Click Form Fill.

The Form Fill Policy List contains all the Form Fill policies that have been created on this Administration Console for the selected policy container.
Select one of the following:
- To enable an existing policy, select the policy, then click Enable. Only the policies that are enabled are applied to this resource. Continue with Step 7.
- To disable an existing policy, select the policy, then click Disable. Continue with Step 7.
- To edit an existing policy, click the name of the policy. Remember that policies can be assigned to multiple protected resources. If you modify the policy, you are also affecting how this policy protects those resources. For configuration information, see Creating Form Fill Policies in the Novell Access Manager 3.1 SP2 Policy Guide.
  
  When you have finished the policy modifications, continue with Step 7.
- To create a new policy, click Manage Policies. On the Policies page, click New, specify a display name, select Access Gateway: Form Fill as the type, then click OK. For configuration information, see Creating Form Fill Policies in the Novell Access Manager 3.1 SP2 Policy Guide.
  
  When you have created your new policy, continue with Step 6.
To enable the policy you just created, select the policy, then click Enable.

Only the policies that are enabled are applied to this resource. If you use the same policy for multiple protected resources, use the policy description field to indicate this.
To save your changes to the browser cache, click OK.
To apply your changes, click the Access Gateways link, then click Update > OK.

IMPORTANT:If you enable a Form Fill policy for a protected resource that has been assigned to use a contract that does not prompt the user for a password and the Form Fill policy contains a field for the user’s password, single sign-on cannot be enabled because the password is not available. To enable single sign-on, you need to use an Authentication class that retrieves the user’s password and injects it into the user’s credentials when the user authenticates using a non-password method such as X.509, RADIUS, smart card, or Kerberos. For information about such a class, see Configuring Password Retrieval in the Novell Access Manager 3.1 SP2 Identity Server Guide.

1.3.6 Assigning a Timeout Per Protected Resource

If all your resources are using the same contract and you want them all to have the same timeout for inactivity, you set the Authentication Timeout option on the contract to the required limit and leave the Activity Realm option blank. The user logs in, and activity by the user on any resource keeps the user’s session active. The user is prompted to reauthenticate only when the user has no activity on any resources for longer than the authentication timeout value.

If you have some resources that require a shorter timeout than other resources, you need to balance the need for single sign-on with the timeout requirements:

To strictly enforce a timeout, the resource needs to be assigned to a custom contract.
To preserve single sign-on, resources need to be assigned to the same contract.

The protected resource is assigned to use a contract, and the timeout is assigned to the contract. For information on how to configure the contract, see Configuring Authentication Contracts in the Novell Access Manager 3.1 SP2 Identity Server Guide.

The following sections describe four configuration scenarios and the user experience that they create.

Scenario 1: If strictly adhering to the timeout value is more important than preserving the session or single sign-on, configure your resources as follows:

Protected resource 1 (PR1) is configured to use contract 1 (C1), which has been created from method 1 (M1) and placed in its own activity realm (AR1). For this scenario you set the authentication timeout to 30 minutes.
Protected resource 2 (PR2) is configured to use contract 2 (C2), which has been created from method 2 (M2) and placed in its own activity realm (AR2). For this scenario, you set the authentication timeout to 15 minutes.

With this scenario, the user is prompted to log in when accessing PR1 and when accessing PR2. Each resource has its own time line, because each resource belongs to its own activity realm. Figure 1-3illustrates this scenario.

Figure 1-3 Login Requirements with Separate Methods and Separate Activity Realms

After authenticating to both resources and remaining active on both resources for the first 10 minutes, the sessions remain active. The user then stays active on PR1 without accessing PR2 for over 15 minutes. The AR1 time line is updated with this activity. The AR2 time line is not updated. When the user accesses PR2 after more than 15 minutes of inactivity on the AR2 time line, the user is prompted to authenticate. The user then returns to PR1 after over 20 minutes of inactivity, but AR1 time line shows activity within the 30-minute timeout. The user is granted access and does not need to log in again to access PR1.

In this scenario, the resources are independent of each other and do not influence each other’s timeout limits.

Scenario 2: If you are willing to allow a resource to influence the timeout of another resource, configure your resources as follows:

Protected resource 1 (PR1) is configured to use contract 1 (C1), which has been created from method 1 (M1) and placed in a shared activity realm (shared1). For this scenario you set the authentication timeout to 30 minutes.
Protected resource 2 (PR2) is configured to use contract 2 (C2), which has been created from method 2 (M2) and placed in a shared activity realm (shared1). For this scenario, you set the authentication timeout to 15 minutes.

With this scenario, the user is prompted to log in when accessing PR1 and when accessing PR2. Activity at either resource updates the shared1 time line. Figure 1-4 illustrates this scenario.

Figure 1-4 Login Requirements for Separate Methods with a Shared Activity Realm

As long as the user is active on PR1, the user’s session to PR2 remains active. After 20 minutes of activity on PR1, the user returns to PR2. The user is allowed access and does not need to log in because the shared1 time line shows activity within the last 5 minutes. The user remains active on PR2 for over 30 minutes, then accesses PR1. Again, the shared1 time line shows activity within the last 5 minutes, so the user is granted access to PR1 without logging in again.

With this configuration, activity at other resources influences the time limits so that they are not strictly enforced.

Scenario 3: If single sign-on is more important than strictly enforcing a timeout value, Novell recommends that you configure all contracts to have the same authentication timeout value.

If you configure your resources as follows, you might not get the behavior you require:

Protected resource 1 (PR1) is configured to use contract 1 (C1), which has been created from method 1 (M1) and placed in a shared activity realm (shared1). For this scenario you set the authentication timeout to 30 minutes.
Protected resource 2 (PR2) is configured to use contract 2 (C2), which has been created from method 1 (M1) and placed in a shared activity realm (shared1). For this scenario, you set the authentication timeout to 15 minutes.

Because C1 and C2 are created from the same method (M1), the user does not need to log in twice to access both resources. Logging in to one resource allows them access to the other resource. Figure 1-5 illustrates this scenario.

Figure 1-5 Login Requirements for Shared Methods and Shared Realms

The user first logs in to PR2 and is active for 10 minutes. The shared1 time line gets updated with this activity. When the user requests access to PR1, the user is granted access without being prompted for credentials. The user is then active on PR1 for over 20 minutes. When the user requests access to PR2, even though the user has been inactive on this resource for over 20 minutes, the user is granted access because the time line shows activity within the last five minutes.

With this configuration, PR2 does not time out as long as the user remains active on PR1. However, when the user goes inactive on both PR2 and PR1 for over 15 minutes and the user requests access to PR1, the time line shows no activity within the time limit specified for PR2 and the user is prompted to log in.

Scenario 4: Novell does not recommend that you set different authentication timeouts on contracts and then use the Any contract option for protected resources. If you want to use the Any contract, then you should set the authentication timeout to the same value on all contracts. If the timeouts are not the same, you cannot consistently predict what timeouts are being applied to the various protected resources. For example, the user requests access to a resource that is protected with a contract with a short timeout. The user logs in, then accesses resources that use the Any contract option. All of these resources are assigned a short timeout.The user then goes inactive and the session times out. The user then requests access to a resource with a contract with a long timeout. The user logs in, and after a few minutes, accesses same resources protected with the Any contract option. These resources are now assigned the long timeout value.

1.3.7 Assigning a Policy to Multiple Protected Resources

If you have created multiple protected resources that need to be protected by the same policy or policies, you can use the policy view to assign a policy to multiple protected resources. However, the protected resources must belong to the same proxy service.

In the Administration Console, click Devices > Access Gateways > Edit > [Reverse Proxy Name] > [Name of Proxy Service] > Protected Resources.
Select the Policy View.
Select the Used By link of the policy you want to assign to multiple resources.

The Policy and Policy Container fields identify the policy. The Protected Resource Policy Usage List displays the protected resources defined for this proxy service and indicates which resources the policy has been enabled on.
To enable the policy for multiple resources, either select them one by one or click Name to select all of them, then click Enable. To disable a policy for a resource, select the resource, then click Disable.
To save your changes to browser cache, click OK.
To apply your changes, click the Access Gateways link, then click Update > OK.