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.

Pass HTTP Headers and Cookies to Policy Server

You can add arbitrary custom key/value pairs to the current session to pass HTTP headers and cookies to the Policy Server. These key/value pairs are kept in the session store; they have the same lifetime as the session. The name/value pairs are stored in the Expiry Data Table in the session store database. There can be maximum 5 entries for a session. The Active Plugin code can use the UserContext structure (Sm_Api_UserContext_t* lpUserContext) to set and retrieve these name/value pairs by calling fSetProp and fGetProp respectively. To set the value, fSetProp is called with lpszPropName as SM_SESSIONVAR(<name>) and lpszValueBuf as the value. To retrieve the value, fGetProp is called with lpszPropName as SM_SESSIONVAR(<name>)/ SM_SESSIONVAR and the value/values is returned in lpszValueBuf.

Note the following:

• To set the name/value pair in Expiry Data Table, the name should be passed in SM_SESSIONVAR(<name>) format only. The name can be maximum 32 characters long, can start with only a letter or underscore and can contain only letters, digits or underscore. The length of the value which can be set is 4000 characters maximum.
• To fetch the value for a name, the name should be passed in SM_SESSIONVAR(<name>) format. The value in Expiry Data Table corresponding to <name> is returned. If only SM_SESSIONVAR is passed (no name is passed within), then all the names for that session are returned in caret-delimited format.
• If you remove name/value pair in Expiry Data Table, the name is passed as SM_SESSIONVAR(<name>) and the value should be passed as blank.

Authorization Function Declarations

You must build the shared library with the proper entry points. Each entry point in the shared library represents one or more active expressions and must be defined according to the specified syntax.

Note: If you are using Microsoft Visual Studio, export the function addresses to a modular definition file (.DEF) file. To export the function addresses, create a .DEF file, and in the export section of the .DEF file, list the functions that you want to invoke from the Active Rule or Active Policy. After you have created the .DEF file, add it to the Microsoft Visual Studio project.

User-Defined Function

The Policy Server calls a user-defined function to perform a custom policy, rule, or response operation.

You can assign the function any name. Through the active expression that you define in the Administrative UI, you advise SiteMinder of the function name and the name of the shared library where the function resides.

Syntax

int SM_EXTERN <func-spec> (
   const Sm_Api_Context_t*          lpApiContext,
   const Sm_Api_UserContext_t*      lpUserContext,
   const Sm_Api_RequestContext_t*   lpReqContext,
   const char*                      lpszParam,
   const int                        nBytesOutBuf,
   char*                            lpszOutBuf,
   const int                        nBytesErrBuf,
   char*                            lpszErrBuf
);

Returns

• Upon successful execution, the function returns a value greater than 0—that is, the total number of bytes in the result buffer lpszOutBuf.
• If an error occurs, the function returns -1 and stores the applicable error message in the error buffer lpszErrBuf.
• When used for an Active Rule, a return value of 0 (an empty string was passed back in lpszOutbuf) results in one of the following actions:
  • With Allow Access rules, the rule does not fire.
  • With Deny Access rules, the rule fires.

SmQueryVersion()

The Policy Server calls this function to determine the Authorization API version that the custom library is compliant with.

Syntax

int SmQueryVersion (
   const Sm_Api_Context_t* lpApiContext
);

Returns

Returns the version number of the Authorization API. Currently the version supported is Sm_Api_Version_V3. This constant is defined in SmApi.h.

Active Expression Examples

This samples provided in the following sections are located in:

sdk\samples\smazapi\smazapi.cpp

The syntax that precedes each sample, such as:

<@ lib="SmAzAPI" func="activeRule" param="" @>

is an example of the Generated Script that SiteMinder constructs in the SiteMinder Active Rule Editor, Active Policy Editor, or Active Response Attribute Editor dialog box from the information you provide in the dialog box.

To build sample active expressions for UNIX, use the makefile found in
<install_path>\sdk\samples\smazapi\makefile.

Example of an Active Rule

The example below returns true if the user has special access permission to view the realm. If the user has directory manager privileges, the user can view the realm.

<@ lib="SmAzAPI" func="activeRule" param="" @>
*************************************************************
int SM_EXTERN activeRule(
const Sm_Api_Context_t* lpApiContext,  
// the structure that provides API context
const Sm_Api_UserContext_t* lpUserContext,  
// the structure that provides user context
const Sm_Api_RequestContext_t* lpReqContext,   
// the structure that provides request context
const char* lpszParam, 
// the parameter string (null-terminated)
const int nBytesOutBuf,   
// the maximum size of the output buffer
char* lpszOutBuf, 
// the output buffer to hold the null-terminated result
const int nBytesErrBuf, 
// the maximum size of the error message buffer
char* lpszErrBuf)     
// the output buffer to hold the null-terminated error message
{
/* User Context is required to use the functions like fGetProp, fSetProp.. */
if(!lpUserContext->bIsUserContext)
   {
   strncpy (lpszErrBuf, "No User Context ", nBytesErrBuf);
   lpszErrBuf[nBytesErrBuf-1] = '\0';
   return -1;
   }
/*
// The DN to look for the attribute "uniquemember"
// If the user is listed as the member of the above attribute,
// it has directory manager privileges.
*/
char lpszDn[] = "cn=Directory Administrators,ou=Groups,o=airius.com";
char lpszDnvalue[256];
memset(lpszDnvalue, 0, sizeof(lpszDnvalue));
/*
// fGetDnProp function is used to retrieve an attribute value
// in a directory entry.
*/
int getResult = lpUserContext->fGetDnProp(
   lpUserContext->lpParam,
   lpszDn,
   "uniquemember",
   sizeof(lpszDnvalue),
   lpszDnvalue);
/*
// If no error occurs, fGenDnProp will return the length of the 
// buffer lpszDnvalue. Otherwise the function returns 0.
*/
if(getResult > 0)
   {

   /* Check to see if the user is present in the list. */
   if(strpbrk(lpszDnvalue, lpUserContext->lpszUserName) != NULL)
      {

      /* The result "true" is placed in the output buffer. */
      strncpy(lpszOutBuf, "true", nBytesOutBuf);
      lpszOutBuf[nBytesOutBuf-1] = '\0';
      return strlen(lpszOutBuf);
      }

      else

      {
      strncpy(lpszOutBuf, "false", nBytesOutBuf);
      lpszOutBuf[nBytesOutBuf-1] = '\0';
      return strlen(lpszOutBuf);
      }
   }
   
   else

   {
   strncpy(lpszErrBuf, "Failed to get attribute value for the DN ",
                        nBytesErrBuf);
   strncat( (lpszErrBuf + strlen(lpszErrBuf)), lpszDn,
             (nBytesErrBuf-strlen(lpszErrBuf)));
   lpszErrBuf[nBytesErrBuf-1] = '\0';
   return -1;
   }

/* everything failed.... */

return 0;

}

Example of an Active Response

This active response returns the common name (cn) of the user, if the user belongs to the organizational unit specified in the parameter (param) field of the active response expression.

<@ lib="SmAzAPI" func="activeResponse" param="Human Resources" @>
***********************************************************
int SM_EXTERN activeResponse(
const Sm_Api_Context_t*   lpApiContext,   
/* the structure that provides API context */
const Sm_Api_UserContext_t*  lpUserContext, 
/* the structure that provides user context */
const Sm_Api_RequestContext_t*  lpReqContext,   
/* the structure that provides request context */
const char* lpszParam,      
/* the parameter string (null-terminated) */
const int  nBytesOutBuf,   
/* the maximum size of the output buffer */
char*  lpszOutBuf,     
/* the output buffer to hold the null-terminated attribute value */
const int   nBytesErrBuf,   
/* the maximum size of the error message buffer */
char*   lpszErrBuf)     
/* the output buffer to hold the null-terminated error message */
{
memset(lpszOutBuf, 0, sizeof(lpszOutBuf));
if(!lpUserContext->bIsUserContext)
      {
      strncpy (lpszErrBuf, "No User Context ", nBytesErrBuf);
      lpszErrBuf[nBytesErrBuf-1] = '\0';
      return -1;
      }
/* Store all the organizational units to which the user belongs. */
char lpszOrgUnit[30];
memset(lpszOrgUnit, 0, sizeof(lpszOrgUnit));
/* store the common name of the user. */
char lpszCN[30];
memset(lpszCN, 0, sizeof(lpszCN));
/* Check to see if a parameter is requested. */
if(lpszParam == NULL || strlen(lpszParam) == 0) 
   {
   strncpy (lpszErrBuf, "Organizational unit is not entered ",
            nBytesErrBuf);
   lpszErrBuf[nBytesErrBuf-1] = '\0';
   return -1;
   }
/* Get all the organization units to which the user belongs. */
int getResult = lpUserContext->fGetProp (
   lpUserContext->lpParam,
   "ou",              /* Attribute name */
   sizeof (lpszOrgUnit), lpszOrgUnit);
if (getResult < 0)
   {
   strncpy (lpszErrBuf, 
        "Failed to get organization unit for the user's profile ",
        nBytesErrBuf);
   strncat( (lpszErrBuf + strlen(lpszErrBuf)), 
            lpUserContext->lpszUserName, 
            (nBytesErrBuf-strlen(lpszErrBuf)));
   lpszErrBuf[nBytesErrBuf-1] = '\0';
   return -1;
   }
    else
    {
/* Check if the user belongs to the organization unit that is requested. */
   if(strstr(lpszOrgUnit, lpszParam) != NULL)
      {
      if((lpUserContext->fGetProp(lpUserContext->lpParam,
           "cn",sizeof(lpszCN),lpszCN)) > 0)
         {
         strncpy(lpszOutBuf, lpszCN, nBytesOutBuf);
         lpszOutBuf[nBytesOutBuf-1] = '\0';
         return strlen(lpszOutBuf);
         } /* end of fGetProp */
         else
         {
         strncpy (lpszErrBuf, 
          "Failed to get user common name from user's profile attribute ",
           nBytesErrBuf);
         strncat( (lpszErrBuf + strlen(lpszErrBuf)),
                    lpUserContext->lpszUserName, 
                    (nBytesErrBuf-strlen(lpszErrBuf)));
         lpszErrBuf[nBytesErrBuf-1] = '\0';
         return -1;
         }
        } /* end of strstr */
        else
        {
      strncpy (lpszErrBuf, 
       "The user does not belong to the requested organizational unit ", 
        nBytesErrBuf);
      lpszErrBuf[nBytesErrBuf-1] = '\0';
      return -1;
      }
   }
    /* everything failed.... */
    return 0;
 }
#ifndef _WIN32
}

#endif