|
![]() |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
This is the interface to the security platform functionality. This interface provides for:
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.
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 |
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".
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".
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".
CSSUserIF.getToken()
,
Constant Field Valuespublic 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".
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".
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:
The value of this constant is "hyperion.providerType".
public static final java.lang.String ENTRY_TYPE_USER
The value of this constant is "USER".
public static final java.lang.String ENTRY_TYPE_GROUP
The value of this constant is "GROUP".
public static final java.lang.String ENTRY_TYPE_OTHER
The value of this constant is "OTHER".
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".
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".
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 value of this constant is "securityAgent.loginName".
public static final java.lang.String PROVIDER_TYPE_LDAP
The value of this constant is specified by
CSSConfigurationDefaults.PROVIDER_TYPE_LDAP
.
public static final java.lang.String PROVIDER_TYPE_NTLM
The value of this constant is specified by
CSSConfigurationDefaults.PROVIDER_TYPE_NTLM
.
public static final java.lang.String PROVIDER_TYPE_MSAD
The value of this constant is specified by
CSSConfigurationDefaults.PROVIDER_TYPE_MSAD
.
public static final java.lang.String PROVIDER_TYPE_CUSTOM
The value of this constant is specified by
CSSConfigurationDefaults.PROVIDER_TYPE_CUSTOM
.
Method Detail |
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:
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.
authenticate
in interface com.hyperion.css.common.internal.CSSFrameworkIF
context
- - Map structure holding key-value information about login name, password, token, and locale.
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.CSSUserIF
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:
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.
getUsers
in interface com.hyperion.css.common.internal.CSSFrameworkIF
context
- - Map structure holding key-value information about locale.userName
- String argument representing the user login name.
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.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:
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.
getUserByEmail
in interface com.hyperion.css.common.internal.CSSFrameworkIF
context
- Map structure holding key-value information about locale.email
- The complete e-mail address string for the user.
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.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:
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.
getUsersByName
in interface com.hyperion.css.common.internal.CSSFrameworkIF
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.
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.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:
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.
getUsers
in interface com.hyperion.css.common.internal.CSSFrameworkIF
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.
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(Map, String, String)
,
getUsers(Map, String)
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:
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.
getUserByIdentity
in interface com.hyperion.css.common.internal.CSSFrameworkIF
context
- Map structure holding information about the locale.identity
- String returned from the user object that uniquely
identifies one user on a provider.
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.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:
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.
getGroups
in interface com.hyperion.css.common.internal.CSSFrameworkIF
context
- Map structure holding locale information.name
- Name of the group.
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.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:
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.
getGroupByIdentity
in interface com.hyperion.css.common.internal.CSSFrameworkIF
context
- Map structure holding locale information.identity
- String returned from the group object that uniquely
identifies one group on a provider.
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.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:
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.
context
- Map structure holding provider and/or locale information.token
- Encrypted string that holds information for a user.
CSSIllegalArgumentException
- - if there is an argument that is inappropriate.
CSSConfigurationException
- - if the configuration specified is not valid.
CSSException
- - if there was any other abnormality.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:
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.
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.
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 abnormalitypublic void initialize(com.hyperion.css.application.CSSApplicationIF appCallback) throws CSSConfigurationException, CSSIllegalArgumentException, CSSException
initialize(Map, CSSApplicationIF)
Initializes the security platform by specifying the callback into the application.
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.
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 abnormalitypublic 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:
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.
context
- Map structure holding locale information.
CSSIllegalArgumentException
- - if there is an argument that is inappropriate.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.
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:
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.
context
- Map structure holding locale information.
CSSIllegalArgumentException
- - if there is an argument that is inappropriate.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 context can specify the following:
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.
context
- Map structure holding locale information.
CSSIllegalArgumentException
- - if there is an argument that is inappropriate.
|
Copyright 2004 Hyperion Solutions Corporation. All rights reserved. |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |