001/* 002 * The contents of this file are subject to the terms of the Common Development and 003 * Distribution License (the License). You may not use this file except in compliance with the 004 * License. 005 * 006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the 007 * specific language governing permission and limitations under the License. 008 * 009 * When distributing Covered Software, include this CDDL Header Notice in each file and include 010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL 011 * Header, with the fields enclosed by brackets [] replaced by your own identifying 012 * information: "Portions copyright [year] [name of copyright owner]". 013 * 014 * Copyright 2015 ForgeRock AS. 015 */ 016package org.forgerock.audit.events; 017 018import java.util.List; 019import java.util.Map; 020 021/** 022 * Builder for audit authentication events. 023 * <p> 024 * This builder should not be used directly but be specialized for each product to allow to define 025 * new specific fields, e.g 026 * <pre> 027 * <code> 028 * class OpenProductAuthenticationAuditEventBuilder{@code <T extends OpenProductAuthenticationAuditEventBuilder<T>>} 029 extends AuthenticationAuditEventBuilder{@code <T>} { 030 * 031 * protected OpenProductAuthenticationAuditEventBuilder(DnsUtils dnsUtils) { 032 * super(dnsUtils); 033 * } 034 * 035 * public static {@code <T>} OpenProductAuthenticationAuditEventBuilder{@code <?>} productAuthenticationEvent() { 036 * return new OpenProductAuthenticationAuditEventBuilder(new DnsUtils()); 037 * } 038 * 039 * public T someField(String v) { 040 * jsonValue.put("someField", v); 041 * return self(); 042 * } 043 * 044 * ... 045 * } 046 * </code> 047 * </pre> 048 * @param <T> the type of the builder 049 */ 050public class AuthenticationAuditEventBuilder<T extends AuthenticationAuditEventBuilder<T>> 051 extends AuditEventBuilder<T> { 052 053 /** Defines the authentication result key. */ 054 public static final String RESULT = "result"; 055 /** Defines the principal key. */ 056 public static final String PRINCIPAL = "principal"; 057 /** Defines the context key. */ 058 public static final String CONTEXT = "context"; 059 /** Defines the entries key. */ 060 public static final String ENTRIES = "entries"; 061 062 /** 063 * Starts to build an audit authentication event. 064 * <p> 065 * Note: it is preferable to use a specialized builder that allow to add fields specific to a product. 066 * 067 * @return an audit authentication event builder 068 */ 069 @SuppressWarnings("rawtypes") 070 public static AuthenticationAuditEventBuilder<?> authenticationEvent() { 071 return new AuthenticationAuditEventBuilder(); 072 } 073 074 /** 075 * Sets the authentication audit event overall result. 076 * 077 * @param result the authentication overall result. 078 * @return an audit authentication event builder 079 */ 080 public T result(Status result) { 081 jsonValue.put(RESULT, result == null ? null : result.toString()); 082 return self(); 083 } 084 085 /** 086 * Sets the principals of the authentication event. 087 * 088 * @param principals the list of principals 089 * @return an audit authentication event builder 090 */ 091 public T principal(List<String> principals) { 092 jsonValue.put(PRINCIPAL, principals); 093 return self(); 094 } 095 096 /** 097 * Sets the context used in the authentication event. 098 * 099 * @param context the authentication event context 100 * @return an audit authentication event builder 101 */ 102 public T context(Map<String, Object> context) { 103 jsonValue.put(CONTEXT, context); 104 return self(); 105 } 106 107 /** 108 * Sets the list of auth modules used in the authentication event and their state. 109 * 110 * @param entries the list of authentication modules and their state 111 * @return an audit authentication event builder 112 */ 113 public T entries(List<?> entries) { 114 jsonValue.put(ENTRIES, entries); 115 return self(); 116 } 117 118 /** 119 * Defines a fixed set of authentication statuses that can be logged. 120 */ 121 public enum Status { 122 /** 123 * Authentication operation has not yet completed. 124 */ 125 CONTINUE, 126 /** 127 * Authentication operation has completed successfully. 128 */ 129 SUCCESSFUL, 130 /** 131 * Authentication operation has completed unsuccessfully. 132 */ 133 FAILED 134 } 135 136}