The following APIs allow you to develop custom extensions to the Policy Server:
For example, you can create the following:
The Policy server exposes a number of hooks that can be used to perform custom authentication and authorization tasks. In addition, hooks can be used to enable delivery of custom data to applications that are protected by SiteMinder Agents. Using these hooks enables tight integration between SiteMinder and the existing infrastructure.
To use this hook, you must build a custom authentication scheme using the Authentication API. A custom authentication scheme can assume control over user disambiguation, authentication, and impersonation issues. A custom authentication scheme can accept or reject a user’s authentication attempt, and can specify a numeric reason and a text message for doing so. The numeric reason and the text message are made available to the application so that the application can take the appropriate action. This enables the application to maintain communication with the authentication scheme until the user is finally authenticated.
To use this hook, you must build a custom authorization module using the Authorization API. A custom authorization module controls whether or not SiteMinder rules and policies allow the user to access a resource.
To use this hook, you must build a custom module that obtains data from an external data source and returns this data to the Policy Server. The Policy Server then delivers the data to the application protected by SiteMinder. SiteMinder does not interpret this data in any way.
The Policy Server defines a number of events that may be triggered after each authentication and authorization. SiteMinder policies are used to catch these events and return appropriate data to applications protected by SiteMinder Agents. Events can be used to implement application workflow. There are two types of events: authentication and authorization.
The Policy Server fires an authentication event based on the outcome of the authentication. Authentication events include:
By using proper authentication events, responses can be accumulated and delivered to the application immediately after a user is authenticated.
The Policy Server fires an authorization event based on the outcome of the authorization. Authorization events include:
By using proper authorization events, responses can be accumulated and delivered to the application immediately after a user is authorized to access a resource.
When the Policy Server makes calls to custom modules, it may be convenient for these modules to communicate some request-specific information between themselves. Custom modules built with the Authentication, Authorization or Directory APIs can preserve state between module invocations. To preserve state, use the memory management hooks provided in the Sm_Api_Context_t structure (defined in SmApi.h). State has request-only scope and is limited to a single instance of a process; that is, a custom module running in the context of the authentication server cannot exchange state with a module running in the context of the authorization server.
Sometimes it may be necessary to return data that describes a user property that is not stored in the user profile. Typically, this data is some kind of dynamic information that is maintained by and known to SiteMinder. The dynamic information is provided using well-known or pseudo user attributes. These attributes can be accessed by the standard response mechanism or by a custom module if the attributes represent standard user attributes. These attributes begin with SM_ and are listed here:
SM_USERNAME
For an authenticated user, this is the user DN as disambiguated by SiteMinder. For an unauthenticated user, this is the user ID as specified by the user in the login attempt.
SM_USERIMPERSONATORNAME
If the authentication scheme performs impersonation, this is the user DN that is authenticated by SiteMinder.
SM_USERLOGINNAME
This is the user ID as specified by the user in the login attempt.
SM_USERLOGINFAILURESCOUNT
The number of attempted logins that failed, expressed as an int value. One of the password policy state attributes.
SM_USERIPADDRESS
The user’s IP address at the time of authentication or authorization.
SM_USERPATH
For an authenticated user, this is a string that represents the directory namespace and directory server (both as specified in the user directory definition), and user DN (as disambiguated by SiteMinder). For example:
“LDAP://123.123.0.1/uid=scarter,ou=people,o=airius.com”
For an unauthenticated user, this is the same as SM_USERNAME.
SM_USERPREVIOUSLOGINTIME
Time of the user’s previous login, expressed as a GMT time_t value. One of the password policy state attributes. This value is read-only (get); it cannot be set. The value represents the time since the Policy Server system epoch time, which is 00:00:00 UTC, January 1, 1970. (If a Mac OS machine is running as a client, its epoch time is 00:00:00, January 1, 1904, local time.) One of the password policy state attributes.
SM_USERPASSWORD
This is the password as specified by the user in the login attempt. The value is returned only on authentication, not on authorization.
SM_TRANSACTIONID
The transaction ID that is generated by the agent.
SM_USERDISABLEDTIME
Time that the user has been disabled, expressed as a GMT time_t value. One of the password policy state attributes. This value is read-only (get); it cannot be set. The value represents the time since the Policy Server system epoch time, which is 00:00:00 UTC, January 1, 1970. (If a Mac OS machine is running as a client, its epoch time is 00:00:00, January 1, 1904, local time.) One of the password policy state attributes.
SM_USERLASTPWCHANGETIME
Time that the user last changed the password, expressed as a GMT time_t value. The value represents the time since the Policy Server system epoch time, which is 00:00:00 UTC, January 1, 1970. (If a Mac OS machine is running as a client, its epoch time is 00:00:00, January 1, 1904, local time.) One of the password policy state attributes.
Note: If you set this value, and the associated password is reset outside of SiteMinder, the password policy preventing password reuse may not work as expected
SM_USERPASSWORDHISTORY
One of the password policy state attributes. Contains all the password change information for up to 32 entries, expressed as a string value. Includes encrypted, structured, binary information. The Password State API does not expose any detail about this structure to the external applications.
Note: You can "set" the value of this attribute only by using an empty string to clear the entire history. No other history changes are allowed. You cannot add or remove only one history entry. There is no read (get) for this attribute.
SM_USERSESSIONSPEC
The user’s session specification.
SM_USERSESSIONID
The session ID of a user who has already been authenticated. This is the session ID that will be assigned to the user upon successful authentication.
SM_USERSESSIONIP
The IP address that was used during the original user authentication (upon establishment of a session).
SM_USERSESSIONUNIVID
The user’s universal ID. If no universal ID directory attribute is specified in the user directory definition, this defaults to the user’s DN.
SM_USERSESSIONDIRNAME
The name of the user directory that the Policy Server is configured to use.
SM_USERSESSIONDIROID
The object ID of the user directory that the Policy server is configured to use.
SM_USERSESSIONTYPE
The user’s session type. One of the following:
SM_USERLASTLOGINTIME
The user’s last login time, expressed as a GMT time_t value. Available only during authentication with applicable password services policies. One of the password policy state attributes.
SM_USERGROUPS
Groups to which the user belongs. If the user belongs to a nested group, this attribute contains the group furthest down in the hierarchy. For all nested groups to which the user belongs, use SM_USERNESTEDGROUPS.
For example, if user JSmith belongs to the group Accounts Payable, which is contained in group Accounting, SM_USERGROUPS contains Accounts Payable. If you want both Accounting and Accounts Payable, use SM_USERNESTEDGROUPS.
SM_USERNESTEDGROUPS
Nested groups to which the user belongs. For only the group furthest down in the hierarchy, use SM_USERGROUPS.
For example, if user JSmith belongs to the group Accounts Payable, which is contained in group Accounting, SM_USERNESTEDGROUPS contains Accounting and Accounts Payable. If you want only Accounting, use SM_USERGROUPS.
SM_USERSCHEMAATTRIBUTES
User attributes associated with the DN, or properties associated with the user. If the user directory is a SQL database, then SM_USERSCHEMAATTRIBUTES holds the names of the columns in the table where user data is stored. For example, using the SmSampleUsers schema, SM_USERSCHEMAATTRIBUTES holds the names of the columns in the SmUser table.
SM_USERPOLICIES
These contain the names of the policies that authorize the user for a resource. For example, suppose that to purchase an item, a user must be associated with the Buyer policy. When the user is successfully authorized to buy an item, SM_USERPOLICIES will contain Buyer.
SM_USERPOLICIES will only contain a value when the action for the associated rule is set to Authorization events and the specified event is OnAccessAccept.
SM_USERPRIVS
When a user is authenticated or is authorized for a resource, SM_USERPRIVS holds all of the response attributes for all policies that apply to that user, in all policy domains.
SM_USERREALMPRIVS
When a user is authenticated or is authorized for a resource under a realm, SM_USERREALMPRIVS holds all the response attributes for all rules under that realm.
For example, suppose that there is a realm called Equipment Purchasing. Under that realm, there is a CheckCredit rule. Associated with the CheckCredit rule is a response that returns the buyer’s credit limit, such as limit = $15000, as a response attribute. If the buyer attempts to purchase equipment worth $5000, the CheckCredit rule fires. SM_USERREALMPRIVS would contain all of the response attributes for all of the rules under the Equipment Purchasing realm.
SM_USERDISABLEDSTATE
Returns a decimal number that represents a bit mask of reasons that a user is disabled. The bits are defined in SmApi.h under the Sm_Api_DisabledReason_t data structure.
For example, a user may be disabled as a result of inactivity, Sm_Api_Disabled_Inactivity. In Sm_Api_DisabledReason_t, the reason Sm_Api_Disabled_Inactivity, corresponds to the value 0x00000004. So, in this case, SM_USERDISABLEDSTATE is 4..
NTUSERNAME
Returns the username portion of the fully qualified WinNT name—for example, for mydomain\myname, myname is returned.
NTFULLUSERNAME
Returns the fully qualified WinNT name.
Some applications require knowledge of user credentials. SiteMinder can make the user password available to the application by returning a well-known attribute SM_USERPASSWORD. This attribute is only available after a successful authentication through the OnAuthAccept event.
The following example demonstrates retrieving a password.
char lpszSmPassword(128); int nBytes = lpUserContext->fGetProp(lpUserContext->lpParam, “SM_USERPASSWORD”, sizeof (lpszSmPassword), lpszSmPassword);
The Policy Server works in tandem with the Web Agent. While it is authenticating and authorizing, the Policy server sends certain information about the outcome of the operation to the Web Agent. The Web Agent makes this information available to the application as follows:
Authentication events without a redirect:
Authentication events with a redirect:
If the reason code is included in the following form:
SMAUTHREASON=$$SMAUTHREASON$$
the value is used in the authentication reason field for SM_AGENTAPI_LOGIN, along with the username and password.
Authorization events without a redirect:
Authorization events with a redirect:
|
Copyright © 2012 CA.
All rights reserved.
|
|