Rules

Rules identify specific resources and either allow or deny access to the resources. Rules can also be used to trigger responses when authentication or authorization events take place. When you create rules, associate rules with specific realms.
sm1252sp1
Rules identify specific resources and either allow or deny access to the resources. Rules can also be used to trigger responses when authentication or authorization events take place. When you create rules, associate rules with specific realms.
The following diagram illustrates some realms and nested realms and their associated rules.
Rules overview
Rules overview
In the diagram, different realms, including nested realms have specific rules for the resources in the realm. You can also configure a single rule for all of or a subset of the resources in a realm. Specify resources in a single rule using resource matching or regular expressions.
This topic discusses the following information:
 
 
3
 
 
How Rules Work as Part of a Policy
Policies protect resources by binding together rules, users, and responses. Rules determine precisely which resources are protected, and which types of actions cause a rule to fire.
For example, a rule can specify that all HTML files in a realm are protected for a GET action. Based on this action, the web server responds to a request for an HTML page. When a user tries accessing a resource, the rule fires. The policy containing the rule determines whether the user can view the selected resource.
How the Policy Server Processes Rules
The Policy Server evaluates rules according to the relationships between users, rules, and responses that are defined in policies. When a user accesses a protected resource, the Policy Server processes policy rules to determine the following conditions:
  • Whether the user is authorized for the resource
  • Whether it must process any authentication and authorization events
  • Whether any responses must be generated and returned to the Web Agent.
When the Policy Server processes an authorization event, it looks for the realm with the longest resource filter that matches the protected resource. The Policy Server fires only those rules that are associated with that realm. In this example, the user is a manager, who wants to access the following protected resource:
 
/company/employees/managers/performance/
 
The following realms have resource filters that match the protected resource:
 
Realm Name
 
 
Realm Description
 
 
Resource Filter
 
Company
Customers, employees, vendors
/company/
Company Employees
All employees
/company/employees/
Company Managers
All managers
/company/employees/managers/
Performance Management
Managers with team members
/company/employees/managers/performance/
The realm with the longest matching resource filter is Performance Management. In response to the authorization event, the Policy Server fires all rules that are associated with the Performance Management realm.
The Policy Server collects responses from all matching rules that fire. When the Policy Server finishes collecting responses that are based on rules, it deletes any duplicate responses.
For details about policy processing for authentication and authorization events, review the information in Policy Processing for Policies with Nested Realms.
Rules Within Nested Realms
Nested realms are created within an existing realm. A nested realm has a parent, or top-level realm, and is considered a child of the parent realm. When you create nested realms, you can also create separate rules to protect the resources in the child realms. You can also copy an existing rule, attach the rule to another realm, and rename the rule.
In a deployment of nested realms, the Policy Server keeps a ranked list of matching realms for use during processing. If any matching rules deny access to a resource, processing stops. The Policy Server then returns any responses that are associated with the deny access rule to the Web Agent. The Policy Server also collects the entire list of accumulated responses for all matching rules. For OnAuthAccept rules, the Policy Server returns the entire list of responses to the Agent. For OnAuthReject rules, the Policy Server returns only the responses for the rule in the deepest nested realm. OnAuthReject rules fire only for users who are bound to the policy.
Rule Actions
A rule action determines what event must occur for the rule to fire. A rule fires when the Policy Server determines that an action specified in a rule occurs. The rule must be contained in an existing, enabled policy. For example, a policy can contain a rule that allows access to an HTML page. If a user in the directy associated with the policy tries to access a resource, the rule fires to process the request.
When a rule fires, the Policy Server processes the rule action. For example, if a user is 
excluded
 from a group, a rule with a GET action does not allow the user to access the resource.
You can create rule actions that differ based on whether a user is authenticated and whether a user is authorized. For more information about setting up different rules, read Policy Processing for Policies with Nested Realms.
Web Agent Actions
Rules with a web agent action either allow or deny access to the resources. Allowing access is the default action. When a rule allows access, the Web Agent allows an authenticated user to access the specified resource. If a rule denies access, the Agent denies access even though the user authenticated successfully. You can add deny access rules to policies to provide an extra layer of security. 
 Deny access rules take precedence over allow access rules. If a deny access rule and an allow access rule fire when a user attempts to access a resource, the deny access rule overrides the allow access rules.
The Web Agent rule actions are:
  • HEAD
  • GET
  • POST
  • PUT
  • DELETE
  • TRACE
  • OPTIONS
WSS Agent Actions
Two more Web Agent rule actions are available for WSS Agent use:
  •  
    ProcessSOAP
    This action supports incoming XML messages wrapped with a SOAP envelope.
  •  
    ProcessXML
    This action supports incoming raw XML messages that are not wrapped with a SOAP envelope.
Authentication Events
Authentication events occur when a user accesses a resource that is protected by a rule with an OnAuth event. The Policy Server fires the rule during the authentication process. Unlike Web Agent actions or authorization events, authentication events always apply to the entire realm. You cannot create an OnAuth rule that applies to a portion of a realm.
The following list contains possible authentication events:
  •  
    OnAuthAccept
    This event occurs for a successful authentication. This event can be used to redirect a user after a successful authentication.
  •  
    OnAuthAcceptCredentials
    This event occurs only during the login stage. The user credentials are presented and generate the creation of a new session.
  •  
    OnAuthReject
    This event occurs if a user fails to authenticate against a policy containing an OnAuthReject rule. This event can be used to redirect the user.
    OnAuthAccept and OnAuthReject events fire at authentication time and at validation time. However, there are certain special actions that only occur at authentication time:
    •  
      Realm timeout override (unless EnforceRealmTimeouts is used)
      The user Idle and Max Timeouts remain at the values for the realm where the user last authenticated. The values only change if the user has to reenter their credentials. The only exception is if the Web Agent supports the EnforceRealmTimeouts option and that option is enabled.
    •  
      Redirects
      Redirects are only allowed at authentication time to prevent the possibility of infinite redirect loops.
    •  
      Access to the user password
      The password is not stored in the SMSESSION cookie. The password is available only when the user enters it during an authentication challenge.
    OnAuth event results are per realm. For example, if a user goes from realm A to realm B and the user has an OnAuthAccept header in realm A, the header is not available in realm B. When the user returns to realm A, the header is set again.
  •  
    OnAuthAttempt
    Indicates an incorrect username as the Policy Server does not recognize the user in the User Store.
  •  
    OnAuthChallenge
    This event occurs when custom challenge-response authentication schemes are activated (for example, a token code).
  •  
    OnAuthUserNotFound
    This event is only used to trigger Active Responses. Do not use this event to trigger any response other than an Active Response.
A rule with an authentication event action might be coupled with a response in a policy. Whether a user is authenticated or rejected, the Policy Server passes any response that is associated with the OnAuth rule back to the requesting Agent.
Optimize performance by limiting the number of times the Web Agent must retrieve static information from the Policy Server. Set up a rule that is based on the OnAuthAccept authentication event and create a response that returns the static information. When you bind the rule and response in a policy, the rule fires for users who are specified in the policy. The static response is only returned for users who successfully authenticate.
Authorization Events
Authorization events occur as the Policy Server verifies whether a user is authorized to access a resource. An authorization event causes the Policy Server to fire a rule at a particular point in the authorization process.
The following list contains possible authorization events:
  •  
    OnAccessAccept
    This event occurs as the result of successful authorization. You can use this event to redirect users who are authorized to access a resource.
  •  
    OnAccessReject
    This event occurs as the result of failed authorization. You can use this event to redirect users who are not authorized to access a resource.
You can couple a rule with an authorization event actionwith a response in a policy. Whether a user is authorized or rejected, the Policy Server passes any responses associated with the applicable OnAccess rule back to the requesting Agent.
If an OnAccessReject rule is in the same policy as a GET/POST rule, the OnAccessReject rule does not fire. When the Policy Server resolves the identity of the user, the user is successfully authenticated. Therefore, if the OnAccessReject rule and the GET/POST rule are in the same policy, the user who is allowed access to the resource is the same user who must be redirected based on the OnAccessReject rule. However, the user is allowed access so the reject event never applies. To resolve this discrepancy, create a separate policy for the OnAccessReject rule. The separate policy can include other event rules, and specify the users for which it applies.
For example, in an LDAP user directory, User1 has access to a resource and all others in the group, ou=People, o=forwardinc.com is redirected to an OnAccessReject page. Two policies are required:
  • Policy1 includes a GET / POST rule that allows access for User1.
  • Policy2 includes the OnAccessReject rule and a Redirect response, and specifies the group ou=People, o=forwardinc.com
Since User1 is authorized, the OnAccessReject rule does not fire when User1 accesses the resource. However, the OnAccessReject rule does fire for all other users in the group, ou=People, o=company.com, because they are not authorized to access the resource.
Impersonation Events
Impersonation lets a privileged user assume the role of another user without ending the privileged user session. Impersonation events are used to start impersonation sessions when resources are accessed.
Possible impersonation events:
  •  
    ImpersonationStart
    When included in an appropriate policy, a rule that includes this event allows an impersonation session to begin.
  •  
    ImpersonationStartUser
    When included in an appropriate policy, a rule that includes this event allows a set of users to be impersonated.
Advanced Rule Options
Advanced options allow you to define more rule settings:
  •  
    Time restrictions
    Specify when a rule does or does not fire.
  •  
    Active rules
    Allow dynamic authorization that is based on external business logic.