wamblee.org Git - utils/blob - security/usermgt/src/main/java/org/wamblee/security/authentication/package-info.java

   1 /*
   2  * Copyright 2005-2010 the original author or authors.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 /**
  17  * This package provides support for managing users and their authentication.
  18  *
  19  * <h1>Supported use cases</h1>
  20  *
  21  * in particular, it supports the following use cases:
  22  * <ul>
  23  *   <li> Dynamically manage users and groups from an application.
  24  *   </li>
  25  *   <li> Authenticate users
  26  *   </li>
  27  *   <li> Store users and groups in a database.
  28  *   </li>
  29  * </ul>
  30  *
  31  * An overview is given below:
  32  * <br/>
  33  * <img src="doc-files/Class_Diagram__org.wamblee.security.authentication__main.jpg" alt="overview"</img>
  34  * <br/>
  35  *
  36  * The user of the package interacts with the {@link UserAdministration} interface for the following tasks:
  37  * <ul>
  38  *   <li>Adding users and removing users</li>
  39  *   <li>Adding users to groups and removing them from groups</li>
  40  *   <li>Renaming users and groups</li>
  41  *   <li>Modifying the user's password</li>
  42  *   <li>Populate with initial users upon first startup</li>
  43  * </ul>
  44  * In addition, it provides methods for authenticating the user. Note however that it is also possible
  45  * to use declarative Java EE security using the appropriate security realm. See for instance,
  46  * <a href="http://flexiblejdbcrealm.wamblee.org">flexible JDBC realm</a> for a Glassfish based solution.
  47  *
  48  * {@link UserAdminInitializer} can be used to automatically initialize the user administration with
  49  * initial users and groups when there are no users defined yet.
  50  *
  51  * To use the user administration interface, several implementation classes must be wired together. This is
  52  * explained below.
  53  *
  54  * There is one implementation {@link UserAdministrationImpl} of this interface that must be constructed
  55  * with a {@link UserSet} and {@link GroupSet} implementation, together with two validators: one for
  56  * user names and another for group names.
  57  *
  58  * For user and groups sets there are two implementations, one inmemory and another with database persistence.
  59  * Typically the one with database persistence is used but for testing other code, the inmemory implementation
  60  * can be used.
  61  * <br/>
  62  * <img src="doc-files/Class_Diagram__org.wamblee.security.authentication__sets.jpg"/>
  63  * <br/>
  64  *
  65  * At construction of the userset, a password validator is required as well as a digest algorithm to
  66  * compute a digest of the password to store in the database and also to validate users against.
  67  * <br/>
  68  * <img src="doc-files/Class_Diagram__org.wamblee.security.authentication__digester.jpg"/>
  69  * <br/>
  70  *
  71  * Finally, there is the basic model for users and groups that is used under the covers. As a user
  72  * of the security library these objects will typically not be used.
  73  * <br/>
  74  * <img src="doc-files/Class_Diagram__org.wamblee.security.authentication__users.jpg"/>
  75  * <br/>
  76  */
  77 package org.wamblee.security.authentication;