001/*
002 * (C) Copyright 2006-2014 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Bogdan Stefanescu
018 */
019package org.nuxeo.ecm.core.api;
020
021import java.io.Serializable;
022import java.security.Principal;
023import java.util.List;
024import java.util.UUID;
025
026import org.nuxeo.runtime.api.Framework;
027import org.nuxeo.runtime.services.config.ConfigurationService;
028
029/**
030 * Class to represent a principal in Nuxeo. This class holds the list of roles and groups for this principal.
031 */
032public interface NuxeoPrincipal extends Principal, Serializable {
033
034    String PREFIX = "user:";
035
036    /**
037     * @since 8.1
038     */
039    String TRANSIENT_USER_PREFIX = "transient/";
040
041    /**
042     * @since 8.1
043     * @deprecated since 10.3.
044     */
045    @Deprecated
046    String TRANSIENT_USER_FORMAT = TRANSIENT_USER_PREFIX + "%s/%s";
047
048    /**
049     * Property that defines if a transient username should be unique no matter what base username is provided, or if a
050     * transient username should be always the same for a given base username.
051     *
052     * @since 10.3
053     */
054    String TRANSIENT_USERNAME_UNIQUE_PROP = "nuxeo.transient.username.unique";
055
056    /**
057     * Gets the first name of this principal.
058     *
059     * @return the first name of this principal
060     */
061    String getFirstName();
062
063    /**
064     * Gets the last name of this principal.
065     *
066     * @return the last name of this principal
067     */
068    String getLastName();
069
070    /**
071     * Gets the password of this principal.
072     * <p>
073     * Note: Some APIs that return principals from the database intentionally do not fill this field
074     *
075     * @return the password of this principal
076     */
077    String getPassword();
078
079    /**
080     * Gets the company name of this principal.
081     *
082     * @return the company name
083     */
084    String getCompany();
085
086    /**
087     * Get the user email if any. Return null if not email was specified
088     *
089     * @return the user email or null if none
090     */
091    String getEmail();
092
093    /**
094     * Gets the groups this principal is directly member of.
095     *
096     * @return the list of the groups
097     */
098    List<String> getGroups();
099
100    /**
101     * Gets the groups this principal directly or undirectly is member of.
102     *
103     * @return the list of the groups
104     */
105    List<String> getAllGroups();
106
107    /**
108     * Recursively test if the user is member of this group.
109     *
110     * @param group The name of the group
111     */
112    boolean isMemberOf(String group);
113
114    /**
115     * Gets the roles for this principal.
116     *
117     * @return the list of the roles
118     */
119    List<String> getRoles();
120
121    void setName(String name);
122
123    void setFirstName(String firstName);
124
125    void setLastName(String lastName);
126
127    void setGroups(List<String> groups);
128
129    void setRoles(List<String> roles);
130
131    void setCompany(String company);
132
133    void setPassword(String password);
134
135    void setEmail(String email);
136
137    /**
138     * Returns a generated id that is unique for each principal instance.
139     *
140     * @return a unique string
141     */
142    String getPrincipalId();
143
144    /**
145     * Sets the principalId.
146     *
147     * @param principalId a new principalId for this instance
148     */
149    void setPrincipalId(String principalId);
150
151    DocumentModel getModel();
152
153    void setModel(DocumentModel model);
154
155    /**
156     * Returns true if the principal is an administrator.
157     * <p>
158     * Security checks still apply on the repository for administrator user. If user is a system user, this method will
159     * return true.
160     *
161     * @return true if the principal is an administrator.
162     */
163    boolean isAdministrator();
164
165    /**
166     * Returns the {@code tenantId} of this {@NuxeoPrincipal}, or {@code null} if there is no {@code tenantId}.
167     *
168     * @since 5.6
169     */
170    String getTenantId();
171
172    /**
173     * Checks if the principal is anonymous (guest user).
174     *
175     * @return true if the principal is anonymous.
176     */
177    boolean isAnonymous();
178
179    /**
180     * Gets the base user from which this principal was created, or {@code null} if this principal was not created from
181     * another user.
182     *
183     * @return the originating user, or {@code null}
184     */
185    String getOriginatingUser();
186
187    /**
188     * Sets the originating user.
189     *
190     * @param originatingUser the originating user
191     */
192    void setOriginatingUser(String originatingUser);
193
194    /**
195     * Gets the acting user for this principal.
196     * <p>
197     * This is the originating user (usually when this principal is a system user), or if there is none this principal's
198     * user.
199     *
200     * @return the acting user
201     * @since 6.0
202     */
203    String getActingUser();
204
205    /**
206     * Returns true if the principal is a transient principal.
207     *
208     * @since 8.1
209     */
210    boolean isTransient();
211
212    /**
213     * Returns true if the given @{code username} is a transient username.
214     *
215     * @since 8.1
216     */
217    static boolean isTransientUsername(String username) {
218        return username != null && username.startsWith(TRANSIENT_USER_PREFIX);
219    }
220
221    /**
222     * Computes a transient username from the given {@code baseUsername}.
223     * <p>
224     * If the configuration property {@value #TRANSIENT_USERNAME_UNIQUE_PROP} is {@code true}, the transient username
225     * will be unique, otherwise it will always be the same for a given {@code baseUsername}.
226     *
227     * @since 8.1
228     */
229    static String computeTransientUsername(String baseUsername) {
230        if (baseUsername != null && !baseUsername.startsWith(TRANSIENT_USER_PREFIX)) {
231            StringBuilder sb = new StringBuilder(TRANSIENT_USER_PREFIX);
232            sb.append(baseUsername);
233            if (Framework.getService(ConfigurationService.class)
234                         .isBooleanPropertyTrue(TRANSIENT_USERNAME_UNIQUE_PROP)) {
235                String uuid = UUID.randomUUID().toString();
236                uuid = uuid.replaceAll("-", "").substring(0, 16);
237                sb.append("/");
238                sb.append(uuid);
239            }
240            return sb.toString();
241        }
242        return baseUsername;
243    }
244
245}