/*
  jwtTest - JSON Web Token Testimplementierung 
  Copyright (C) 2021  Ulrich Hilger

  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU Affero General Public License as
  published by the Free Software Foundation, either version 3 of the
  License, or (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU Affero General Public License for more details.

  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
package de.uhilger.httpserver.auth.realm;

/**
 * A Realm is a "database" of usernames and passwords that identify valid 
 * users of an application (or a set of applications), plus an enumeration 
 * of the list of roles associated with each valid user. 
 * 
 * You can think of roles as similar to groups in Unix-like operating systems, 
 * because access to specific web application resources is granted to all 
 * users possessing a particular role (rather than enumerating the list of 
 * associated usernames). A particular user can have any number of roles 
 * associated with their username.
 * 
 * 
 * 
 * 
 * Die Klasse Realm liefert Angaben zu Benutzern, die zu deren 
 * Authentifizierung benoetigt werden.
 * 
 * Ein Benutzer Authentisiert sich gegenueber einem System z.B. mit 
 * seiner Benutzerkennung und einem Kennwort. 
 * 
 * Das System vergleicht die Authentisierungsangaben den Benutzers mit 
 * Angaben, die fuer diesen Benutzer im System hinterlegt wurden. Stimmen die 
 * Angaben ueberein, gibt das System eine Bestaetigung aus, die den Benutzer 
 * authentifiziert. 
 * 
 * Diese Authentifizierungsbestaetigung dient zur Ausfuehrung 
 * von Transaktionen, die nur von bestimmten Benutzern durchgefuehrt 
 * werden duerfen. Anhand der Authentifizierungsbestaetigung kann das System 
 * bei jeder Anfrage pruefen, ob der Benutzer, von dem die Anfrage kommt, der 
 * Benutzer ist, der er vorgibt zu sein.
 * 
 * @author Ulrich Hilger
 * @version 1, 22.05.2021
 */
public interface Realm {
  
  /**
   * Uberpruefen, ob die Benutzerkennung und das Kennwort gueltig sind.
   * 
   * @param user  der Benutzer
   * @param kennwort das Kennwort des Benutzers
   * @return true, wenn die Angaben stimmen, false wenn nicht
   */
  public boolean isValid(String userId, String kennwort);
  
  /**
   * Pruefen, ob ein Benutzer eine Rolle hat
   * 
   * @param user der Benutzer
   * @param roleId die Kennung der Rolle
   * @return  true, wenn der Benutzer die Rolle hat, false wenn nicht
   */
  public boolean hasRole(String userId, String roleId);
  
  /**
   * Den Namen dieses Realms ermitteln
   * @return Name des Realms
   */
  public String getName();
  
}