Programming Guides › Programming Guide for Java › Java Authentication and Authorization Guidance › Use the Authorization API

Use the Authorization API

The Java Authorization API lets you implement custom functionality for controlling access to protected resources.

The functionality is provided through custom Java classes that are referenced in Policy Server active expressions. An active expression is a string of variable definitions that appears in the following Policy Server objects:

• Active policy—A policy that provides dynamic authorization based on external business logic.

  For example, you might implement a custom Java class that returns true if the user belongs to a particular organizational unit (ou) in an LDAP directory. The ou is passed to the custom Java class in the parameter (param) field of the active expression.

• Active response—A response returned from a custom Java class. Using an active response is one way you can define user-specific privilege information.

  For example, you might define an active response that returns a user’s common name (cn) if the user belongs to the ou passed in the param field of the active expression.

• Active rule—A rule that provides dynamic authorization based on external business logic.

  For example, you might define a custom Java class that returns true if a user is a member of a group, such as Directory Administrator, that has permission to view a realm. The group name is passed to the Java class in the param field of the active expression.

Active Expressions

Active expressions are constructed in the Policy Server User Interface using the following syntax:

<@ lib=<lib-spec> func=<func-spec> param=<func-params>@>

An active expression based on the Java Authorization API has the following required fields:

• lib contains the shared library name smjavaapi. This library is used with all active expressions that reference a custom Java class in param.
• func contains the function name JavaActiveExpression. This function is the entry point for the smjavaapi library. It is used with all active expressions that reference a custom Java class in param.
• param contains the following information.
  • The name of your custom Java class
  • Optionally, any parameters to pass to an instance of your class

You define an active expression when you configure the active policy, rule, or response in the Policy Server User Interface.

Execute an Active Expression

When SiteMinder detects an active expression that references a custom Java class, it performs the following tasks:

• Loads the shared library and instance of the custom Java class specified in the active expression.
• Calls the library function specified in the active expression.
• Passes to the instance of the custom Java class the optional parameter string plus the following context objects:
  • APIContext
  • RequestContext
  • UserContext
• The instance of the Java class performs the custom functionality and returns a result to SiteMinder. Results are returned from the custom Java class’s invoke() method.

Interpret an Active Expression Result

SiteMinder interprets the result returned by the instance of the custom Java class according to the type of active expression that references the Java class, as follows:

• Active Policy—If the result returned is an empty string or if an exception is thrown, authorization is denied.

  The policy does not fire if the result returned matches any of the following strings (not case-sensitive): FALSE, F, or 0.

  Any other result causes the policy to fire.

• Active Rule—If the result returned is an empty string or if an exception is thrown, the following behavior occurs:
  • With Allow Access rules, the rule does not fire.
  • With Deny Access rules, the rule fires.

  Otherwise, the behavior is the same as for Active Policies.

• Active Response—The result is a string that corresponds to a response attribute. How SiteMinder interprets the result string is determined by the response attribute specified in the Policy Server User Interface. For example:
  • WebAgent-OnReject-Redirect. Given this response attribute, SiteMinder expects the result string to specify a location, such as a URL, to redirect a user who is denied access to a resource.

    (The URL that is passed back might vary according to information passed into the custom Java class. For example, a group name could be passed in the param field of the active expression. The custom Java class could then test for the group name to determine the URL to pass back.)

  • WebAgent-HTTP-Cookie-Variable. Given this response attribute, SiteMinder expects that the result string, such as the user’s common name, is to be assigned to a cookie variable. You can use the result string any way you like, such as to display the user’s common name to personalize a form.

    You specify the cookie name in the SiteMinder Response Attribute Editor.

  If the method fails (that is, the method returns -1 or 0), the response attribute is ignored.

ActiveExpression Methods

The base interface in the Java Authorization API is ActiveExpression. All Java classes that provide custom authorization functionality must implement this interface.

The name of the class that you implement from the base interface must appear in the param field of any associated active expression.

SiteMinder calls the following methods in the base interface ActiveExpression:

Note: Classes that implement ActiveExpression should be implemented on a stateless model that does not depend on instance state stored in member variables of the ActiveExpression class.

Other Classes in the Authorization API

The following classes in the Authorization API are used in conjunction with the ActiveExpression base interface: