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}