| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| * |
| */ |
| package org.apache.directory.fortress.core; |
| |
| |
| import org.apache.directory.fortress.core.model.AuthZ; |
| import org.apache.directory.fortress.core.model.Mod; |
| import org.apache.directory.fortress.core.model.UserAudit; |
| import org.apache.directory.fortress.core.model.Bind; |
| |
| import java.util.List; |
| |
| |
| /** |
| * This interface prescribes methods used to search <a href="http://www.openldap.org/">OpenLDAP</a>'s slapd access log. |
| * The access log events are persisted in |
| * <a href="http://www.oracle.com/technetwork/database/berkeleydb/overview/index.html">BDB</a> and available for inquiry |
| * via common LDAP protocols. |
| * Audit entries stored on behalf of Fortress operations correspond to runtime authentication |
| * {@link org.apache.directory.fortress.core.model.Bind}, authorization |
| * {@link org.apache.directory.fortress.core.model.AuthZ} and modification |
| * {@link org.apache.directory.fortress.core.model.Mod} |
| * events as they occur automatically on the server when audit is enabled. |
| * <h3></h3> |
| * <h4>Audit Interrogator</h4> |
| * Provides an OpenLDAP access log retrieval mechanism that enables security event monitoring. |
| * <ol> |
| * <li>Authentication events:</li> |
| * <li> |
| * <ul> |
| * <li>Session enablement events</li> |
| * <li>Authorization events</li> |
| * <li>Entity mods and deletes</li> |
| * </ul> |
| * </li> |
| * </ol> |
| * <img src="./doc-files/Audit.png" alt=""> |
| * <p> |
| * All events include Fortress context, see {@link org.apache.directory.fortress.core.model.FortEntity}. |
| * <h4> |
| * The following APIs generate events subsequently stored in this access log: |
| * </h4> |
| * <ul> |
| * <li>{@link AccessMgr}</li> |
| * <li>{@link AdminMgr}</li> |
| * <li>{@link AdminMgr}</li> |
| * <li>{@link DelAdminMgr}</li> |
| * <li>{@link ConfigMgr}</li> |
| * <li>{@link PwPolicyMgr}</li> |
| * </ul> |
| * <h4> |
| * The following reports are supported using search input: {@link org.apache.directory.fortress.core.model.UserAudit} |
| * </h4> |
| * <ul> |
| * <li> |
| * User Authentications: <code>List<{@link org.apache.directory.fortress.core.model.Bind}> |
| * {@link AuditMgr#searchBinds(org.apache.directory.fortress.core.model.UserAudit)}</code> |
| * </li> |
| * <li> |
| * Invalid User AuthN: <code>List<{@link org.apache.directory.fortress.core.model.Bind}> |
| * {@link AuditMgr#searchInvalidUsers(org.apache.directory.fortress.core.model.UserAudit)} </code> |
| * </li> |
| * <li> |
| * User Authorizations 1: <code>List<{@link org.apache.directory.fortress.core.model.AuthZ}> |
| * {@link AuditMgr#getUserAuthZs(org.apache.directory.fortress.core.model.UserAudit)} </code> |
| * </li> |
| * <li> |
| * User Authorizations 2: <code>List<{@link org.apache.directory.fortress.core.model.AuthZ}> |
| * {@link AuditMgr#searchAuthZs(org.apache.directory.fortress.core.model.UserAudit)} </code> |
| * </li> |
| * <li> |
| * User Session Activations: <code>List<{@link org.apache.directory.fortress.core.model.Mod}> |
| * {@link AuditMgr#searchUserSessions(org.apache.directory.fortress.core.model.UserAudit)} </code> |
| * </li> |
| * <li> |
| * Entity Modifications: <code>List<{@link org.apache.directory.fortress.core.model.Mod}> |
| * {@link AuditMgr#searchAdminMods(org.apache.directory.fortress.core.model.UserAudit)} </code> |
| * </li> |
| * </ul> |
| * <p> |
| * This interface's implementer will NOT be thread safe if parent instance variables ({@link Manageable#setContextId(String)} |
| * or {@link Manageable#setAdmin(org.apache.directory.fortress.core.model.Session)}) are set. |
| * |
| * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> |
| */ |
| public interface AuditMgr extends Manageable |
| { |
| /** |
| * This method returns a list of authorization events for a particular user |
| * {@link org.apache.directory.fortress.core.model.UserAudit#userId} |
| * and given timestamp field {@link org.apache.directory.fortress.core.model.UserAudit#beginDate}.<br> |
| * Method also can discriminate between all events or failed only by setting |
| * {@link org.apache.directory.fortress.core.model.UserAudit#failedOnly}. |
| * <h3></h3> |
| * <h4>optional parameters</h4> |
| * <ul> |
| * <li>{@link org.apache.directory.fortress.core.model.UserAudit#userId} - contains the target userId</li> |
| * <li>{@link UserAudit#beginDate} - contains the date in which to begin search</li> |
| * <li>{@link UserAudit#failedOnly} - if set to 'true', return only failed authorization events</li> |
| * </ul> |
| * |
| * @param uAudit This entity is instantiated and populated before invocation. |
| * @return a List of objects of type AuthZ. Each AuthZ object contains one authorization event. |
| * @throws SecurityException if a runtime system error occurs. |
| */ |
| List<AuthZ> getUserAuthZs( UserAudit uAudit ) |
| throws SecurityException; |
| |
| |
| /** |
| * This method returns a list of authorization events for a particular user |
| * {@link org.apache.directory.fortress.core.model.UserAudit#userId}, |
| * object {@link org.apache.directory.fortress.core.model.UserAudit#objName}, and given timestamp field |
| * {@link org.apache.directory.fortress.core.model.UserAudit#beginDate}.<BR> |
| * Method also can discriminate between all events or failed only by setting flag {@link UserAudit#failedOnly}.. |
| * <h3></h3> |
| * <h4>required parameters</h4> |
| * <ul> |
| * <li>{@link UserAudit#userId} - contains the target userId</li> |
| * <li>{@link UserAudit#objName} - contains the object (authorization resource) name</li> |
| * </ul> |
| * <h4>optional parameters</h4> |
| * <ul> |
| * <li>{@link UserAudit#beginDate} - contains the date in which to begin search</li> |
| * <li>{@link UserAudit#failedOnly} - if set to 'true', return only failed authorization events</li> |
| * </ul> |
| * |
| * @param uAudit This entity is instantiated and populated before invocation. |
| * @return a List of objects of type AuthZ. Each AuthZ object contains one authorization event. |
| * @throws SecurityException |
| * if a runtime system error occurs. |
| */ |
| List<AuthZ> searchAuthZs( UserAudit uAudit ) |
| throws SecurityException; |
| |
| |
| /** |
| * This method returns a list of authentication audit events for a particular user |
| * {@link org.apache.directory.fortress.core.model.UserAudit#userId}, |
| * and given timestamp field {@link org.apache.directory.fortress.core.model.UserAudit#beginDate}.<BR> |
| * <h3></h3> |
| * <h4>optional parameters</h4> |
| * <ul> |
| * <li>{@link org.apache.directory.fortress.core.model.UserAudit#userId} - contains the target userId</li> |
| * <li> |
| * {@link org.apache.directory.fortress.core.model.UserAudit#beginDate} - contains the date in which to begin search |
| * </li> |
| * <li>{@link UserAudit#failedOnly} - if set to 'true', return only failed authorization events</li> |
| * </ul> |
| * |
| * @param uAudit This entity is instantiated and populated before invocation. |
| * @return a List of objects of type Bind. Each Bind object contains one bind event. |
| * @throws SecurityException |
| * if a runtime system error occurs. |
| */ |
| List<Bind> searchBinds( UserAudit uAudit ) |
| throws SecurityException; |
| |
| |
| /** |
| * This method returns a list of sessions created for a given user {@link UserAudit#userId}, |
| * and timestamp {@link org.apache.directory.fortress.core.model.UserAudit#beginDate}.<BR> |
| * <h3></h3> |
| * <h4>required parameters</h4> |
| * <ul> |
| * <li>{@link UserAudit#userId} - contains the target userId</li> |
| * </ul> |
| * <h4>optional parameters</h4> |
| * <ul> |
| * <li>{@link UserAudit#beginDate} - contains the date in which to begin search</li> |
| * </ul> |
| * |
| * @param uAudit This entity is instantiated and populated before invocation. |
| * @return a List of objects of type Mod. Each Mod object in list corresponds to one update or delete event on directory. |
| * @throws SecurityException if a runtime system error occurs. |
| */ |
| List<Mod> searchUserSessions( UserAudit uAudit ) |
| throws SecurityException; |
| |
| |
| /** |
| * This method returns a list of admin operations events for a particular entity |
| * {@link org.apache.directory.fortress.core.model.UserAudit#dn}, |
| * object {@link UserAudit#objName} and timestamp {@link org.apache.directory.fortress.core.model.UserAudit#beginDate}. |
| * If the internal userId {@link org.apache.directory.fortress.core.model.UserAudit#internalUserId} is set it will limit |
| * search by that field. |
| * <h3></h3> |
| * <h4>optional parameters</h4> |
| * <ul> |
| * <li> |
| * {@link UserAudit#dn} - contains the LDAP distinguished name for the updated object. For example if caller |
| * wants to find out what changes were made to John Doe's user object this would be |
| * 'uid=jdoe,ou=People,dc=example,dc=com' |
| * </li> |
| * <li> |
| * {@link UserAudit#objName} - contains the object (authorization resource) name corresponding to the event. For |
| * example if caller wants to return events where User object was modified, this would be 'updateUser' |
| * </li> |
| * <li |
| * >{@link org.apache.directory.fortress.core.model.UserAudit#internalUserId} - maps to the internalUserId of user |
| * who changed the record in LDAP. This maps to {@link org.apache.directory.fortress.core.model.User#internalId}. |
| * </li> |
| * <li>{@link UserAudit#beginDate} - contains the date in which to begin search</li> |
| * <li>{@link UserAudit#endDate} - contains the date in which to end search</li> |
| * </ul> |
| * |
| * @param uAudit This entity is instantiated and populated before invocation. |
| * @return a List of objects of type Mod. Each Mod object in list corresponds to one update or delete event on directory. |
| * @throws SecurityException |
| * if a runtime system error occurs. |
| */ |
| List<Mod> searchAdminMods( UserAudit uAudit ) |
| throws SecurityException; |
| |
| |
| /** |
| * This method returns a list of failed authentication attempts on behalf of an invalid identity |
| * {@link org.apache.directory.fortress.core.model.UserAudit#userId}, and given timestamp {@link UserAudit#beginDate}. |
| * If the {@link org.apache.directory.fortress.core.model.UserAudit#failedOnly} is true it will |
| * return only authentication attempts made with invalid userId. This event represents either User incorrectly entering |
| * userId during signon or possible fraudulent logon attempt by hostile agent. |
| * <p> |
| * This event is generated when Fortress looks up User record prior to LDAP bind operation. |
| * <h3></h3> |
| * <h4>optional parameters</h4> |
| * <ul> |
| * <li>{@link UserAudit#userId} - contains the target userId</li> |
| * <li>{@link UserAudit#beginDate} - contains the date in which to begin search</li> |
| * <li>{@link UserAudit#failedOnly} - if set to 'true', return only failed authorization events</li> |
| * </ul> |
| * |
| * @param uAudit This entity is instantiated and populated before invocation. |
| * @return a List of objects of type AuthZ. Each AuthZ object contains one failed authentication event. |
| * @throws SecurityException |
| * if a runtime system error occurs. |
| */ |
| List<AuthZ> searchInvalidUsers( UserAudit uAudit ) |
| throws SecurityException; |
| } |