Module org.bzdev.ejws
Package org.bzdev.ejws

Class EjwsUserTable<A extends EjwsAuthenticator,E extends EjwsAuthenticator.Entry>

java.lang.Object
org.bzdev.ejws.EjwsUserTable<A,E>
Direct Known Subclasses:
DefaultBasicUT, DefaultSecureBasicUT
public abstract class EjwsUserTable<A extends EjwsAuthenticator,E extends EjwsAuthenticator.Entry> extends Object
Default user-table implementation. This class is used by subclasses of EjwsAuthenticator to manage a map that associates user names with entries used by an authenticator. It provides the operations needed by EjwsBasicAuthenticator and EjwsSecureBasicAuth, which require a simpler API than instances of Map provides.

Subclasses of this class can be written so that user data is stored in a database, or whatever type of persistent storage is desired. A subclass must override the following methods:

In all of these methods, the first String argument, if there is one, is a string providing a user name, often an email address.

If persistent storage is altered, either the method updateEntry(String) or EjwsAuthenticator's createUser methods (along with EjwsAuthenticator.UserInfo methods) should be called so that the authenticator will record the change.

  • Constructor Details

    • EjwsUserTable

      public EjwsUserTable()
      Constructor.

  • Method Details

    • setMap

      public void setMap(Map<String,E> map)
      Set the user-table's map. This method is called by EjwsBasicAuthenticator.setUserTable(org.bzdev.ejws.EjwsUserTable<org.bzdev.ejws.EjwsBasicAuthenticator, org.bzdev.ejws.EjwsBasicAuthenticator.Entry>) and EjwsSecureBasicAuth.setUserTable(org.bzdev.ejws.EjwsUserTable<org.bzdev.ejws.EjwsSecureBasicAuth, org.bzdev.ejws.EjwsSecureBasicAuth.Entry>). One of those methods should be called before an instance of this class is used.

      Normally, this method should be called only by subclasses of EjwsUserTable.

      Parameters:
      map - the map

    • setAuth

      public void setAuth(A auth)
      Set the authenticator that uses this EjwsUserTable. This method is called by EjwsBasicAuthenticator.setUserTable(org.bzdev.ejws.EjwsUserTable<org.bzdev.ejws.EjwsBasicAuthenticator, org.bzdev.ejws.EjwsBasicAuthenticator.Entry>) and EjwsSecureBasicAuth.setUserTable(org.bzdev.ejws.EjwsUserTable<org.bzdev.ejws.EjwsSecureBasicAuth, org.bzdev.ejws.EjwsSecureBasicAuth.Entry>). One of those methods should be called before an instance of this class is used.

      Normally, this method should be called only by subclasses of EjwsUserTable.

      Parameters:
      auth - the authenticator;

    • getAuthenticator

      protected A getAuthenticator()
      Get the authenticator that uses this EjwsUserTable.
      Returns:
      the authenticator.

    • getRoles

      public Set<String> getRoles(String user)
      Get the roles for a user.
      Returns:
      the roles; null or an empty set if there are no roles

    • getEntry

      public final E getEntry(String user)
      Get an entry. The value returned will be the entry in the map passed to the constructor. Instead of using this method, one can look up the entry directly from the map.
      Parameters:
      user - the user name
      Returns:
      the entry

    • putEntry

      public final E putEntry(String user, E entry)
      Add or replace an entry. Typically, one will call getEntry(java.lang.String), modify the entry this method returns, and then call putEntry(String,Entry) to update the value. If an operation using this method fails the authenticator's map should be restored to its previous value.
      Parameters:
      user - the user name
      entry - the new entry
      Returns:
      true if successful; false if the operation failed.

    • makeActive

      public final boolean makeActive(String user)
      Make a user active.
      Parameters:
      user - the user
      Returns:
      true on success; false on error or if the user was already active

    • makePending

      public final boolean makePending(String user)
      Make a user pending.
      Parameters:
      user - the user
      Returns:
      true on success; false on error or if the user was already pending

    • storeGPGKey

      public abstract void storeGPGKey(String value, EjwsAuthenticator.GPGKeyIDs keyids) throws IllegalArgumentException, IllegalStateException, IOException
      Store a PGP/GPG key. The keyids argument is used for test to make sure we do not replace existing keys with unrelated ones.
      Parameters:
      value - an ASCII-armored PGP/GPG public key.
      keyids - a container for the key's email address and the key's fingerprint
      Throws:
      NullPointerException - if the GPG home directory had not been set (for implementations that specify a GPG home directory)
      IllegalArgumentException - if the key is ill-formed
      IllegalStateException - if the key cannot be stored
      IOException - if an IO error occurs while constructing a cannonical path

    • storeSBLData

      public abstract void storeSBLData(String s, EjwsAuthenticator.AddStatus status) throws Exception
      Store SBL data that was provided using the string representation. If status is EjwsAuthenticator.AddStatus.REJECTED, this method should not be called by an authenticator.

      Implementation note: the method EjwsAuthenticator.getUserNameFromSBL(String) can be used to find the user name. If the contents of the string s should be stored rather than s itself, the constructor ConfigProperties(String,String) can be called with s as its first argument and the string "application/vnd.bzdev.sblauncher" as its second argument. This SBL file should have a single key KEY and a field named KEY.description or possibly base64.KEY.description, which can be used to determine the key KEY. Normally KEY will be the string user.

      • base64.keypair.publicKey. A base-64 encoded, PEM encoded public key.
      • KEY.user. The user's name (email address is preferred).
      • base64.KEY.password. The password.
      • KEY.base. The shared prefix used by this user table's authenticator. It must end with a "/".
      • KEY.uri. The URI to visit. If it starts with $(KEY.base), that will be replaced with the value of the KEY.base field.
      • KEY.mode. The ordinal of an enumeration constant defined by SecureBasicUtilities.Mode:
        • 0 for DIGEST.
        • 1 for SIGNATURE_WITHOUT_CERT.
        • 2 for SIGNATURE_WITH_CERT.
        • 3 for PASSWORD.
      Parameters:
      s - SBL data in string form
      status - the status of the request (EjwsAuthenticator.AddStatus.OK or EjwsAuthenticator.AddStatus.PENDING)
      Throws:
      Exception - if there is an error

    • storePW

      public abstract void storePW(String un, String pw, boolean isActive) throws Exception
      Store a basic-authentication password.
      Parameters:
      un - the user name
      pw - the password
      isActive - true if the user is active; false otherwise
      Throws:
      Exception - if there is an error

    • updateEntry

      public final boolean updateEntry(String user)
      Update an entry in the map. This method should be called when data in persistent storage for the given user has been changed explicitly, rather than by this user table's authenticator—otherwise the persistent storage and the corresponding authenticator will be inconsistent.

      If there is no current entry for a user, the method createEntryFromDB(String) will be called with the user name as its argument. The value returned will then be put into the map with the user name as the map's key.

      If there is an existing user, the method getEntryFromDB(E,String) will be called to get a replacement entry, with the existing entry as its first argument and the user name as its second argument. If the replacement entry is null, the user is removed from the map; otherwise the map is updated.

      Parameters:
      user - the user name
      Returns:
      true normally; false if there was a failure that threw an exception

    • removeEntry

      public final boolean removeEntry(String user)
      Remove an entry.
      Parameters:
      user - the user name
      Returns:
      true on success; false on failure

    • loadEntriesFromDB

      protected abstract void loadEntriesFromDB(Map<String,E> map) throws Exception
      Set up the map based on information in persistent storage. This method is called by setMap(java.util.Map<java.lang.String, E>).

      The source code for DefaultBasicUT and DefaultSecureBasicUT are useful guides for an implementation.

      Parameters:
      map - the map
      Throws:
      Exception - if an error occurred

    • createEntryFromDB

      protected abstract void createEntryFromDB(String user) throws Exception
      Create an entry corresponding to the data in persistent storage.

      The source code for DefaultBasicUT and DefaultSecureBasicUT are useful guides for an implementation.

      Parameters:
      user - the user name
      Throws:
      Exception - if an error occurs

    • getEntryFromDB

      protected abstract E getEntryFromDB(E oldEntry, String user) throws Exception
      Get an entry corresponding to the data in persistent storage.

      The source code for DefaultBasicUT and DefaultSecureBasicUT are useful guides for an implementation.

      Parameters:
      oldEntry - the previous map entry
      user - the user name
      Returns:
      the entry; null if there is none in persistent storage
      Throws:
      Exception - if an error occurs

    • makeActiveInDB

      protected abstract void makeActiveInDB(String user) throws Exception
      Make an entry active in persistent storage.

      This may be called by EJWS when an admin page is used, when an account is uses an authorization code, or when any new account is accepted.

      Parameters:
      user - the user name
      Throws:
      Exception - if there is an error

    • makePendingInDB

      protected abstract void makePendingInDB(String user) throws Exception
      Make an entry pending in persistent storage.

      This may be called when an admin page changes an account from active to pending. The source code for DefaultBasicUT and DefaultSecureBasicUT are useful guides for an implementation.

      Parameters:
      user - the user name
      Throws:
      Exception - if there is an error

    • removeEntryFromDB

      protected abstract void removeEntryFromDB(String user) throws Exception
      Remove an entry from persistent storage.

      This may be called by EJWS when an admin page deletes an account. The source code for DefaultBasicUT and DefaultSecureBasicUT are useful guides for an implementation.

      Parameters:
      user - the user name
      Throws:
      Exception - if an error occurs