Programming Guides › Programming Guide for Java › Authentication and Authorization APIs

Authentication and Authorization APIs

This section contains the following topics:

Configuration of All Custom Classes

Custom Classes for Authentication and Authorization

Required Library File

Shared Information

Common Classes

Create a Custom Authentication Scheme

Use the Authorization API

Configuration of All Custom Classes

The following configuration information applies to all custom authentication schemes and active expressions implemented with the Java Authentication API and Java Authorization API:

• The library name is always smjavaapi.
• In the parameter field, the first item must be the name of the custom class you implemented with the Authentication API or Authorization API, as follows:
  • With authentication schemes, specify the name of the class you implemented from the base interface SmAuthScheme. The class name should include the fully qualified package name, such as:

    com.myorg.sdk.myclass

  • With active policies, active rules, and active responses, specify the name of the class you implemented from the base interface ActiveExpression.
• If any parameters are specified in the parameter field after the class name, the class name is separated from the parameters list by a space character.

  When SiteMinder calls the methods in an instance of your custom class, it passes the specified parameters. The class name is not passed. The parameters are passed as a single string. If the string contains multiple parameters, the parameters can be delimited in any way that the custom class requires.

• The class file specified in the parameter field must be referenced in the classpath directive of the JVMOptions.txt configuration file. This file is located in Netegrity/SiteMinder/Config within the SiteMinder installation path.
• With active expressions, the function name (that is, the entry point for the smjavaapi library file) is always JavaActiveExpression.

Custom Classes for Authentication and Authorization

The basic steps for implementing and deploying custom authentication or authorization classes are as follows:

1. Implement the custom authentication or authorization class using the Authentication or Authorization API and the common classes.
2. Deploy the custom class or jar file on the Policy Server machine, and specify its location in the classpath directive of the JVMOptions.txt file. This file is located in Netegrity/siteminder/config within the SiteMinder installation path.
3. Configure the custom authentication or authorization functionality in the Policy Server User Interface.

Required Library File

All custom authentication and authorization classes use the same library file—smjavaapi. This library file is included with the Policy Server. You do not have to modify this library file. You simply reference it when you are configuring your custom authentication or authorization class.

Shared Information

Custom authentication and authorization objects may sometimes need to communicate request-specific information between themselves, such as to preserve state between object instances. These objects can share information through AppSpecificContext, which is retrieved through ApiContext. ApiContext is one of the common classes that is passed to both authentication and authorization objects.

Information shared through AppSpecificContext has request-only scope. For example, a custom object running in the context of an authentication request cannot exchange information with an object running in the context of an authorization request.

Common Classes

The following classes are used by both the Authentication API and the Authorization API. The services that these classes provide include:

• Sending logging, tracing, and error messages to the Policy Server
• Providing a mechanism for custom authentication and authorization objects to share information
• Making user context information available to authentication and authorization objects

The following table summarizes the common classes:

Create a Custom Authentication Scheme

Authentication schemes provide a way to collect a user’s credentials and determine the user’s identity.

The Policy Server includes a variety of standard authentication schemes. These schemes range from basic user name/password authentication and HTML forms-based authentication to digital certificate and token authentication.

If the standard authentication schemes included with the Policy Server do not provide the kind of authentication functionality required at your site, you can use the Java Authentication API to create a custom authentication scheme.

Classes and Interfaces in the Authentication API

The base interface in the Java Authentication API is SmAuthScheme. All custom authentication schemes created with the Java Authentication API must implement this interface.

SmAuthScheme Methods

SiteMinder calls the following methods in the base interface SmAuthScheme:

Other Classes in the Authentication API

The following classes are used in conjunction with the SmAuthScheme base interface:

How SiteMinder Loads a Custom Authentication Scheme in Java

When user authentication is to occur against a custom authentication scheme created with the Java API, SiteMinder loads the custom scheme by loading:

• The standard library file smjavaapi that is installed with the Policy Server
• An instance of the custom class implemented from SmAuthScheme

How SiteMinder Initializes Authentication Processing

Immediately after the scheme is loaded, SiteMinder calls the following methods in the custom class implemented from SmAuthScheme:

• query(). SiteMinder passes SMAUTH_QUERY_DESCRIPTION in the request parameter, requesting that the authentication scheme pass back the version number and description of the Java Authentication API.

  Note: When SiteMinder passes SMAUTH_QUERY_CREDENTIALS_REQ in query(), SiteMinder is requesting that the authentication scheme specify the kind of credentials that are required. SiteMinder then collects the specified credentials.

• init(). SiteMinder passes the parameter string and shared secret that were defined when the authentication scheme was configured in the Policy Server. The scheme then performs any initialization procedures it requires.

Authentication of User Credentials

The following figure shows the key activities that occur during authentication:

Supported Credentials

The Java Authentication API supports authentication based on the following general types of credentials requirements:

• Username/Password
• X.509 Certificate
• Custom user attributes

You specify the authentication credentials that are required through the setResponseBuffer() method in the object SmAuthQueryResponse. This object contains a number of constants that indicate the specific credentials that are required or whether no credentials are required.

User Disambiguation and Authentication

The authentication process includes two phases—user disambiguation and user authentication.

Before a user can be authenticated, the user’s profile information must be retrieved from the user store so that the user’s stored credentials can be compared with the credentials supplied at login. Looking up the user in a user store (such as an LDAP user directory or an ODBC database) is called user disambiguation. Either SiteMinder or the authentication scheme can disambiguate the user.

SiteMinder calls SmAuthScheme.authenticate() at least once during the disambiguation phase and at least once during the authentication phase:

• During disambiguation, it is called once per directory where disambiguation occurred.
• During authentication, it is called once per user found in the directory.

The basic steps are as follows:

1. User login. The user supplies a login ID (such as jsmith) for authentication purposes.
2. Disambiguation phase. Before the user lookup in the data store can begin, a complete DN or a search expression must be constructed based upon the supplied login ID. For example, if the login ID is jsmith, the DN used to search the user store might be constructed as follows:

   uid=jsmith,ou=marketing,o=myorg.org
   

   An LDAP search expression can also be used to search an LDAP user directory, and a SQL query is used to search an ODBC database—for example:

   (&(objectclass=inetOrgPerson)(uid=jsmith))
   

   select Name from SmUser where Name = 'jsmith'

   Multiple results are possible, given that the LDAP DN or the ID stored in the ODBC database might apply to different users who have different passwords.

3. Authentication phase. The custom authentication scheme compares the known credentials of each disambiguated user with the credentials supplied during login—for example, by comparing the hash of the supplied password against the hash in the user store.

User Disambiguation

SiteMinder first calls authenticate() at the beginning of the user disambiguation phase.

Either SiteMinder or the custom authentication scheme can disambiguate the user. The authentication scheme indicates whether it has performed the disambiguation through a combination of the following:

• One of the status codes listed below
• Whether a value is passed to SiteMinder in the setUserText() method of SmAuthenticationContext

The status codes are set in the SmAuthStatus object. This object is passed in the status parameter of the SmAuthenticationResult constructor. SmAuthenticationResult is returned from authenticate():

• SMAUTH_NO_USER_CONTEXT

  The authentication scheme asks SiteMinder to disambiguate the user.

  When returning this status code, the authentication scheme should also return an empty string through the setUserText() method. SiteMinder gets the login ID from the Agent, constructs the DN or search expression based on the login ID and the information defined in the SiteMinder User Directory Properties dialog box, and disambiguates the user by looking up the user in the user store.

• SMAUTH_SUCCESS

  The authentication scheme asks SiteMinder to disambiguate the user.

  The authentication scheme passes the login ID to SiteMinder through setUserText(). SiteMinder uses that value to construct the DN or search expression and disambiguate the user in the user store. This approach gives the authentication scheme the opportunity to modify the login ID before SiteMinder disambiguates the user.

  Note: If the authentication scheme passes an empty string in setUserText(), SiteMinder uses the login ID provided by the Agent (the same behavior as with return code SMAUTH_NO_USER_CONTEXT).

• SMAUTH_SUCCESS_USER_DN

  The authentication scheme disambiguates the user by constructing the complete DN or search expression and looking up the user in the user store. The authentication scheme passes the user’s complete DN or ODBC database ID to SiteMinder in setUserText(). Only one DN or database ID can be passed in setUserText().

• SMAUTH_ATTEMPT.

  The user cannot be found in the directory.

• SMAUTH_FAILURE

  This is returned if an error condition exists. Error text is returned to SiteMinder through the setUserText() method.

User Authentication

During this phase, SiteMinder calls authenticate() again to allow the authentication scheme to verify the supplied credentials after the user context has been established during disambiguation. The method sets one of the following status codes:

• SMAUTH_ACCEPT. The user is authenticated.
• SMAUTH_REJECT. The user is not authenticated.
• SMAUTH_CHALLENGE. The user is challenged. The scheme passes the challenge message to SiteMinder through the setUserText() method. Also, a reason code must be supplied in the SmAuthenticationResult object returned by authenticate().
• SMAUTH_FAILURE. An error condition occurred. Error text is passed to SiteMinder in setUserText().

Redirection

Your authentication scheme can have the Policy Server instruct the agent to perform a redirect. To build redirection capabilities into your authentication scheme:

• Specify the redirection URL in:

  SmAuthenticationContext.setErrorText()
  

• When creating an SmAuthenticationResult object to return from authenticate(), specify REASON_ERROR_MESSAGE_IS_REDIRECT in the reason parameter of the constructor.

Authentication Events

Authentication results are tied to SiteMinder events. If authentication events are enabled in the realm where the user is being authenticated, SiteMinder evaluates optional policies tied to OnAuthAccept, OnAuthReject, OnAuthAttempt, and OnAuthChallenge rules. You can configure these policies to return custom responses based on a user’s identity, redirect the user to another location based on the result of the authentication, or update the user data in an external database.

Extend the SAML and WS-Federation Authentication Schemes

The SiteMinder SAML (1.x and 2.0) and WS-Federation authentication schemes process response messages. For business reasons, for example, you might want to add additional steps to further process a response. The Message Consumer Extension API defines an interface that enables you to elaborate on the SAML or WS-Federation response in two ways during the authentication process:

• To report detailed failure reasons during user disambiguation
• To customize user credential validation

The SiteMinder Java MessageConsumerPlugin API implements the Message Consumer Extension (MCE) interface. You can code to your own requirements and then integrate the custom plug-in into SiteMinder.

The MessageConsumerPlugin includes the following four methods:

SiteMinder provides the following samples of the Message Consumer plug-in class:

• MessageConsumerPluginSample.java in <install-path>\sdk\samples\messageconsumerplugin
• MessageConsumerSAML20.java in <install-path>\sdk\samples\authextensionsaml20

The Role of the MessageConsumerPlugin

The following list describes the MessageConsumerPlugin in an elaborated process of user authentication:

1. The Federation Web Services (FWS) application forwards a request for user authentication to the Policy Server.
2. The Policy Server invokes the authentication scheme to disambiguate the user.
3. The authentication scheme disambiguates the user as follows:
   1. The authentication scheme metadata is obtained from the Policy store.
   2. The authentication scheme attempts to obtain the LoginID. If LoginID is not found, the authentication scheme invokes the MessageConsumerPlugin as described in Step 4.
   3. If the LoginID is obtained successfully, the authentication scheme searches the current user directory with a predefined SearchSpec. If the user is not found, the postDisambiguate() method is called as described in Step 4. If the user is found, the Policy Server proceeds with credential validation, as described in Step 6 and following.
   4. When the authentication scheme does not provide the user store SearchSpec, the Policy Server core searches for the user with the search string defined with the User Directory object. The MessageConsumerPlugin is not called.
4. The postDisambiguateUser() method searches a user directory to determine whether a particular LoginID exists. The result is returned to the authentication scheme. The method might be called several times if more than one user directory is configured. This method can also be used to add data for new federation users from the assertion to a user store.
5. When the user has been successfully disambiguated by the Policy Server, the authentication scheme, or the plug-in, the Policy Server returns the user DN to the Policy Server and proceeds to credential validation (Step 8 and following).
6. If the user has not been successfuly disambiguated for this user directory by either the Policy Server, the authentication scheme, or MessageConsumerPlugin, the FWS application checks the next user directory and repeats Steps 2 - 6 before proceeding with credential validation.
7. When a user has been disambiguated, the Policy Server again calls the authentication scheme to determine whether the user has the proper credentials for the authentication request. The authentication scheme determines whether the response message is acceptable.
8. After the the authentication scheme has attempted to authenticate the disambiguated user with the response message, the Policy Server calls the postAuthenticateUser() method from the MessageConsumerPlugin. The Policy Server always calls this method when a user is disambiguated, even when the Policy Server core performs the user disambiguation.
9. You can use postAuthenticateUser() to add any other procedures for federation credential validation required by your implementation.
10. The final result is passed back to the Policy Server by the authenticaiton scheme.
11. If necessary, the FWS application can process any failure and redirect the user to an appropriate URL.

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.