com.hyperion.css
Interface CSSAPIIF

All Superinterfaces:
com.hyperion.css.common.internal.CSSFrameworkIF

public interface CSSAPIIF
extends com.hyperion.css.common.internal.CSSFrameworkIF

This is the interface to the security platform functionality. This interface provides for:

  1. Authentication by user name and password.
  2. Authentication by token.
  3. Integration with a Security Agent (For instance: Netegrity SiteMinder)
  4. Getting users and groups based on names and identities.

The searchOrder that is specified in the associated configuration is used to determine the sequence in which the plugged-in providers are called to get to the information requested. Note: Unless specified otherwise the switch from one provider to another in the search order would take place only if the first provider does not return anything.

Sample use of the application:


    Map context = new HashMap(5);

    CSSSystem instance = CSSSystem.getInstance();
    CSSAPIIF css = instance.getCSSAPI();

 	  context.put(CSSAPIIF.LOCALE, new Locale("en", "US"));
 	  context.put(CSSAPIIF.LOG_PREPEND_TEXT, "[APP_NAME/IPADDRESS]");
    css.initialize(context, appCallback);
    try
    {
    	context.put(CSSAPIIF.LOGIN_NAME, "gkhanna");
    	context.put(CSSAPIIF.PASSWORD, "password");

      CSSUserIF user = css.authenticate(context);
    }
    catch (CSSTokenNotAvailableException tNAE)
    {
       // log this
       // check message and error code for more info
       // try again
    }
    catch (CSSAuthenticationException aE)
    {
       // Unable to authenticate
       // check credentials
       // check message and error code for more info
       // log this
    }
    catch (CSSIllegalArgumentException iAE)
    {
       // check arguments and correct them according to the contract
       // check message and error code for more info
       // try again
    }
    catch (CSSNoProviderException nPE)
    {
       // CSS was unable to launch a provider
       // that was requested in the provider entry in the context
       // check message and error code for more info
       // check and try again
       // log this
    }
    catch (CSSInvalidIdentityException iIE)
    {
       // Unable to use the identity passed in the token
       // log this
    }
    catch (CSSTokenNotAcceptedException tNAcceptedE)
    {
       // the token passed in is not valid
       // log this
    }
    catch (CSSException e)
    {
       // Any other abnormality
       // check message and error code for more info
       // log this
    }
 

To override the search order, the specification of the provider in the input is supported through the following syntax:

entryName@ProviderName

Here, entryName could be a userName or a groupName. The ProviderName specifies the name of the provider as determined in the Configuration settings.

There is a specific case for NTLM providers. The NTLM provider may or may not specify a domain. If it does specify a domain, then that NTLM provider is only responsible for performing the operations on that domain.
If on the other hand, no domain is specified, then the provider performs operations on all the trusted domains. If a token contains a domain that does not correspond to any of the NTLM providers listed domains, then the first provider that does not have domain listed would be used.

Some examples:

The getUsers(context, name) is to be called with a name parameter to get user/s that have that name. Passing null is not accepted and would not return all the users.
You can use wildcards such as '*' for the userName parameter. In this case users would be returned in the order of directories that is specified by the search order.
You could retreive all users on a provider by specifying "*@providerName"

The getGroups(context, groupName) can be called with the wildcard * for groupName to get all the groups from the first provider in the search order. In this case it would go by the search order.
To get all groups from a particular provider, specify "*@providerName".
This follows the "groupName@providerName" syntax. You can also have wildcards such as "GA*@providerName" for the groupName parameter.

Since:
v2.0

Field Summary
static java.lang.String ENTRY_TYPE_GROUP
          Constant that holds type of the entry.
static java.lang.String ENTRY_TYPE_OTHER
          Constant that holds the type of the entry.
static java.lang.String ENTRY_TYPE_USER
          Constant that holds the type of the entry.
static java.lang.String LOCALE
          Constant that holds the property that specifies the name of the Locale.
static java.lang.String LOG_PREPEND_TEXT
          Constant that holds the the name of the property that specifies the text message to be prepended to the log messages.
static java.lang.String LOGIN_NAME
          Constant that holds the name of the property for specifying the user name.
static java.lang.String PASSWORD
          Constant that holds the name of the property for specifying the password.
static java.lang.String PROVIDER_NAME
          Constant that holds the name of the property for specifying the provider to be used.
static java.lang.String PROVIDER_REQUEST
          Constant that holds the name of the property for specifying the provider URL that an entry belongs to.
static java.lang.String PROVIDER_TYPE
          Constant that holds the name of the property for specifying the provider type to be used.
static java.lang.String PROVIDER_TYPE_CUSTOM
          Constant that holds the type specified for the custom provider.
static java.lang.String PROVIDER_TYPE_LDAP
          Constant that holds the type specified for the LDAP provider.
static java.lang.String PROVIDER_TYPE_MSAD
          Constant that holds the type specified for the MSAD provider.
static java.lang.String PROVIDER_TYPE_NTLM
          Constant that holds the type specified for the NTLM provider.
static java.lang.String SECURITY_AGENT_LOGIN_NAME
          Constant that holds name of the property for specifying the login name.
static java.lang.String TOKEN
          Constant that holds the name of the property for specifying the token string.
 
Method Summary
 com.hyperion.css.common.CSSUserIF authenticate(java.util.Map context)
          The user is authenticated by the security platform.
 com.hyperion.css.common.CSSGroupIF getGroupByIdentity(java.util.Map context, java.lang.String identity)
          Get a group based on the identity of the group.
 com.hyperion.css.common.CSSGroupIF[] getGroups(java.util.Map context, java.lang.String name)
          Get a group based on the name.
 java.lang.String[] getHeaderNamesFromSecurityAgent(java.util.Map context)
          This method returns the HTTP headers that would carry the login name of the user.
 java.lang.String[] getProviderNames(java.util.Map context)
          Gets the names of the providers that are registered with the security platform.
 com.hyperion.css.common.CSSUserIF getUserByEmail(java.util.Map context, java.lang.String email)
          Get a user based on an email match.
 com.hyperion.css.common.CSSUserIF getUserByIdentity(java.util.Map context, java.lang.String identity)
          Get a user based on the identity of the user.
 com.hyperion.css.common.CSSUserIF[] getUsers(java.util.Map context, java.lang.String userName)
          Gets the user specified by userName.
 com.hyperion.css.common.CSSUserIF[] getUsers(java.util.Map context, java.lang.String userName, java.lang.String firstName, java.lang.String lastName)
          Get a user based on a user name , firstName and lastName match.
 com.hyperion.css.common.CSSUserIF[] getUsersByName(java.util.Map context, java.lang.String firstName, java.lang.String lastName)
          Get a user based on a firstName and lastName match.
 void initialize(com.hyperion.css.application.CSSApplicationIF appCallback)
          Deprecated. As of CSS 2.5, replaced by initialize(Map, CSSApplicationIF)
 void initialize(java.util.Map context, com.hyperion.css.application.CSSApplicationIF appCallback)
          Initializes the security platform by specifying the callback into the application.
 boolean isSecurityAgentProtected(java.util.Map context)
          This method is invoked to determine if the access to a resource might be protected by a Security Agent.
 boolean isValidCSSToken(java.util.Map context, java.lang.String token)
          Determines if the token is valid.
 

Field Detail

LOGIN_NAME

public static final java.lang.String LOGIN_NAME

Constant that holds the name of the property for specifying the user name. The value of the property should be the login name of the user.

The value of this constant is "hyperion.loginName".

See Also:
Constant Field Values

PASSWORD

public static final java.lang.String PASSWORD

Constant that holds the name of the property for specifying the password. The value of the property should be the password of the user.

The value of this constant is "hyperion.password".

See Also:
Constant Field Values

TOKEN

public static final java.lang.String TOKEN

Constant that holds the name of the property for specifying the token string. The value of the property should be the token associated with a user.

The value of this constant is "hyperion.token".

See Also:
CSSUserIF.getToken(), Constant Field Values

PROVIDER_REQUEST

public static final java.lang.String PROVIDER_REQUEST

Constant that holds the name of the property for specifying the provider URL that an entry belongs to. The value of the property should be the provider URL. For instance: "ldap://localhost:389/ou=abc,o=com" For NTLM, the provider URL would be the domain name.

This is used in isValidCSSToken(Map, String)

The value of this constant is "hyperion.providerRequest".

See Also:
Constant Field Values

PROVIDER_NAME

public static final java.lang.String PROVIDER_NAME

Constant that holds the name of the property for specifying the provider to be used. The value of the property should be the provider name. For instance: ldapServer1, NTLMServer2 etc.
In the configuration, the provider name maps to the entries in the searchOrder element.

The value of this constant is "hyperion.providerName".

Since:
CSS v2.0.8
See Also:
Constant Field Values

PROVIDER_TYPE

public static final java.lang.String PROVIDER_TYPE

Constant that holds the name of the property for specifying the provider type to be used. The value of the property should be the provider type. For instance: NTLM, LDAP, MSAD etc.

This is specified by constants:

  1. PROVIDER_TYPE_LDAP
  2. PROVIDER_TYPE_MSAD
  3. PROVIDER_TYPE_NTLM
  4. PROVIDER_TYPE_CUSTOM

The value of this constant is "hyperion.providerType".

Since:
CSS v2.0.8
See Also:
Constant Field Values

ENTRY_TYPE_USER

public static final java.lang.String ENTRY_TYPE_USER
Constant that holds the type of the entry.

The value of this constant is "USER".

See Also:
Constant Field Values

ENTRY_TYPE_GROUP

public static final java.lang.String ENTRY_TYPE_GROUP
Constant that holds type of the entry.

The value of this constant is "GROUP".

See Also:
Constant Field Values

ENTRY_TYPE_OTHER

public static final java.lang.String ENTRY_TYPE_OTHER
Constant that holds the type of the entry.

The value of this constant is "OTHER".

See Also:
Constant Field Values

LOCALE

public static final java.lang.String LOCALE

Constant that holds the property that specifies the name of the Locale.

The value of this constant is "LOCALE".

See Also:
Constant Field Values

LOG_PREPEND_TEXT

public static final java.lang.String LOG_PREPEND_TEXT

Constant that holds the the name of the property that specifies the text message to be prepended to the log messages.

The value of this constant is "LOG_PREPEND_TEXT".

Since:
CSS v2.5
See Also:
Constant Field Values

SECURITY_AGENT_LOGIN_NAME

public static final java.lang.String SECURITY_AGENT_LOGIN_NAME

Constant that holds name of the property for specifying the login name. The value of this property is the login name that is retrieved from the Security Agent.


The Security Agent could be Netegrity SiteMinder. The value for this constant should be the login name for a user.

The value of this constant is "securityAgent.loginName".

Since:
CSS v2.5
See Also:
Constant Field Values

PROVIDER_TYPE_LDAP

public static final java.lang.String PROVIDER_TYPE_LDAP
Constant that holds the type specified for the LDAP provider.

The value of this constant is specified by CSSConfigurationDefaults.PROVIDER_TYPE_LDAP.

Since:
CSS v2.0.8

PROVIDER_TYPE_NTLM

public static final java.lang.String PROVIDER_TYPE_NTLM
Constant that holds the type specified for the NTLM provider.

The value of this constant is specified by CSSConfigurationDefaults.PROVIDER_TYPE_NTLM.

Since:
CSS v2.0.8

PROVIDER_TYPE_MSAD

public static final java.lang.String PROVIDER_TYPE_MSAD
Constant that holds the type specified for the MSAD provider.

The value of this constant is specified by CSSConfigurationDefaults.PROVIDER_TYPE_MSAD.

Since:
CSS v2.0.8

PROVIDER_TYPE_CUSTOM

public static final java.lang.String PROVIDER_TYPE_CUSTOM
Constant that holds the type specified for the custom provider.

The value of this constant is specified by CSSConfigurationDefaults.PROVIDER_TYPE_CUSTOM.

Since:
CSS v2.0.8
Method Detail

authenticate

public com.hyperion.css.common.CSSUserIF authenticate(java.util.Map context)
                                               throws CSSNoProviderException,
                                                      CSSTokenNotAvailableException,
                                                      CSSIllegalArgumentException,
                                                      CSSAuthenticationException,
                                                      CSSTokenNotAcceptedException,
                                                      CSSInvalidIdentityException,
                                                      CSSConfigurationException,
                                                      CSSException

The user is authenticated by the security platform.

The context can specify the following:

  1. login name
  2. password
  3. token
  4. locale
  5. login name from the Security Agent header

These properties are discussed in the field description. Please note that if the locale is not specified, the default locale set for the system is used.

If the login name from the header is specified as SECURITY_AGENT_LOGIN_NAME and is passed in the context argument then authentication using the loginName specified by this header would take precedence. This implies that even if a token To extend the lifetime of a token, this method can be invoked and the token is stamped with the current time and its validity period is reset.

The entryName@ProviderName syntax is supported by this method. This can be specified in the user name.

The domainName\entryName syntax is also supported for the benefit of applications using NTLM as the authentication protocol.

This method does not support wildcards in the arguments. No guarantee is made for the behavior of this method if wildcards are part of the arguments.

Also, reserved characters for different directory servers are not directly supported.The caller needs to escape them in the appropriate way for the underlying directory store.

Specified by:
authenticate in interface com.hyperion.css.common.internal.CSSFrameworkIF
Parameters:
context - - Map structure holding key-value information about login name, password, token, and locale.
Returns:
CSSUserIF - this contains the token string that can be used to single-sign-on.
Throws:
CSSNoProviderException - - if no provider exists with the name specified.
CSSIllegalArgumentException - - if there is an argument that is inappropriate.
CSSAuthenticationException - - If there was a match for the user but the credentials were incorrect.
CSSTokenNotAcceptedException - - if the token was not based on a provider for this application.
CSSTokenNotAvailableException - - if the token could not be contructed.
CSSInvalidIdentityException - - if the identity encapsulated in the token was invalid.
CSSConfigurationException - - if the configuration specified is not valid.
CSSException - - if there was any other abnormality.
See Also:
CSSUserIF

getUsers

public com.hyperion.css.common.CSSUserIF[] getUsers(java.util.Map context,
                                                    java.lang.String userName)
                                             throws CSSNoProviderException,
                                                    CSSIllegalArgumentException,
                                                    CSSConfigurationException,
                                                    CSSException

Gets the user specified by userName. The userName could be mapped to a particular attribute in a directory through the Configuration. The search for users based on *userName* should be based on getting all users who have userName as a part of the value of the attribute specified.

The userName could contain a wildcard such as "*". This implies that all the matching users in the directory need to be returned. However, the NTLM provider does not support * as a prefix to the userName.

Passing null as the userName parameter is not accepted and would not return all the users. You can use wildcards such as '*' for the userName parameter. In this case users would be returned in the order of directories that is specified by the search order.
You could retreive all users on a provider by specifying "*@providerName"

Passing a groupName to this call is not supported and no guarantees are made on the validity of the results.

The context can specify the following:

  1. locale

These properties are discussed in the field description. Please note that if the locale is not specified, the default locale set for the system is used.

The entryName@ProviderName syntax is supported by this method as a part of the user name.

Also, reserved characters for different directory servers are not directly supported.The caller needs to escape them in the appropriate way for the underlying directory store.

Specified by:
getUsers in interface com.hyperion.css.common.internal.CSSFrameworkIF
Parameters:
context - - Map structure holding key-value information about locale.
userName - String argument representing the user login name.
Returns:
CSSUserIF[] - Returns an empty array if there are no matches.
Throws:
CSSNoProviderException - - if no provider exists with the name specified.
CSSIllegalArgumentException - - if there is an argument that is inappropriate.
CSSConfigurationException - - if the configuration specified is not valid.
CSSException - - if there was any other abnormality.

getUserByEmail

public com.hyperion.css.common.CSSUserIF getUserByEmail(java.util.Map context,
                                                        java.lang.String email)
                                                 throws CSSNoProviderException,
                                                        CSSIllegalArgumentException,
                                                        CSSConfigurationException,
                                                        CSSException

Get a user based on an email match. The email could be mapped to a particular attribute in a directory through the configuration. The search for users based on email should be absolute.

The context can specify the following:

  1. locale

These properties are discussed in the field description. Please note that if the locale is not specified, the default locale set for the system is used.

This method is not supported by the NTLM provider.

Wildcards should not be used in the arguments of this method. No guarantee is made for the behavior of this method if wildcards are part of the arguments.

Also, reserved characters for different directory servers are not directly supported.The caller needs to escape them in the appropriate way for the underlying directory store.

Specified by:
getUserByEmail in interface com.hyperion.css.common.internal.CSSFrameworkIF
Parameters:
context - Map structure holding key-value information about locale.
email - The complete e-mail address string for the user.
Returns:
CSSUserIF
Throws:
CSSNoProviderException - - if no provider exists with the name specified.
CSSIllegalArgumentException - - if there is an argument that is inappropriate.
CSSConfigurationException - - if the configuration specified is not valid.
CSSException - - if there was any other abnormality.

getUsersByName

public com.hyperion.css.common.CSSUserIF[] getUsersByName(java.util.Map context,
                                                          java.lang.String firstName,
                                                          java.lang.String lastName)
                                                   throws CSSNoProviderException,
                                                          CSSIllegalArgumentException,
                                                          CSSConfigurationException,
                                                          CSSException

Get a user based on a firstName and lastName match. The firstName and lastName could be mapped to a particular set of attribute/s in a directory through the configuration. If there are two attributes, one each for firstName and lastName , then the search would be absolute and an AND would be performed.

If one of the parameters (for example, firstName) is not specified, then results for the other (for example, lastName are returned.

Wildcards should not be used in the arguments of this method. No guarantee is made for the behavior of this method if wildcards are part of the arguments.

The context can specify the following:

  1. locale

These properties are discussed in the field description.

Please note that if the locale is not specified, the default locale set for the system is used.

This method is not supported by the NTLM provider.

Also, reserved characters for different directory servers are not directly supported.The caller needs to escape them in the appropriate way for the underlying directory store.

Specified by:
getUsersByName in interface com.hyperion.css.common.internal.CSSFrameworkIF
Parameters:
context - Map structure holding key-value information about locale.
firstName - The user's first name, with appended middle name if one exists.
lastName - The user's last name.
Returns:
CSSUserIF[]
Throws:
CSSNoProviderException - - if no provider exists with the name specified.
CSSIllegalArgumentException - - if there is an argument that is inappropriate.
CSSConfigurationException - - if the configuration specified is not valid.
CSSException - - if there was any other abnormality.

getUsers

public com.hyperion.css.common.CSSUserIF[] getUsers(java.util.Map context,
                                                    java.lang.String userName,
                                                    java.lang.String firstName,
                                                    java.lang.String lastName)
                                             throws CSSNoProviderException,
                                                    CSSIllegalArgumentException,
                                                    CSSConfigurationException,
                                                    CSSException

Get a user based on a user name , firstName and lastName match. All the attributes are absolute and required. The way this is evaluated is as follows (in LDAP parlance):

 (&(userName="gkhanna")(firstName="Gaurav")(lastName="khanna") )
 

This can be explained as simply the AND of all the arguments.

The context can specify the following:

  1. locale

These properties are discussed in the field description. Please note that if the locale is not specified, the default locale set for the system is used.

Wildcards should not be used in the arguments of this method. No guarantee is made for the behavior of this method if wildcards are part of the arguments.

Also, reserved characters for different directory servers are not directly supported.The caller needs to escape them in the appropriate way for the underlying directory store.

Specified by:
getUsers in interface com.hyperion.css.common.internal.CSSFrameworkIF
Parameters:
context - Map structure holding key-value information about locale.
userName - String argument representing the user login name.
firstName - The user's first name, with appended middle name if one exists.
lastName - The user's last name.
Returns:
CSSUserIF[] - empty if there is no match
Throws:
CSSNoProviderException - - if no provider exists with the name specified.
CSSIllegalArgumentException - - if there is an argument that is inappropriate.
CSSConfigurationException - - if the configuration specified is not valid.
CSSException - - if there was any other abnormality.
See Also:
getUsersByName(Map, String, String), getUsers(Map, String)

getUserByIdentity

public com.hyperion.css.common.CSSUserIF getUserByIdentity(java.util.Map context,
                                                           java.lang.String identity)
                                                    throws CSSNoProviderException,
                                                           CSSInvalidIdentityException,
                                                           CSSInvalidUserException,
                                                           CSSIllegalArgumentException,
                                                           CSSConfigurationException,
                                                           CSSException

Get a user based on the identity of the user. The identity is stored by the application and is generated by the security platform.

The context can specify the following:

  1. locale

These properties are discussed in the field description. Please note that if the locale is not specified, the default locale set for the system is used.

Also, reserved characters for different directory servers are not directly supported.The caller needs to escape them in the appropriate way for the underlying directory store.

Specified by:
getUserByIdentity in interface com.hyperion.css.common.internal.CSSFrameworkIF
Parameters:
context - Map structure holding information about the locale.
identity - String returned from the user object that uniquely identifies one user on a provider.
Returns:
CSSUserIF
Throws:
CSSNoProviderException - - if no provider exists with the name specified.
CSSInvalidIdentityException - - if the identity is invalid.
CSSInvalidUserException - - if the user specified by the identity does not exist. The user might have been deleted.
CSSIllegalArgumentException - - if there is an argument that is inappropriate.
CSSConfigurationException - - if the configuration specified is not valid.
CSSException - - if there was any other abnormality.

getGroups

public com.hyperion.css.common.CSSGroupIF[] getGroups(java.util.Map context,
                                                      java.lang.String name)
                                               throws CSSNoProviderException,
                                                      CSSIllegalArgumentException,
                                                      CSSConfigurationException,
                                                      CSSException

Get a group based on the name. The name could be mapped to a particular attribute in a directory through the configuration. The search for groups based on *name* should be based on getting all groups who have name as a part of the value of the attribute specified. For instance: the search is on "*name*".
However, the NTLM provider does not support * as a prefix to the name.

The method can be called with the wildcard * for groupName to get all the groups from the first provider in the search order. In this case it would go by the search order.
To get all groups from a particular provider, specify "*@providerName"
.
This follows the "groupName@providerName" syntax. You can also have wildcards such as "GA*@providerName" for the groupName parameter.

The context can specify the following:

  1. locale

These properties are discussed in the field description. Please note that if the locale is not specified, the default locale set for the system is used.

The entryName@ProviderName syntax is supported by this method. This is used in the name parameter.

Also, reserved characters for different directory servers are not directly supported.The caller needs to escape them in the appropriate way for the underlying directory store.

Specified by:
getGroups in interface com.hyperion.css.common.internal.CSSFrameworkIF
Parameters:
context - Map structure holding locale information.
name - Name of the group.
Returns:
CSSGroupIF[] - empty if there is no match
Throws:
CSSNoProviderException - - if no provider exists with the name specified.
CSSIllegalArgumentException - - if there is an argument that is inappropriate.
CSSConfigurationException - - if the configuration specified is not valid.
CSSException - - if there was any other abnormality.

getGroupByIdentity

public com.hyperion.css.common.CSSGroupIF getGroupByIdentity(java.util.Map context,
                                                             java.lang.String identity)
                                                      throws CSSNoProviderException,
                                                             CSSIllegalArgumentException,
                                                             CSSInvalidIdentityException,
                                                             CSSInvalidGroupException,
                                                             CSSConfigurationException,
                                                             CSSException

Get a group based on the identity of the group. The identity is stored by the application and is generated by the security platform.

The context can specify the following:

  1. locale

These properties are discussed in the field description. Please note that if the locale is not specified, the default locale set for the system is used.

Also, reserved characters for different directory servers are not directly supported.The caller needs to escape them in the appropriate way for the underlying directory store.

Specified by:
getGroupByIdentity in interface com.hyperion.css.common.internal.CSSFrameworkIF
Parameters:
context - Map structure holding locale information.
identity - String returned from the group object that uniquely identifies one group on a provider.
Returns:
CSSGroupIF
Throws:
CSSNoProviderException - - if no provider exists with the name specified.
CSSIllegalArgumentException - - if there is an argument that is inappropriate.
CSSInvalidIdentityException - - if the identity is invalid.
CSSInvalidGroupException - - if the group specified by the identity does not exist. The group might have been deleted.
CSSConfigurationException - - if the configuration specified is not valid.
CSSException - - if there was any other abnormality.

isValidCSSToken

public boolean isValidCSSToken(java.util.Map context,
                               java.lang.String token)
                        throws CSSIllegalArgumentException,
                               CSSConfigurationException,
                               CSSException

Determines if the token is valid.

The context can specify the following:

  1. provider request - the provider to use. If this property is specified then token is also validated for this provider. This implies that the token in order to be valid should have this provider as the "server of reference".
  2. Locale

These properties are discussed in the field description. Please note that if the locale is not specified, the default locale set for the system is used.

Parameters:
context - Map structure holding provider and/or locale information.
token - Encrypted string that holds information for a user.
Returns:
boolean - true if it is valid. False otherwise.
Throws:
CSSIllegalArgumentException - - if there is an argument that is inappropriate.
CSSConfigurationException - - if the configuration specified is not valid.
CSSException - - if there was any other abnormality.

initialize

public void initialize(java.util.Map context,
                       com.hyperion.css.application.CSSApplicationIF appCallback)
                throws CSSConfigurationException,
                       CSSIllegalArgumentException,
                       CSSException

Initializes the security platform by specifying the callback into the application.

The context can specify the following:

  1. Locale
  2. text that is prepended to the log messages

These properties are discussed in the field description. Please note that if the locale is not specified, the default locale set for the system is used.


There are two types of tests on the configuration performed by this method:
  1. Static Configuration Tests: This implies tests on the structure and validity of the configuration file.
  2. Dynamic Configuration Tests: This implies tests on the correct execution of the providers based on the configuration provided. For instance: a test connection would be created to the underlying data store to determine the validity of the configuration. If a connection cannot be made to the directory store then the validity of the configuration cannot be confirmed and no exception is thrown

    Parameters:
    appCallback - Handle passed by the application implementation to the security platform, providing a way for the security platform to send information back to the calling application.
    Returns:
    void
    Throws:
    CSSConfigurationException - - if the configuration specified is not valid in terms of static tests or the configuration is not valid in terms of dynamic tests. .
    CSSIllegalArgumentException - - if there is an argument that is inappropriate.
    CSSException - - if there was any other abnormality
    Since:
    CSS v2.5

initialize

public void initialize(com.hyperion.css.application.CSSApplicationIF appCallback)
                throws CSSConfigurationException,
                       CSSIllegalArgumentException,
                       CSSException
Deprecated. As of CSS 2.5, replaced by initialize(Map, CSSApplicationIF)

Initializes the security platform by specifying the callback into the application.


There are two types of tests on the configuration performed by this method:
  1. Static Configuration Tests: This implies tests on the structure and validity of the configuration file.
  2. Dynamic Configuration Tests: This implies tests on the correct execution of the providers based on the configuration provided. For instance: a test connection would be created to the underlying data store to determine the validity of the configuration. If a connection cannot be made to the directory store then the validity of the configuration cannot be confirmed and no exception is thrown

    Parameters:
    appCallback - Handle passed by the application implementation to the security platform, providing a way for the security platform to send information back to the calling application.
    Returns:
    void
    Throws:
    CSSConfigurationException - - if the configuration specified is not valid in terms of static tests or the configuration is not valid in terms of dynamic tests. .
    CSSIllegalArgumentException - - if there is an argument that is inappropriate.
    CSSException - - if there was any other abnormality

getProviderNames

public java.lang.String[] getProviderNames(java.util.Map context)
                                    throws CSSIllegalArgumentException

Gets the names of the providers that are registered with the security platform.

The context can specify the following:

  1. locale

These properties are discussed in the field description. Please note that if the locale is not specified, the default locale set for the system is used.

Parameters:
context - Map structure holding locale information.
Returns:
String[] - the list of the providers. Empty if there are no providers listed.
Throws:
CSSIllegalArgumentException - - if there is an argument that is inappropriate.

isSecurityAgentProtected

public boolean isSecurityAgentProtected(java.util.Map context)
                                 throws CSSIllegalArgumentException

This method is invoked to determine if the access to a resource might be protected by a Security Agent.


The Security Agent could be Netegrity Siteminder. If this method returns true then the caller should attempt to locate the appropriate header; for instance, for Netegrity: SECURITY_AGENT_LOGIN_NAME; in the HTTP headers. If the header exists then the value for that should be passed into the (@link #authenticate(Map)} method.

The context can specify the following:

  1. locale

These properties are discussed in the field description. Please note that if the locale is not specified, the default locale set for the system is used.

Parameters:
context - Map structure holding locale information.
Returns:
boolean - true if the configuration specifies a Security Agent is used to protect the resources.
Throws:
CSSIllegalArgumentException - - if there is an argument that is inappropriate.
Since:
CSS v2.5

getHeaderNamesFromSecurityAgent

public java.lang.String[] getHeaderNamesFromSecurityAgent(java.util.Map context)
                                                   throws CSSIllegalArgumentException

This method returns the HTTP headers that would carry the login name of the user.


The header names are populated by the Security Agent. The Security Agent could be Netegrity SiteMinder.
The array returned could be of length > 0. If that is the case then the calling application needs to compare the headers from the HTTP REQUEST with the names from this array one by one starting from index 0. This comparison should be case insensitive.
There could be more than one header because different application/web servers map headers to different names. For instance, some might prepend HTTP to the header name.
It is the reponsibility of the product team to invoke this method and use the header names returned by it to retrieve the login name from the HTTP REQUEST.

The context can specify the following:

  1. locale

These properties are discussed in the field description. Please note that if the locale is not specified, the default locale set for the system is used.

Parameters:
context - Map structure holding locale information.
Returns:
String[] - the header names that are used to specify the login name. This is empty if there is no match.
Throws:
CSSIllegalArgumentException - - if there is an argument that is inappropriate.
Since:
CSS v2.5

Copyright 2004 Hyperion Solutions Corporation. All rights reserved.