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.json; 017 018import static org.forgerock.json.JsonValue.field; 019import static org.forgerock.json.JsonValue.json; 020import static org.forgerock.json.JsonValue.object; 021 022import java.io.IOException; 023import java.io.InputStream; 024import java.util.LinkedHashMap; 025import java.util.Map; 026 027import org.forgerock.audit.AuditException; 028import org.forgerock.audit.AuditServiceBuilder; 029import org.forgerock.audit.AuditServiceConfiguration; 030import org.forgerock.audit.events.handlers.AuditEventHandler; 031import org.forgerock.audit.events.handlers.EventHandlerConfiguration; 032import org.forgerock.audit.util.JsonValueUtils; 033import org.forgerock.json.JsonValue; 034import org.slf4j.Logger; 035import org.slf4j.LoggerFactory; 036 037import com.fasterxml.jackson.annotation.JsonPropertyDescription; 038import com.fasterxml.jackson.databind.AnnotationIntrospector; 039import com.fasterxml.jackson.databind.ObjectMapper; 040import com.fasterxml.jackson.databind.introspect.Annotated; 041import com.fasterxml.jackson.databind.introspect.JacksonAnnotationIntrospector; 042import com.fasterxml.jackson.module.jsonSchema.JsonSchema; 043import com.fasterxml.jackson.module.jsonSchema.factories.SchemaFactoryWrapper; 044 045/** 046 * Utility class to facilitate creation and configuration of audit service and audit event handlers 047 * through JSON. 048 */ 049public class AuditJsonConfig { 050 private static final Logger logger = LoggerFactory.getLogger(AuditJsonConfig.class); 051 052 /** Field containing the name of an event handler. */ 053 private static final String NAME_FIELD = "name"; 054 /** Field containing the implementation class of an event handler. */ 055 private static final String CLASS_FIELD = "class"; 056 /** Field containing the configuration of an event handler. */ 057 private static final String CONFIG_FIELD = "config"; 058 /** Field containing events topics to process for an event handler. */ 059 private static final String EVENTS_FIELD = "events"; 060 061 /** The mapper from JSON structure to Java object. */ 062 //checkstyle:off 063 private static final ObjectMapper mapper = new ObjectMapper(); 064 // checkstyle:on 065 066 private static final AnnotationIntrospector defaultAnnotationIntrospector = new JacksonAnnotationIntrospector(); 067 private static final AnnotationIntrospector helpAppenderAnnotationIntrospector = 068 new HelpAppenderAnnotationIntrospector(); 069 070 private AuditJsonConfig() { 071 // prevent instantiation of the class 072 } 073 074 /** 075 * Returns a JSON value from the provided input stream. 076 * 077 * @param input 078 * Input stream containing an arbitrary JSON structure. 079 * @return the JSON value corresponding to the JSON structure 080 * @throws AuditException 081 * If an error occurs. 082 */ 083 public static JsonValue getJson(InputStream input) throws AuditException { 084 try { 085 return new JsonValue(mapper.readValue(input, LinkedHashMap.class)); 086 } catch (IOException e) { 087 throw new AuditException(String.format("Unable to retrieve json value from json input stream"), e); 088 } 089 } 090 091 /** 092 * Returns the audit service configuration from the provided input stream. 093 * 094 * @param input 095 * Input stream containing JSON configuration of the audit service. 096 * @return the configuration object 097 * @throws AuditException 098 * If any error occurs. 099 */ 100 public static AuditServiceConfiguration parseAuditServiceConfiguration(InputStream input) throws AuditException { 101 try { 102 return mapper.readValue(input, AuditServiceConfiguration.class); 103 } catch (IOException e) { 104 throw new AuditException(String.format("Unable to retrieve class %s from json input stream", 105 AuditServiceConfiguration.class), e); 106 } 107 } 108 109 /** 110 * Returns the audit service configuration from the provided JSON string. 111 * 112 * @param json 113 * JSON string representing the configuration of the audit service. 114 * @return the configuration object 115 * @throws AuditException 116 * If any error occurs. 117 */ 118 public static AuditServiceConfiguration parseAuditServiceConfiguration(String json) throws AuditException { 119 if (json == null) { 120 return new AuditServiceConfiguration(); 121 } 122 try { 123 return mapper.readValue(json, AuditServiceConfiguration.class); 124 } catch (IOException e) { 125 throw new AuditException(String.format("Unable to retrieve class %s from json: %s", 126 AuditServiceConfiguration.class, json), e); 127 } 128 } 129 130 /** 131 * Returns the audit service configuration from the provided JSON value. 132 * 133 * @param json 134 * JSON value representing the configuration of the audit service. 135 * @return the configuration object 136 * @throws AuditException 137 * If any error occurs. 138 */ 139 public static AuditServiceConfiguration parseAuditServiceConfiguration(JsonValue json) throws AuditException { 140 return parseAuditServiceConfiguration(JsonValueUtils.extractValueAsString(json, "/")); 141 } 142 143 /** 144 * Configures and registers the audit event handler corresponding to the provided JSON configuration 145 * to the provided audit service. 146 * 147 * @param jsonConfig 148 * The configuration of the audit event handler as JSON. 149 * @param auditServiceBuilder 150 * The builder for the service the event handler will be registered to. 151 * @throws AuditException 152 * If any error occurs during configuration or registration of the handler. 153 */ 154 public static void registerHandlerToService(JsonValue jsonConfig, AuditServiceBuilder auditServiceBuilder) 155 throws AuditException { 156 registerHandlerToService(jsonConfig, auditServiceBuilder, auditServiceBuilder.getClass().getClassLoader()); 157 } 158 159 /** 160 * Configures and registers the audit event handler corresponding to the provided JSON configuration 161 * to the provided audit service, using a specific class loader. 162 * 163 * @param jsonConfig 164 * The configuration of the audit event handler as JSON. 165 * @param auditServiceBuilder 166 * The builder for the service the event handler will be registered to. 167 * @param classLoader 168 * The class loader to use to load the handler and its configuration class. 169 * @throws AuditException 170 * If any error occurs during configuration or registration of the handler. 171 */ 172 public static void registerHandlerToService(JsonValue jsonConfig, 173 AuditServiceBuilder auditServiceBuilder, ClassLoader classLoader) throws AuditException { 174 String name = getHandlerName(jsonConfig); 175 Class<? extends AuditEventHandler> handlerClass = getAuditEventHandlerClass(name, jsonConfig, classLoader); 176 Class<? extends EventHandlerConfiguration> configClass = 177 getAuditEventHandlerConfigurationClass(name, handlerClass, classLoader); 178 EventHandlerConfiguration configuration = parseAuditEventHandlerConfiguration(configClass, jsonConfig); 179 auditServiceBuilder.withAuditEventHandler(handlerClass, configuration); 180 } 181 182 /** 183 * Returns the name of the event handler corresponding to provided JSON configuration. 184 * <p> 185 * The JSON configuration is expected to contains a "name" field identifying the 186 * event handler, e.g. 187 * <pre> 188 * "name" : "passthrough" 189 * </pre> 190 * 191 * @param jsonConfig 192 * The JSON configuration of the event handler. 193 * @return the name of the event handler 194 * @throws AuditException 195 * If an error occurs. 196 */ 197 private static String getHandlerName(JsonValue jsonConfig) throws AuditException { 198 String name = jsonConfig.get(CONFIG_FIELD).get(NAME_FIELD).asString(); 199 if (name == null) { 200 throw new AuditException(String.format("No name is defined for the provided audit handler. " 201 + "You must define a 'name' property in the configuration.")); 202 } 203 return name; 204 } 205 206 /** 207 * Creates an audit event handler factory from the provided JSON configuration. 208 * <p> 209 * The JSON configuration is expected to contains a "class" property which provides 210 * the class name for the handler factory to instantiate. 211 * 212 * @param jsonConfig 213 * The configuration of the audit event handler as JSON. 214 * @param classLoader 215 * The class loader to use to load the handler and its configuration class. 216 * @return the fully configured audit event handler 217 * @throws AuditException 218 * If any error occurs during configuration or registration of the handler. 219 */ 220 @SuppressWarnings("unchecked") // Class.forName calls 221 private static Class<? extends AuditEventHandler> getAuditEventHandlerClass( 222 String handlerName, JsonValue jsonConfig, ClassLoader classLoader) throws AuditException { 223 // TODO: class name should not be provided in customer configuration 224 // but through a commons module/service context 225 String className = jsonConfig.get(CLASS_FIELD).asString(); 226 if (className == null) { 227 String errorMessage = String.format("No class is defined for the audit handler %s. " 228 + "You must define a 'class' property in the configuration.", handlerName); 229 throw new AuditException(errorMessage); 230 } 231 try { 232 return (Class<? extends AuditEventHandler>) Class.forName(className, true, classLoader); 233 } catch (ClassNotFoundException e) { 234 String errorMessage = String.format("Invalid class is defined for the audit handler %s.", handlerName); 235 throw new AuditException(errorMessage, e); 236 } 237 } 238 239 @SuppressWarnings("unchecked") // Class.forName calls 240 private static Class<? extends EventHandlerConfiguration> getAuditEventHandlerConfigurationClass( 241 String handlerName, Class<? extends AuditEventHandler> handlerClass, ClassLoader classLoader) 242 throws AuditException { 243 String className = handlerClass.getName() + "Configuration"; 244 try { 245 return (Class<? extends EventHandlerConfiguration>) Class.forName(className, true, classLoader); 246 } catch (ClassNotFoundException e) { 247 String errorMessage = String.format("Unable to locate configuration class %s for the audit handler %s.", 248 className, handlerName); 249 throw new AuditException(errorMessage, e); 250 } 251 } 252 253 /** 254 * Returns the audit event handler configuration from the provided JSON string. 255 * 256 * @param <C> 257 * The type of the configuration bean for the event handler. 258 * @param jsonConfig 259 * The configuration of the audit event handler as JSON. 260 * @return the fully configured audit event handler 261 * @throws AuditException 262 * If any error occurs while instantiating the configuration from JSON. 263 */ 264 private static <C extends EventHandlerConfiguration> C parseAuditEventHandlerConfiguration( 265 Class<C> clazz, JsonValue jsonConfig) throws AuditException { 266 C configuration = null; 267 JsonValue conf = jsonConfig.get(CONFIG_FIELD); 268 if (conf != null) { 269 configuration = mapper.convertValue(conf.getObject(), clazz); 270 } 271 return configuration; 272 } 273 274 /** 275 * Gets the configuration schema for an audit event handler as json schema. The supplied json config must contain 276 * a field called class with the value of the audit event handler implementation class. 277 * @param className The class name to get the configuration for. 278 * @param classLoader The {@link ClassLoader} to use to load the event handler and event handler config class. 279 * @return The config schema as json schema. 280 * @throws AuditException If any error occurs parsing the config class for schema. 281 */ 282 public static JsonValue getAuditEventHandlerConfigurationSchema(final String className, 283 final ClassLoader classLoader) throws AuditException { 284 final Class<? extends EventHandlerConfiguration> eventHandlerConfiguration = 285 getAuditEventHandlerConfigurationClass( 286 className, 287 getAuditEventHandlerClass( 288 className, 289 json(object(field("class", className))), 290 classLoader), 291 classLoader); 292 try { 293 mapper.setAnnotationIntrospector(helpAppenderAnnotationIntrospector); 294 SchemaFactoryWrapper visitor = new SchemaFactoryWrapper(); 295 mapper.acceptJsonFormatVisitor(mapper.constructType(eventHandlerConfiguration), visitor); 296 JsonSchema jsonSchema = visitor.finalSchema(); 297 final JsonValue schema = json(mapper.readValue(mapper.writeValueAsString(jsonSchema), Map.class)); 298 mapper.setAnnotationIntrospector(defaultAnnotationIntrospector); 299 return schema; 300 } catch (IOException e) { 301 final String error = String.format("Unable to parse configuration class schema for configuration class %s", 302 eventHandlerConfiguration.getName()); 303 logger.error(error, e); 304 throw new AuditException(error, e); 305 } 306 } 307 308 /** 309 * Extends the default {@link JacksonAnnotationIntrospector} and overrides the {@link JsonPropertyDescription} 310 * annotation inorder to append ".help" to the description. 311 */ 312 private static class HelpAppenderAnnotationIntrospector extends JacksonAnnotationIntrospector { 313 @Override 314 public String findPropertyDescription(Annotated ann) { 315 JsonPropertyDescription desc = _findAnnotation(ann, JsonPropertyDescription.class); 316 return (desc == null) ? null : desc.value().concat(".help"); 317 } 318 } 319 320}