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:

Modify a SAML Assertion or Response

According to SAML specifications, an assertion (SAML 1.x) or response (SAML 2.0) is generated by a producer site and sent to a consumer site for validation. Typically, you will use the default SAML assertion or response that SiteMinder generates at the producer site. If you want to modify the content of the assertion or the reponse, you can do so by implementing the Java assertion generator plug-in. This plug-in is appropriate for both consumers (SAML 1.x) and Service Providers (SAML 2.0).

To modify the SAML assertion or response

1. Implement a Java SAML assertion generator plug-in.

   The implementation is a plug-in for the SiteMinder Assertion Generator Framework. The Assertion Generator Framework sends a default token to the custom plug-in object. After processing, the custom object passes a modified token to the Assertion Generator Framework.

2. Configure the plug-in by specifying the fully-qualified name of the plug-in class and any optional parameters that the plug-in might require.

   You configure a custom assertion generator plug-in in any of these ways:

   • For SAML 1.x support, on the Advanced tab of the SiteMinder Affiliate Properties dialog.
   • For SAML 2.0 support, on the Advanced tab of the SiteMinder Service Provider Properties dialog.
   • Through the C or Perl Policy Management API.

   Note: Configuration of the assertion generator plug-in requires a Policy Management API session version of at least v6.0 SP 2.

Interaction between SiteMinder and an Assertion Generator

The following steps outline the interaction between SiteMinder and a custom assertion generator plug-in. The activities begin when an authorized user makes a request, through a SiteMinder Policy Server, for a resource at a site that consumes assertions:

1. An authorized user requires a SAML assertion or response for a consumer or Service Provider.
2. The SiteMinder Assertion Generator Framework generates a default SAML assertion or response.
3. If an assertion generator plug-in is defined for the site that consumes the assertion, the SiteMinder Assertion Generator Framework requests an instance of the plug-in object from the plug-in cache.

   Note: The site consuming assertions can have no more than one assertion generator plug-in defined for it.

4. If the plug-in has not yet been loaded into cache:
   1. SiteMinder instantiates the plug-in class and loads it into cache.
   2. SiteMinder calls the plug-in’s init() method. This method performs any initialization procedures that you have implemented for the plug-in.

   A successfully initialized plug-in object remains in cache until SiteMinder shuts down. This avoids having to re-load and re-initialize the object every time the plug-in is required.

5. The SiteMinder Assertion Generator Framework passes the default XML token, generated in step 2, to the plug-in’s customizeAssertion() method.
6. The plug-in validates or modifies the information as required, and returns the processed assertion to the Assertion Generator Framework.
7. The Assertion Generator Framework passes the processed token to the consumer or Service Provider. This site uses the information in the assertion to determine how to respond to the user’s request.
8. Steps through are repeated whenever a user requires an assertion for the service provider.

When SiteMinder is about to shut down, SiteMinder calls the plug-in’s release() method to allow the plug-in to perform any rundown activities it might require.

Development and Deployment Notes

When developing and deploying a custom assertion generator plug-in, keep the following points in mind:

• The implemented plug-in class must provide a public default constructor method with no parameters.
• The implementation must be stateless—that is, the single plug-in instance can be concurrently used for multiple threads.
• The syntax requirements and use of the parameter string that is passed into the customizeAssertion() method is the responsibility of the custom object.
• The custom object must parse the default assertion that is passed to customizeAssertion()—for example, through a Document Object Module (DOM) parser or a Simple API for XML (SAX) parser. The sample plug-in class AssertionSample.java uses a DOM parser.
• To enable SiteMinder to locate your deployed plug-in class, specify the deployment location in -Djava.class.path of the configuration file JVMOptions.txt. This file is in the following location of the SiteMinder installed directory structure: <install-path>\siteminder\config.
• For a sample of an assertion plug-in class, see AssertionSample.java, which demonstrates the plug-in process for a SAML 1.x assertion, in the following location of the SiteMinder installed directory structure: <install-path>\sdk\samples\assertiongeneratorplugin. In the same directory there are samples for the Assertion Generator Plugin for SAML 2.0, SAML2AppAttrPlugin.java, and WS-Federation, WSFedAppAttrPlugin.java.