Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Copyright 2004 Hyperion Solutions Corporation. All rights reserved.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD