ArisID API

From OpenLiberty.org Wiki
Jump to: navigation, search

Contents

ArisID API

Revised: October 10, 2008


Introduction

The ArisID API (formerely IGF Attribute Services API) is a set of library functions combined with providers (e.g. Higgins IdAS) which may be used to retrieve Identity Subjects (DigitalSubject) that contain collections of attributes. The API can be initialized by consuming a CARML file or by defining schema and interactions in code (aka Dynamic definition).

The current primary implementation is based in Java, but implementations are expected in other languages depending on contributions received from the community.

API Description

ArisID supports the use of “subjects” defined by authentication and policy systems (JAAS, webgates, or other Application Server security components) and allows applications to obtain more information about subjects using a transactional style interface. That is to say, the ArisID API focuses on declared attributes and transactions that can be performed using those attributes.

Another related API is the ArisID Beans API. In this version of ArisID, the API follows a Java bean pattern by using a CARML declaration to generate Java beans that call the ArisID API. An ArisID Bean represents a particular subject where various bean methods can be called to perform actions against that subject. Along with the Java bean representation of subject are Manager classes that enable life-cycle management of subjects represented by the Java beans.

The ArisID API allows applications to modify identity attributes as well as retrieve them. By using the API, developers do not need to be concerned about how or where information is stored. Instead, identity information is handled by a set of services and policies that can be configured at run time, external to the application logic. Rather than being restricted to a specific and non-flexible information model design at development time, applications written this way will enjoy dramatic flexibility and configurability - decreasing application deployment costs, while increasing privacy and identity services support by the application.

ArisID is able to de-couple applications from infrastructure requirements because it abstracts the nature of specific systems and protocols so that the developer can have a consistent model for representing data from these systems and have a simple interface for obtaining and updating identity-related data.

Aris-Generic.jpg

The combination of the ArisID API and a Provider is defined as an Identity Services Stack.

The current Java implementation of ArisID is intended to be used by J2EE applications (other implementations and bindings expected to follow). When using the API, an identity services stack implementing the IGF Attribute Svcs Interface (to be published shortly) will service the application. The stack provider can take the generated CARML declaration and/or use the Java Interaction objects passed to it for dynamic support of IGF.

Major Components

The ArisID API consists of 3 main java packages: AttributeService, Schema, and Stack.

Attribute Service Package

This package contains the AttributeServicesFactory which is used to instantiate an AttributeService instance. The factory methods allow the developer to provide a pre-defined CARML file or allow the developer to complete the CARML declaration programmatically. When an AttributeService is created, it is instantiated in connection with a provider that implements the IAttrSvcStack interface. This provider can be specifically defined or defaulted using a Java system property.

The AttributeService represents a handle to the attribute service. Initialized with the location of the attribute service and a set of Interactions, it enables DigitalSubjects to be retrieved from the service.

Depending on how the CARML declared, the AttributeService provides access to the schema definitions through the SchemaManager (see below), and to defined Interactions.

An Interaction is an object that defines one interaction or transaction type of an application’s identity attribute requirements. In XML terms, it is a representation of a single interaction in the CARML xml specification. An Interaction has a type associated with it that must be one of: add, authenticate, delete, modify, read, or search.

Schema Package

The schema package defines a java object model that represents the defined schema within a particular CARML declaration. Within the schema package are objects such as AttributeDef, FilterDef, PredicateDef, and RoleDef. Each of these objects defines a particular type of schema within a CARML definition.

Stack Package

The stack package is used by the AttributeService API to communicate with providers implementing the IAttrSvcsStack Interface.

Schema Package Objects

Click to enlarge

SchemaManager

The SchemaManager is used to manipulate and query schema associated with a CARML declaration. Note: if the AttributeService has been initialized, the SchemaManager will throw an exception if any changes to schema are attempted.

AttributeDef

Defines an attribute and its policy, schema, and usability. This object is typically used for defining attributes in an Interaction. Each object defines a name, a schema, and other items, such as caching requirements, propagation permissions, that an application would like to request. Note that while these are requested items it may be conceivable that an attribute service may not be able to provide all attributes and their usage requirements in all cases. In other words, an attribute service my have to limit results based on an individual user consent rule that may provide limits on a subject by subject basis.

AttributeRef

An AttributeRef is used by an Interaction to reference an AttributeDef object defined in schema. Additionally, the AttributeRef also allows a PolicyDef object to be referenced to associate a specific policy with the use of a particular attribute defined in schema for a particular Interaction.

FilterDef

A FilterDef defines a filter that can be used to select a particular subject or set of objects.

PredicateDef

A PredicateDef defines a predicate used to test a boolean condition. Examples: IsAdult, IsBusinessClassFlyer, IsRetired. This object is typically used for defining predicates defined within the SchemaManager. The Interaction object will also reference predicate objects that are used by the Interaction. A predicate(aka property) is similar to an Attribute except that its returned value is true or false (a predicate). Each property defines a name, a schema, and other items, such as caching requirements, propagation permissions, that an application would like to request. Note that while these are requested items it may be conceivable that an attribute service may not be able to provide all attributes and their usage requirements in all cases. In other words, an attribute service my have to limit results based on an individual user consent rule that may provide limits on a subject by subject basis.

PredicateRef

An PredicateRef is used by an Interaction to reference an PredicateDef object defined in schema. Additionally, the PredicateRef also allows a PolicyDef object to be referenced to associate a specific policy with the use of a particular attribute defined in schema for a particular Interaction.

PolicyDef

A PolicyDef' object holds a set of WS-Policy assertions that can be used to set policy for the use of an attribute, predicate, role, etc.

RoleDef

A role is a value that defines a right that one or more subjects may possess. A role is locally meaningful to an application, and like a predicate must be interpreted by an attribute authority. As with predicate, the use of descriptive text and DataType URIs will be used by attribute authorities to determine how to map and interpret roles. Roles also differ from predicates in that they are handled as values rather than specific test. E.g. subject.getRoles() returns the roles the user possesses.

RoleRef

An RoleRef is used by an Interaction to reference an RoleDef object defined in schema. Additionally, the RoleRef also allows a PolicyDef object to be referenced to associate a specific policy with the use of a particular attribute defined in schema for a particular Interaction.

Attribute Service Package Objects

Click to enlarge

AttributeServiceFactory

The AttributeServiceFactory is responsible for creating and managing instances of AttributeService objects. Each AttributeService object is associated with a single CARML declaration and a single Attribute Services Stack Provider (IAttrSvcStack). Each AttributeService instance created by the factory represents a single CARML declaration (containing 1 or more Interaction objects used to read and modify data. An AttributeService has associated with it a class that implements the services used by the defined Interactions. While there may be multiple AttributeService objects with differing CARML declarations, the factory will work to ensure that there is only once instance of each IAttrSvcStack stack in the JVM.

AttributeService

Defines an identity attribute service handle. Typically as part of the constructor/initialization, both the attribute service URL is provided along with a set of Interactions. During this exchange, the attribute service will inform the client what the preferred AttributeService service providers are and their alternates. The API will use this to configure future requests and enable fault-tolerance. Optionally, the attribute service URL provided by the client might not be the actual service URL that the client will use. Instead, it may simply be a rendezvous or registration service that allows a client to initially connect and locate its true service provider.

The AttributeService provides the key methods that enable DigitalSubjects to be retrieved such as getIdentity(some key). The intent is to have an intelligent retrieval mechanism that either parses the current httprequest for an authentication token (e.g. SAML assertion) or other header value such as getIdentity(HttpRequest req). If an application policy service is present (e.g. a web gate), it may also provide a header variable that can be used as the unique lookup key by the attribute service. In the event that an application has no unique key but rather a combination of attribute values, an application could request a DigitalIdentity based on a set of attribute assertions, e.g. getIdentity(AttribueValue[]), to retrieve a DigitalSubject. E.g. uid, or mail, or employeeid. A use case, might be looking up an identity based on 2 or 3 assertions (such as mail, pass phrase answer, date of birth) to facilitate user id or password recovery where the user has forgotten their user identity if not already handled by a security or idm service.

Interaction

An Interaction defines a single transaction used by a client application with the identity service. A set of Interaction objects embodie a client's CARML specification. The set may be used to generate a CARML xml file using the toCARML() method of AttributeService. It may also be used during service connection establishment to define attributes to be processed when handling DigitalSubjects. The Interaction object can be initialized using a CARML xml document, or can be defined by adding defined using the AttributeService factory methods. This object embodies the preferred schema that a client application needs from an identity attribute service.

An Interaction has a declared type that must be one of:

  • Add (to Add a new subject)
  • Authenticate (to locate or return a single IPrincipalIdentifier based on one or more Filters)
  • Delete (to Delete a subject)
  • Modify (to Modify attributes or roles of a subject)
  • Read (to read attributes, predicaes, and/or roles of a subject)
  • Search (to locate one or more IPrincipalIdentifiers based on one or more Filters or Role values)

DigitalSubject

This object embodies an identity. It has a set of AttributeValue objects (internally based on SAML assertions) that together define the digital subject. Properties specified in the parent Interaction can be tested using isPropertyMatched(name) method. In addition to allowing applications to read attribute values, the DigitalSubject can also be used to enable modification. Modification is done through a simple method setAttributeValue(name,value). This method is processed immediately against the server to ensure all requests are atomic. [Note: we want to avoid any option that would cause need for a rollback or other complex recovery].

DigitalSubject objects can be constructed with a set of AttributeValue objects and/or a SAML assertion. Note: Should we allow values to be set only via a constructor?

AttributeValue

An attribute value holds a set of values of an attribute for a particular DigitalSubject. It may contain policy restrictions which may provide further restrictions that those originally requested in CARML. For example, even though a client app may have requested rights to propagate, the supplier may have refused or may have had an issue with consent from a particular subject. The AttributeValue object may be empty – containing an error code from the attribute service. E.g. request refused. This allows the service to deliver partial results.

Example java code:

...

File carmlFile = new File("carml.xml");

try {
	_asvc = AttributeServiceFactory.createAttributeService(_appCred,
		carmlFile.toURI());
} catch (Exception e) {
	fail("Failed to parse copied XML file: " + e.getMessage());
	return;
}
		
IReadInteraction _readUserop;
// Locate the _readUserOp "ReadUser" that was declared in the CARML declaration file	
try {
	_readUserOp = (IReadInteraction) _asvc.getInteraction("ReadUser");
} catch (Exception e) {
	e.printStackTrace();
	fail("A transaction was missing or not parsed." + e.getMessage());
	return;
}

// retrieve the Principal identified within the ServletRequest request object
try {
	DigitalSubject subj = _readUserOp.doGetByRequest(request, null);

	if (subj == null)
		fail("Subject read failed");

	AttributeValue val = subj.getAttributeValue(_first.getNameId());

	if (val.isError()) {
		fail("Exception reading value: " + val.getError().getMessage());
		return;
	}

	if (val.size() == 0) {
		fail("No values retured");
		return;
	}

	// Retrieve the first value
	String firstname = val.get(0);
	System.out.println("First name is: "+firstname);

} catch (IGFException e) {
	e.printStackTrace();
	fail("IGF Exception on read: " + e.getMessage());
	return;
}
...

FilterValue

FilterValue is used to hold values returned from an attribute authority. An FilterValue usually represents one returned attribute in a DigitalSubject. All String values are UTF-8 encoded. The FilterValue will also hold IGF meta response data for an attribute.

PredicateValue

PredicateValue is used to hold value returned from an attribute authority for a particular property. An PredicateValue usually represents one returned property in a DigitalSubject. The PredicateValue will also hold IGF meta response data for a property.

PrincipalIdentifier

An extension of java.security.Principal, this class can be used to interrogate principal identifiers for information on how the Principal is mapped to one or more contexts in the IAttrSvcStack. This class is also used for pointing to logical user records for add,delete,modify, and read operations. Note: application developers should reference this object directly. Instead, applications should use either of the interaces IMultiContextIdentifier or IPrincipalIdentifier.

Stack Package Objects

Click to enlarge

IAttrSvcStack

IAttrSvcStack is a java interface used by implementors to provide services to an IGF-enabled attribute services client via the AttributeServices API.

IPrincipalIdentifier

Used to hold a unique identifier that can represent a principal in an IGF enabled Attribute Service. The identifier is not necessarily universal and may only be relevant for a particular Attribute Service Stack context. For reporting purposes only, IPrincipalIdentifier can be used to retrieve information about whether the principal is mapped to one or more context providers (an entity that has attributes in multiple contexts).

IMultiContextIdentifier

Used to hold a unique identifier that can represent a principal in an IGF enabled Attribute Service. IMutiContextIdentifier holds information on contexts that this principal may be related to. The identifier is not necessarily universal and may only be relevant for a particular Attribute Service Stack context. For reporting purposes only, IMultiContextIdentifier can be used to retrieve information about whether the principal is mapped to one or more context providers (an entity that has attributes in multiple contexts). IMultiContextIdentifier may be used by IAttrSvcStack implementors to track and maintain relationships for DigitalSubjects that are made of more than one context or attribute authority.

Operations

Initialization Sequence

When the web server initializes, the servlet, jsp, etc will activate the CARML Client API and initiate a connection to an attribute service provider. In establishing this connection, the client api supplies an application credential and its CARML requirements to AttributeService “A” (shown below). After determining that “Attribute Service B” is more appropriate, Attribute Service A issues a re-direct to service B. The CarmlClient repeats the initialization process with Attribute Service B and initialization is completed if no more re-directs or errors returned.

Client Initialization Sequence

When a user-request is received by the web server, the server will authenticate the user as it normally would (e.g. could be via a web policy server). In the web application code, the application looks up the authenticated user by issuing a getIdentity() request using the request headers, or other lookup key. The CarmlClient api then issues the request to the service provider which responds with the DigitalSubject located (or a subject containing an error). The web application may then retrieve subject values by calling getValue on the DigitalSubject returned.


Error Handling

There are several types of error conditions that might arise while processing client requests that might involve, privilege errors, consent errors, invalid subjects, or missing or undefined data. The following outlines how these conditions may be handled in a CARML API using exception conditions.

Example with Exception Handling:

...
IReadInteraction _readOp = ashandle.getInteraction("ReadUser");

/* Fetch the user by passing the current http request headers 
 * Allow api to locate authentication token/assertion for lookup
 */
DigitalSubject user = null;

try {
    user = _readOp.doGetByRequest(request);
} catch (ConsentException ce) {
    System.err.println("Entry could not be returned. Consent not given");
    return;
} catch (SubjectNotFoundException snf) {
    System.err.println("Entry could not be located, mapped, or is otherwise invalid");
    return;	
} catch (InvalidCredentialsException ice) {
    System.err.println("Credentials not valid for the requested operation.");
    return;
} catch (RightsException re) {
    System.err.println("The operation requested is not authorized for the current credentials");
    return;
}

AttributeValue cn = null;
try {
    cn = user.getValue("cn");
} catch (ValueUndefinedException vundef) {
    // Non-fatal exception
    System.err.println("Value was either missing or not supported by service provider");
    return;
} catch (ConsentException ce) {
    // Non-fatal exception
    System.err.println("Value could not be returned due to invalid consent");
} catch (RightsException re) {
    System.err.println("The operation requested is not authorized for the current credentials");
    return;
}

Partial list of exceptions

ConsentException

Exception thrown when a consent error prevents return of either a DigitalSubject or AttributeValue.

InvalidSubjectException

The subject index values supplied could not be mapped to a valid entry in the identity service. This means the identity service has no way to resolve this subject whether it is existing or new.

InvalidCredentialsException

Either the web application client credentials and/or the web user credential is not valid for the specified operation. This is usually caused by AAPML policy denying the operation.

RightsException

The operation requested is not permitted. This is usually caused by an AAPML policy decision. E.g. user attempting to modify a record they are not authorized to update.

ValueUndefinedException

No value or default value was located for the attribute requested.

InvalidEncodingException

The value(s) supplied do not conform to the format specified in the CARML specification.

Project Index

Project Aristotle

Downloads

ArisID

ArisID Providers


Related External Information

Other

OpenAz