Programming Guides › Programming Guide for C › Authorization API

Authorization API

This section contains the following topics:

Authorization API Overview

Active Expressions

Authorization Function Declarations

Active Expression Examples

Authorization API Overview

Using the Authorization API, you can implement custom access control functionality. To implement custom access control functionality, you must:

1. Develop a shared library that supports the Authorization API and provides the custom functionality you need.

   The shared library must contain one or more functions defined as exportable symbols. SmApi.h defines all of the data structures necessary to create custom policy, rule, and response plug-ins.

2. Install the shared library in one of the following default locations:
   • On UNIX platforms, in the SiteMinder lib directory
   • On Windows platforms, in the SiteMinder bin directory
3. Define one or more of the following in the Administrative UI:
   • Active policy—A policy that provides dynamic authorization based on external business logic.

     For example, you might define an active policy that returns true if the user belongs to a particular organizational unit (ou) in an LDAP directory as defined in the parameter (param) field of the active policy expression.

   • Active response—A custom response returned from a shared library. 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 specified in the param field of the active response expression.

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

     For example, you might define an active rule that returns true if a user is a member of a group, such as Directory Administrator, that has permission to view a realm.

Include File

When extending the authorization API, include the SmApi.h header file:

#include "SmApi.h"

Active Expressions

An active expression is a string of variable definitions that comprises an active policy, rule, or response. Active expressions are constructed in the Administrative UI using the following syntax:

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

In the syntax example:

• lib-spec is the path to a custom shared library. This clause is required.

  If you place the library in the default location, you need only specify the library file name rather than a path. Default locations are defined in Authorization API Overview.

  Also, the extension .dll or .so is optional.

• func-spec is the name of a user-defined, externally-visible function defined in the shared library. This clause is required.
• func-params is a parameter string to be passed to the function. This clause is optional.

SiteMinder constructs the active expression from information provided in the Active Rule Editor, Active Policy Editor, or Active Response Attribute Editor dialog box.

How SiteMinder Interprets Active Expressions

When SiteMinder detects an active expression, it performs the following tasks:

• Loads the shared library specified in the active expression.
• Calls the user-defined function specified in the active expression.
• Passes to the user-defined function the optional parameter string plus contextual information—that is, API context (Sm_Api_Context_t), request context (Sm_Api_RequestContext_t), and user context (Sm_Api_UserContext_t).

The following diagram illustrates the procedure:

The specified user-defined function in the shared library returns a result to SiteMinder in the lpszOutBuf parameter. SiteMinder interprets this result according to the type of active expression, as follows:

• Active Policy—If the function call fails or the result returned in lpszOutBuf is empty, authorization is denied.

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

  Any other result value causes the policy to fire.

• Active Rule—If the function call fails or the result returned in lpszOutBuf is empty, 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 representing the response attribute value. How SiteMinder uses this value is determined by the response attribute specified in the Administrative UI. For example:
  • WebAgent-OnReject-Redirect. Given this attribute, SiteMinder expects the response value to specify a location, such as a URL, to redirect a user who is denied access to a resource.

    For example, you could specify a group name in the optional param variable of the active expression, then test for the group name in the function to determine the URL to pass back.

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

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

Define Active Rules

Active rules are defined in the Administrative UI using the SiteMinder Active Rule Editor dialog box. To access this editor from the Rule Properties dialog box, select the Active Rule tab in the Advanced group box, then click Edit.

Define Active Responses

Active responses are defined in the Administrative UI using the SiteMinder Response Attribute Editor dialog box.

From the Response Properties dialog box, access the editor by clicking Create and select the Active Response button in the Attribute Kind group box on the Attribute Setup tab.

Define Active Policies

Active policies are defined in the Administrative UI using the SiteMinder Active Policy Editor dialog box.

From the Policies Properties dialog box, access this editor by selecting the Advanced tab and clicking Edit.