Getting Started - Basic Concepts

Introduction

This section describes some basic concepts used by PicketBox. They are the key to better understand and use PicketBox and its features.

The UserContext

This class represents the source of a request (eg.: an user and his related information such credentials, etc ) and also the security context for an authenticated user with all security related information.

PicketBox defines that users can hold two states, basically:

Unauthenticated
At this state the UserContext acts like a AUTHENTICATING security context, holding specific information that will be used to authenticate an user, such as credentials, etc.

Authenticated
At this state the UserContext represents an AUTHENTICATED user holding all his security related information such as roles, groups, attributes, etc.

After the authentication have being done and the user is successfully authenticated, applications are able use the UserContext to check for roles, groups or any other information stored in the security context. images/author/download/attachments/53379497/pb_user_context_class.png

The class representing an user is org.picketbox.core.UserContext.

The PicketBox Manager

All security operations are centralized and managed by the PicketBox Manager. The manager acts like a Facade for your security layer providing all the necessary functionality to get your users authenticated and authorized. Its main role is coordinate how the different managers (Eg.: authentication, authorization, identity management, session) are used to get your application secure.

PicketBox provides some built-in implementations for the manager, a default implementation that can be used by any Java application and others for some specific environment, like the one provided by the PicketBox HTTP extension.

To create a PicketBoxManager instance you only need to provide a configuration by using the Configuration API. Simple as that.

The interface representing the PicketBox Manager is the org.picketbox.core.PicketBoxManager.

Authentication

User Credential

In order to authenticate an user you should provide his credentials.

Each credential type dictates how the user should be authenticated, in other words, which is the Authentication Mechanism that knows how to validate that type of credential. Credentials type can be username/password, digest, certificate, security tokens, etc.

The credentials are populated into the authenticating UserContext before starting the authentication process.

Authentication Mechanisms

Each application has its own requirements about how users should be authenticated. Authentication Mechanisms define how the users credentials are validated using a specific mechanism like username/password, digest, certificates or some specific security token.

Each mechanism knows how to process a specific credential type and how this credential should be validated using the Identity Manager, from which the user information will be retrieved.

PicketBox already provides some built-in mechanisms that can be used in most cases. But you can always provide your own implementations.

For more information, check the Authentication Mechanism documentation.

Identity Management, Identity Stores and User's Roles, Groups and Attributes

User information is usually stored at some specific repository like databases, LDAP servers, etc. These repositories are called Identity Stores.

Identity Stores are managed by the Identity Manager which acts like a Facade for user account (de)provisioning, account management, credentials management, query support, etc.

Usually, when you authenticate an user you need to retrieve some additional information like roles, groups, attributes or any personal information to use during his interaction with your application. For that, PicketBox provides an Identity Manager component that is responsible to populate the authenticated user with those information during the authentication process.

PicketBox is fully integrated with the PicketLink Identity Management project, which provides all necessary functionality to manage your users and their information.

For more information, check the Identity Management documentation.

Authorization Managers

Usually, your application needs to authorize your users before accessing some specific/protected resource. The authorization is done by looking at the user security context (populated with roles, groups, attributes, etc) and the resource that is being requested.

The authorization is based on the following rule: IS [subject] WITH [security context] ALLOWED TO ACCESS RESOURCE [resource].

PicketBox provides some built-in implementations like the Drools Authorization Manager.

The interface representing the Authorization Manager is the org.picketbox.core.authorization.AuthorizationManager.