Security API refactoring

Introduction

One of the area that received the largest amount of requests for improvement is the security area. Please see RFE #505 and all dependent issue for details. In Restlet 2.0, we want to address those concerns by attempting to refactor and enhance the Restlet API.

Requirements

High priority enhancements (Restlet 2.0)

Low priority enhancements (Restlet 2.1 and later)

Related discussions

Related references

Analysis

Requirements synthesis

  1. Proper separation between Identification, Authentication, Authorization and Accounting (see article)
  2. Support pluggability with third-party security libraries (jGuard, JSecurity and Spring Security)
  3. All security aspects should be configurable programmatically via the Restlet API
  4. Aspects likely to be changed by administrators should be configurable via XML
  5. Support several grades of authentication that could impact the authorization policy
  6. Support compound authentication in order to increase the grade of the authentication
  7. Support several authentication alternatives to cope with various client types

Features

  1. Multiple Realms can be defined for a single Component instance
  2. A single Realm can be bound to an Application instance
  3. The MemoryRealm offers a default security model, where a Realm is composed of several Organizations
  4. To differentiate users of several application, the 'userIdentifier@organizationDomainName' pattern is used for user identifiers
  5. Hierarchical groups can define sets of users (optionally inheriting roles)
  6. The mapping between Organizations/Groups/Users and Application-level Roles/Permissions is isolated by the Enroler class and exposed to the Application via the Context class, ensuring a complete isolation from their parent Component
  7. Hierarchical roles are supported (optionally inheriting permissions)
  8. JAAS Subject (see "Request.clientInfo.subject" property) aggregates all the security information related to an authenticated Restlet User like its principals (ex: roles) and its credentials (ex: keys)

Design

Introduction

The design of this new security API will have to respect several constraints:

  • Respect Restlet containment model : a Component contains several Applications that are, by default, fully isolated from each others. There can potentially be several Components inside a single JVM, therefore we shouldn't rely on static methods.
  • In order to facilitate Applications portability and reusability in various security contexts, the authentication aspect should be based on fully pluggable credentials verifiers. Applications should however be in control of the authorization aspects, by defining the available application roles. The mapping between authenticated users and their granted or denied roles in Applications should be defined outside the Application to keep it reusable.
  • Plug naturally into Restlet processing chain, both on the server-side and on the client-side (see updated resource API).
  • Keep the authentication and authorization aspects isolated as much as possible as they could be provided in different ways, by different sources.
  • Offer a pluggable and extensible API to integrate with all common security solutions.
  • Provide a solid default security mechanism implementing this new security API. Its usage should be optional.
  • Authentication and Authorization features should be usable either as Filters or as regular helper classes.

To do list

  • Allow the retrieval of users/groups mapped to a given Role
  • Refactor and test HttpDigestAuthenticator
  • Refactor and test JaasVerifier
  • Test the usage of a SecurityManager with a JAAS-based policy file
  • Test the default Restlet security model on a hierarchy of directories
  • Support the "salt" and "iterationNumber" properties on DigestVerifier
  • Review changes necessary to the Component XSD and write XML persistence logic
  • How to associate certificates or other credentials to a User represented in the default Restlet security model (ex: User's property retrieved by LDAP?)
  • Write unit tests

Overall architecture

Here is the overall architecture:

Security architecture
Click to enlarge

Processing flow

Now let's look at the proposed Restlet handling flow. Note that both Authenticator and Authorizer are Filter subclasses. That means that they can be used together or separately.

Restlet flow
Click to enlarge

For example, it is possible to use an Authenticator at the root of your application to ensure that all requests going through are properly authenticated.Then, you could attach different Authorizer instances at different routing point to implement various authorization policies based on target resources protected.

Implementation

Authentication model

Here is a class diagram that summarizes the main security classes and their derivation hierarchy:

Security design

Now here is the verifier mechanism. It is generally independent of the authentication scheme.

Security verifiers

Authorization model

Here are the classes the define the authorization model:

Authorization

Now more details on the Realm class that provides the Verifier and Enroler to an Application via its Context:

Realms

Now more details on the default memory realm:

Memory realm

Javadocs

See the Javadocs of the new org.restlet.security package.

Comments (0)