org.openliberty.arisid.stack
Interface IAttrSvcStack

public interface IAttrSvcStack

IAttrSvcStack represents the interface used by all implementors of the IGF Attribute Services stack.

Version:

0.9, 03/24/08, 1.1, 08/11/09

Method Summary

IPrincipalIdentifier	doAdd(IAddInteraction ixn, IAttributeValue[] attrVals, java.lang.String[] roles, javax.security.auth.Subject user) A method to allow the caller to add a new identity as defined by the Interaction object ixn and perform the add in the context of the application user.
boolean	doCompare(ICompareInteraction ixn, IPrincipalIdentifier subjectKey, java.util.List<IAttributeValue> attrFilterVals, javax.security.auth.Subject user) A method allowing the client app to test if certain attribute condition values are matched using both the application and the end-user context.
void	doDelete(IDeleteInteraction ixn, IPrincipalIdentifier subjectKey, java.util.Map<java.lang.String,IPolicy> dynamicConstraintsMap, javax.security.auth.Subject user) A method allowing the client app to delete a subject using both the application and the end-user context.
IDigitalSubject	doFind(IFindInteraction ixn, java.util.List<IAttributeValue> attrFilterVals, java.util.Map<java.lang.String,IPolicy> dynamicConstraintsMap, javax.security.auth.Subject user) A method to authenticate the end-user of an application.
void	doModify(IModifyInteraction ixn, IPrincipalIdentifier subjectKey, IAttributeValue[] attrVals, java.lang.String[] roleVals, javax.security.auth.Subject user) A method allowing the client app to modify a subject based on a subject key and a set of AttributeValues described in the Interaction The request is performed under the specified user context.
IDigitalSubject	doRead(IReadInteraction ixn, javax.servlet.http.HttpServletRequest req, java.util.Map<java.lang.String,IPolicy> dynamicConstraintsMap, javax.security.auth.Subject user) A method allowing the client app to return a DigitalSubject based on a defined Interaction and based on information passed in HTTP Headers or assertions (e.g.
IDigitalSubject	doRead(IReadInteraction ixn, IPrincipalIdentifier subjectKey, java.util.Map<java.lang.String,IPolicy> dynamicConstraintsMap, javax.security.auth.Subject user) A method allowing the client app to return a DigitalSubject based on a defined Interaction and subjectKey index value using the Application's credential and the end-user credential.
IDigitalSubject	doRead(IReadInteraction ixn, java.util.Map<java.lang.String,IPolicy> dynamicConstraintsMap, javax.security.auth.Subject user) A method allowing the client app to return a DigitalSubject based on a defined Interaction and the identity of the application user.
IResultSet	doSearch(IInteraction ixn, java.util.List<IAttributeValue> attrFilterVals, java.util.Map<java.lang.String,IPolicy> dynamicConstraintsMap, javax.security.auth.Subject user) The search operation can be used for reporting purposes to locate a set of subjects that match a particular condition.
void	register(javax.security.auth.Subject appSecurityContext, ArisIdService attrSvc) register enables the client code to register its presence with the Attribute Services stack provider.
void	restart() Method called by ArisIdServiceFactory to initiate a warm restart.
void	shutdown() Method called typically by ArisIdServiceFactory to initiate a graceful shutdown.
void	startup() Startup is called by ArisIdServiceFactory after the first instantiation.
void	unregister(ArisIdService attrSvc) Allows an attribute service client to unregister as a result of ArisIdService.close() being called.

Method Detail

register

void register(javax.security.auth.Subject appSecurityContext,
              ArisIdService attrSvc)
              throws IGFException,
                     AuthenticationException,
                     NoSuchContextException,
                     NoSuchSubjectException,
                     SubjectNotUniqueException

register enables the client code to register its presence with the Attribute Services stack provider.

Parameters:

appSecurityContext - This is a security credential representing the security credential of the application. It will be applied to all operations with lower level providers. Not the xxxxAs operations allow the user context to also be passed in.

attrSvc - is a pointer back to the ArisIdService object. This allows the stack provider to callback to obtain items such as CARML and Interaction definitions.

Throws:

IGFException

AuthenticationException - is thrown when the security credential is not valid.

NoSuchContextException - is thrown when the subject cannot be mapped to an available context. This is usually suggestive of a configuration problem.

SubjectNotUniqueException - is thrown when the subject cannot be uniquely mapped to a single context or is not unique within a context.

NoSuchSubjectException

unregister

void unregister(ArisIdService attrSvc)

Allows an attribute service client to unregister as a result of ArisIdService.close() being called.

Parameters:

attrSvc - is a pointer back to the ArisIdService object. This allows the stack provider to callback to obtain items such as CARML and Interaction definitions.

doAdd

IPrincipalIdentifier doAdd(IAddInteraction ixn,
                           IAttributeValue[] attrVals,
                           java.lang.String[] roles,
                           javax.security.auth.Subject user)
                           throws ConnectionException,
                                  PolicyException,
                                  NoSuchContextException,
                                  NoSuchSubjectException,
                                  SubjectNotUniqueException,
                                  SchemaException,
                                  MappingException

A method to allow the caller to add a new identity as defined by the Interaction object ixn and perform the add in the context of the application user.

Parameters:

attrVals - An array of IAttributeValue objects representing the subject to be added. Note: Dynamic policy constraints may also be included as part of specific IAttributeValue values.

roles - An array of Strings representing the roles to be asserted for the subject to be added.

user - is the Subject representing the user interacting with the application or null if the transaction is to be done using the application credential context alone.

Returns:

an PrincipalIdentifier representing the subject added.

Throws:

ConnectionException - is thrown when a network or other connection problem has occurred causing the transaction to fail.

PolicyException - is thrown when the the transaction has failed due to policy or consent failure.

NoSuchContextException - is thrown when the subject cannot be mapped to an available context. This is usually suggestive of a configuration problem.

NoSuchSubjectException - is thrown when the user cannot be mapped within a context to perform the operation.

SubjectNotUniqueException - is thrown when the subject cannot be uniquely mapped to a single context or is not unique within a context.

SchemaException - is thrown when an attribute is not successfully matched to a context. This can be due to a missing attribute or a non-compatible syntax error.

MappingException - is thrown when an error has occurred in mapping a value to a particular schema. In this case, the schema was valid, but the value was either invalid or not mappable.

doFind

IDigitalSubject doFind(IFindInteraction ixn,
                       java.util.List<IAttributeValue> attrFilterVals,
                       java.util.Map<java.lang.String,IPolicy> dynamicConstraintsMap,
                       javax.security.auth.Subject user)
                       throws ConnectionException,
                              PolicyException,
                              NoSuchContextException,
                              NoSuchSubjectException,
                              SubjectNotUniqueException,
                              SchemaException,
                              MappingException

A method to authenticate the end-user of an application. E.g. JAAS can call this method through the AttributeServiceLoginHandler class.

Parameters:

attrFilterVals - An array of IAttributeValue objects that specify the comparison values for any AttrFilter objects contained in the declared filter for the transaction. The number of values specified must correspond exactly to the number specified in the declared filter. Use Filter.getCompareAttrValues() to obtain the values that need to be set.

dynamicConstraintsMap - A map containing a set of dynamic constraints relevant to the transaction. The map index is either an attribute, predicate, or role name, or interaction name (to define policy at the interaction level). This parameter is used for things like specifying a localization constraint on an attribute.

user - is the end-user context that the transaction is to be performed under or null if the transaction is to be done using the application credential context alone.

Returns:

String containing the mapped credential key. currentCred may also be updated.

Throws:

ConnectionException - is thrown when a network or other connection problem has occurred causing the transaction to fail.

PolicyException - is thrown when the the transaction has failed due to policy or consent failure.

NoSuchContextException - is thrown when the subject cannot be mapped to an available context. This is usually suggestive of a configuration problem.

NoSuchSubjectException - is thrown when the user cannot be mapped within a context to perform the operation.

SubjectNotUniqueException - is thrown when the subject cannot be uniquely mapped to a single context or is not unique within a context.

SchemaException - is thrown when a filter or role cannot be matched or used appropriately.

MappingException - is thrown when an error has occurred in mapping a filter or role to an appropriate search filter.

doCompare

boolean doCompare(ICompareInteraction ixn,
                  IPrincipalIdentifier subjectKey,
                  java.util.List<IAttributeValue> attrFilterVals,
                  javax.security.auth.Subject user)
                  throws ConnectionException,
                         PolicyException,
                         NoSuchContextException,
                         NoSuchSubjectException,
                         SubjectNotUniqueException,
                         SchemaException,
                         MappingException

A method allowing the client app to test if certain attribute condition values are matched using both the application and the end-user context.

Parameters:

subjectKey - A subject key representing the unique key for the user to be compared.

attrFilterVals - An array of IAttributeValue or IFilterValue objects that specify the comparison values for any AttrFilter objects contained in the declared filter for the transaction. The number of values specified must correspond exactly to the number specified in the declared filter. Use Filter.getCompareAttrValues() to obtain the values that need to be set. Note: Dynamic policy constraints may also be included as part of specific IAttributeValue or IFilterValue values.

user - is the end-user context that the transaction is to be performed under or null if the transaction is to be done using the application credential context alone.

Returns:

boolean representing whether a complete match was achieved or not

Throws:

ConnectionException - is thrown when a network or other connection problem has occurred causing the transaction to fail.

PolicyException - is thrown when the the transaction has failed due to policy or consent failure.

NoSuchContextException - is thrown when the subject cannot be mapped to an available context. This is usually suggestive of a configuration problem.

NoSuchSubjectException - is thrown when the user cannot be mapped within a context to perform the operation.

SubjectNotUniqueException - is thrown when the subject or user cannot be uniquely mapped to a single context or is not unique within a context.

SchemaException - is thrown when an attribute is not successfully matched to a context. This can be due to a missing attribute or a non-compatible syntax error.

MappingException - is thrown when an error has occurred in mapping a value to a particular schema. In this case, the schema was valid, but the value was either invalid or not mappable.

doDelete

void doDelete(IDeleteInteraction ixn,
              IPrincipalIdentifier subjectKey,
              java.util.Map<java.lang.String,IPolicy> dynamicConstraintsMap,
              javax.security.auth.Subject user)
              throws ConnectionException,
                     PolicyException,
                     NoSuchContextException,
                     NoSuchSubjectException,
                     SubjectNotUniqueException

A method allowing the client app to delete a subject using both the application and the end-user context.

Parameters:

subjectKey - A subject key representing the unique key for the user to be deleted.

dynamicConstraintsMap - A map containing a set of dynamic constraints relevant to the transaction. The map index is either an attribute, predicate, or role name, or interaction name (to define policy at the interaction level). This parameter is used for things like specifying a localization constraint on an attribute.

user - is the end-user context that the transaction is to be performed under or null if the transaction is to be done using the application credential context alone.

Throws:

ConnectionException - is thrown when a network or other connection problem has occurred causing the transaction to fail.

PolicyException - is thrown when the the transaction has failed due to policy or consent failure.

NoSuchContextException - is thrown when the subject cannot be mapped to an available context. This is usually suggestive of a configuration problem.

NoSuchSubjectException - is thrown when the user cannot be mapped within a context to perform the operation.

SubjectNotUniqueException - is thrown when the subject or user cannot be uniquely mapped to a single context or is not unique within a context.

doRead

IDigitalSubject doRead(IReadInteraction ixn,
                       java.util.Map<java.lang.String,IPolicy> dynamicConstraintsMap,
                       javax.security.auth.Subject user)
                       throws ConnectionException,
                              PolicyException,
                              NoSuchContextException,
                              NoSuchSubjectException,
                              SubjectNotUniqueException,
                              SchemaException,
                              MappingException

A method allowing the client app to return a DigitalSubject based on a defined Interaction and the identity of the application user.

Parameters:

dynamicConstraintsMap - A map containing a set of dynamic constraints relevant to the transaction. The map index is either an attribute, predicate, or role name, or interaction name (to define policy at the interaction level). This parameter is used for things like specifying a localization constraint on an attribute.

user - is the end-user credential and the user about information is to be retrieved.

Returns:

DigitalSubject the identity information requested in the Interaction object.

Throws:

ConnectionException - is thrown when a network or other connection problem has occurred causing the transaction to fail.

PolicyException - is thrown when the the transaction has failed due to policy or consent failure.

NoSuchContextException - is thrown when the subject cannot be mapped to an available context. This is usually suggestive of a configuration problem.

NoSuchSubjectException - is thrown when the user cannot be mapped within a context to perform the operation.

SubjectNotUniqueException - is thrown when the subject or user cannot be uniquely mapped to a single context or is not unique within a context.

SchemaException - is thrown when an attribute is not successfully matched to a context. This can be due to a missing attribute or a non-compatible syntax error.

MappingException - is thrown when an error has occurred in mapping a value to a particular schema. In this case, the schema was valid, but the value was either invalid or not mappable.

doRead

IDigitalSubject doRead(IReadInteraction ixn,
                       IPrincipalIdentifier subjectKey,
                       java.util.Map<java.lang.String,IPolicy> dynamicConstraintsMap,
                       javax.security.auth.Subject user)
                       throws ConnectionException,
                              PolicyException,
                              NoSuchContextException,
                              NoSuchSubjectException,
                              SubjectNotUniqueException,
                              SchemaException,
                              MappingException

A method allowing the client app to return a DigitalSubject based on a defined Interaction and subjectKey index value using the Application's credential and the end-user credential.

Parameters:

subjectKey - is the subject key index value for the DigialIdentity to be returned.

dynamicConstraintsMap - A map containing a set of dynamic constraints relevant to the transaction. The map index is either an attribute, predicate, or role name, or interaction name (to define policy at the interaction level). This parameter is used for things like specifying a localization constraint on an attribute.

user - is the end-user credential context to be used for performing the query or null if the transaction is to be done using the application credential context alone.

Returns:

DigitalSubject the identity information requested in the Interaction object.

Throws:

ConnectionException - is thrown when a network or other connection problem has occurred causing the transaction to fail.

PolicyException - is thrown when the the transaction has failed due to policy or consent failure.

NoSuchContextException - is thrown when the subject cannot be mapped to an available context. This is usually suggestive of a configuration problem.

NoSuchSubjectException - is thrown when the user cannot be mapped within a context to perform the operation.

SubjectNotUniqueException - is thrown when the subject or user cannot be uniquely mapped to a single context or is not unique within a context.

SchemaException - is thrown when an attribute is not successfully matched to a context. This can be due to a missing attribute or a non-compatible syntax error.

MappingException - is thrown when an error has occurred in mapping a value to a particular schema. In this case, the schema was valid, but the value was either invalid or not mappable.

doRead

IDigitalSubject doRead(IReadInteraction ixn,
                       javax.servlet.http.HttpServletRequest req,
                       java.util.Map<java.lang.String,IPolicy> dynamicConstraintsMap,
                       javax.security.auth.Subject user)
                       throws ConnectionException,
                              PolicyException,
                              NoSuchContextException,
                              NoSuchSubjectException,
                              SubjectNotUniqueException,
                              SchemaException,
                              MappingException

A method allowing the client app to return a DigitalSubject based on a defined Interaction and based on information passed in HTTP Headers or assertions (e.g. SAML). The request is performed under the specified user context even though the request object is searched for the targeted search user.

Parameters:

req - is the ServletRequest object passed to the application servlet. The req object will be parsed for user subject information as well as assertions present request.

dynamicConstraintsMap - A map containing a set of dynamic constraints relevant to the transaction. The map index is either an attribute, predicate, or role name, or interaction name (to define policy at the interaction level). This parameter is used for things like specifying a localization constraint on an attribute.

user - is the end-user credential context to be used for performing the query or null if the transaction is to be done using the application credential context alone.

Returns:

DigitalSubject the identity information requested in the Interaction object.

Throws:

ConnectionException - is thrown when a network or other connection problem has occurred causing the transaction to fail.

PolicyException - is thrown when the the transaction has failed due to policy or consent failure.

NoSuchContextException - is thrown when the subject cannot be mapped to an available context. This is usually suggestive of a configuration problem.

NoSuchSubjectException - is thrown when the user cannot be mapped within a context to perform the operation.

SubjectNotUniqueException - is thrown when the subject or user cannot be uniquely mapped to a single context or is not unique within a context.

SchemaException - is thrown when an attribute is not successfully matched to a context. This can be due to a missing attribute or a non-compatible syntax error.

MappingException - is thrown when an error has occurred in mapping a value to a particular schema. In this case, the schema was valid, but the value was either invalid or not mappable.

doSearch

IResultSet doSearch(IInteraction ixn,
                    java.util.List<IAttributeValue> attrFilterVals,
                    java.util.Map<java.lang.String,IPolicy> dynamicConstraintsMap,
                    javax.security.auth.Subject user)
                    throws ConnectionException,
                           PolicyException,
                           NoSuchContextException,
                           NoSuchSubjectException,
                           SubjectNotUniqueException,
                           SchemaException,
                           MappingException

The search operation can be used for reporting purposes to locate a set of subjects that match a particular condition. The result set returns a List of SubjectKeys that match the filter and role conditions specified. Note that if reporting is desired, the caller may then issue doRead requests to pull back attributes, predicates, and roles of particular subjects returned from this method.

Parameters:

ixn -

attrFilterVals - An array of IAttributeValue or IFilterValue objects that specify the comparison values for any AttrFilter objects contained in the declared filter for the transaction. The number of values specified must correspond exactly to the number specified in the declared filter. Use Filter.getCompareAttrValues() to obtain the values that need to be set.

dynamicConstraintsMap - A map containing a set of dynamic constraints relevant to the transaction. The map index is either an attribute, predicate, or role name, or interaction name (to define policy at the interaction level). This parameter is used for things like specifying a localization constraint on an attribute.

user -

Returns:

A List of subjectKeys of entries that match the search conditions.

Throws:

ConnectionException - is thrown when a network or other connection problem has occurred causing the transaction to fail.

PolicyException - is thrown when the the transaction has failed due to policy or consent failure.

NoSuchContextException - is thrown when the subject cannot be mapped to an available context. This is usually suggestive of a configuration problem.

NoSuchSubjectException - is thrown when the user cannot be mapped within a context to perform the operation.

SubjectNotUniqueException - is thrown when the subject or user cannot be uniquely mapped to a single context or is not unique within a context.

SchemaException - is thrown when a filter or role cannot be matched or used appropriately.

MappingException - is thrown when an error has occurred in mapping a filter or role to an appropriate search filter.

doModify

void doModify(IModifyInteraction ixn,
              IPrincipalIdentifier subjectKey,
              IAttributeValue[] attrVals,
              java.lang.String[] roleVals,
              javax.security.auth.Subject user)
              throws ConnectionException,
                     PolicyException,
                     NoSuchContextException,
                     NoSuchSubjectException,
                     SubjectNotUniqueException,
                     SchemaException,
                     MappingException

A method allowing the client app to modify a subject based on a subject key and a set of AttributeValues described in the Interaction The request is performed under the specified user context.

Parameters:

subjectKey - is the unique subject key for the subject to be modified.

attrVals - is the modified IAttributeValue that replace the existing values. Note: Dynamic policy constraints may also be included as part of specific IAttributeValue values.

roleVals - is a string array representing the roles (of the declared roles) to be set. If a declared role is not present in the roleVals parameter, it is treated as a clear or delete of the role. A null value indicates no changes are to be made. An empty array indicates all declared values are to be cleared.

user - is the end-user credential context to be used for performing the query or null if the transaction is to be done using the application credential context alone.

Throws:

ConnectionException - is thrown when a network or other connection problem has occurred causing the transaction to fail.

PolicyException - is thrown when the the transaction has failed due to policy or consent failure.

NoSuchContextException - is thrown when the subject cannot be mapped to an available context. This is usually suggestive of a configuration problem.

NoSuchSubjectException - is thrown when the user cannot be mapped within a context to perform the operation.

SubjectNotUniqueException - is thrown when the subject or user cannot be uniquely mapped to a single context or is not unique within a context.

SchemaException - is thrown when an attribute is not successfully matched to a context. This can be due to a missing attribute or a non-compatible syntax error.

MappingException - is thrown when an error has occurred in mapping a value to a particular schema. In this case, the schema was valid, but the value was either invalid or not mappable.

startup

void startup()
             throws IGFException

Startup is called by ArisIdServiceFactory after the first instantiation.

Throws:

IGFException

shutdown

void shutdown()
              throws IGFException

Method called typically by ArisIdServiceFactory to initiate a graceful shutdown.

Throws:

IGFException

restart

void restart()
             throws IGFException

Method called by ArisIdServiceFactory to initiate a warm restart. This method should be a privileged operation.

Throws:

IGFException