001/**
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2005 Sun Microsystems Inc. All Rights Reserved
005 *
006 * The contents of this file are subject to the terms
007 * of the Common Development and Distribution License
008 * (the License). You may not use this file except in
009 * compliance with the License.
010 *
011 * You can obtain a copy of the License at
012 * https://opensso.dev.java.net/public/CDDLv1.0.html or
013 * opensso/legal/CDDLv1.0.txt
014 * See the License for the specific language governing
015 * permission and limitations under the License.
016 *
017 * When distributing Covered Code, include this CDDL
018 * Header Notice in each file and include the License file
019 * at opensso/legal/CDDLv1.0.txt.
020 * If applicable, add the following below the CDDL Header,
021 * with the fields enclosed by brackets [] replaced by
022 * your own identifying information:
023 * "Portions Copyrighted [year] [name of copyright owner]"
024 *
025 * $Id: IdRepo.java,v 1.8 2009/07/02 20:33:30 hengming Exp $
026 *
027 */
028
029/**
030 * Portions Copyrighted 2013 ForgeRock, Inc.
031 */
032package com.sun.identity.idm;
033
034import java.util.Collections;
035import java.util.HashSet;
036import java.util.Map;
037import java.util.Set;
038
039import javax.security.auth.callback.Callback;
040
041import com.iplanet.sso.SSOException;
042import com.iplanet.sso.SSOToken;
043import com.sun.identity.sm.SchemaType;
044
045/**
046 * 
047 * This interface defines the methods which need to be implemented by plugins.
048 * Two plugins are supported, <code> ldap </code> and <code> remote </code>.
049 *
050 * @supported.all.api
051 */
052public abstract class IdRepo {
053
054    /**
055     * The constants used to define membership operations.
056     */
057    public static final int ADDMEMBER = 1;
058
059    public static final int REMOVEMEMBER = 2;
060
061    public Map<String, Set<String>> configMap = Collections.EMPTY_MAP;
062
063    public static final int NO_MOD = -1;
064
065    public static final int OR_MOD = 0;
066
067    public static final int AND_MOD = 1;
068
069    /**
070     * Initialization paramters as configred for a given plugin.
071     * 
072     * @param configParams
073     * @throws IdRepoException 
074     */
075    public void initialize(Map<String, Set<String>> configParams) throws IdRepoException {
076        configMap = Collections.unmodifiableMap(configParams);
077    }
078
079    /**
080     * This method is invoked just before the plugin is removed from the IdRepo
081     * cache of plugins. This helps the plugin clean up after itself
082     * (connections, persistent searches etc.). This method should be overridden
083     * by plugins that need to do this.
084     * 
085     */
086    public void shutdown() {
087        // do nothing
088    }
089
090    /**
091     * Return supported operations for a given IdType
092     * 
093     * @param type
094     *     Identity type
095     * @return set of IdOperation supported for this IdType.
096     */
097    public Set<IdOperation> getSupportedOperations(IdType type) {
098        Set<IdOperation> set = new HashSet<IdOperation>();
099        set.add(IdOperation.READ);
100        return set;
101    }
102
103    /**
104     * @return Returns a Set of IdTypes supported by this plugin.
105     * Returns the supported types of identities for this
106     * plugin. If a plugin does not override this method, it
107     * returns an empty set.
108     *
109     * @return a Set of IdTypes supported by this plugin.
110     */
111    public Set<IdType> getSupportedTypes() {
112        return Collections.EMPTY_SET;
113    }
114
115    /**
116     * Returns true if the <code> name </code> object exists in the data store.
117    *
118     * @param token
119     *     Single sign on token of identity performing the task.
120     * @param type
121     *     Identity type of this object.
122     * @param name
123     *     Name of the object  of interest.
124     * @return
125     *     <code>true</code> if name object is in data store
126     *     else <code>false</code>
127     * @throws IdRepoException If there are repository related error conditions.
128     * @throws SSOException If identity's single sign on token is invalid.
129     */
130    public abstract boolean isExists(SSOToken token, IdType type, String name)
131            throws IdRepoException, SSOException;
132
133    /**
134     * Returns true if the <code> name </code> object is active.
135     *
136     * @return
137     *     <code>true</code> if name object is in active
138     *     else <code>false</code>
139     * @param token
140     *     Single sign on token of identity performing the task.
141     * @param type
142     *     Identity type of this object.
143     * @param name
144     *     Name of the object of interest.
145     * @throws IdRepoException If there are repository related error conditions.
146     * @throws SSOException If identity's single sign on token is invalid.
147     */
148    public boolean isActive(SSOToken token, IdType type, String name)
149            throws IdRepoException, SSOException {
150        return false;
151    }
152
153    /**
154     * Sets the object's status to <code>active</code>.
155     *
156     * @param token
157     *     Single sign on token of identity performing the task.
158     * @param type
159     *     Identity type of this object.
160     * @param name
161     *     Name of the object of interest.
162     * @param active
163     *     true if setting to active; false otherwise.
164     * @throws IdRepoException If there are repository related error conditions.
165     * @throws SSOException If identity's single sign on token is invalid.
166     */
167    public abstract void setActiveStatus(SSOToken token, IdType type,
168        String name,  boolean active)
169        throws IdRepoException, SSOException;
170
171    /**
172     * Returns all attributes and values of name object
173     *
174     * @param token
175     *     Single sign on token of identity performing the task.
176     * @param type
177     *     Identity type of this object.
178     * @param name
179     *     Name of the object of interest.
180     * @return
181     *     Map of attribute-values
182     * @throws IdRepoException If there are repository related error conditions.
183     * @throws SSOException If identity's single sign on token is invalid.
184     */
185    public abstract Map<String, Set<String>> getAttributes(SSOToken token, IdType type, String name)
186            throws IdRepoException, SSOException;
187
188    /**
189     * Returns requested attributes and values of name object.
190     *
191     * @param token
192     *     Single sign on token of identity performing the task.
193     * @param type
194     *     Identity type of this object.
195     * @param name
196     *     Name of the object of interest.
197     * @param attrNames
198     *     Set of attribute names to be read
199     * @return
200     *     Map of attribute-values
201     * @throws IdRepoException If there are repository related error conditions.
202     * @throws SSOException If identity's single sign on token is invalid.
203     */
204    public abstract Map<String, Set<String>> getAttributes(SSOToken token, IdType type, String name,
205            Set<String> attrNames) throws IdRepoException, SSOException;
206
207    /**
208     * Returns requested binary attributes as an array of bytes.
209     *
210     * @param token
211     *     Single sign on token of identity performing the task.
212     * @param type
213     *     Identity type of this object.
214     * @param name
215     *     Name of the object of interest.
216     * @param attrNames
217     *     Set of attribute names to be read
218     * @return
219     *     Map of attribute-values
220     * @throws IdRepoException If there are repository related error conditions.
221     * @throws SSOException If identity's single sign on token is invalid.
222     */
223    public abstract Map<String, byte[][]> getBinaryAttributes(SSOToken token, IdType type,
224            String name, Set<String> attrNames) throws IdRepoException, SSOException;
225
226    /**
227     * Creates an identity.
228     *
229     * @param token
230     *     Single sign on token of identity performing the task.
231     * @param type
232     *     Identity type of this object.
233     * @param name
234     *     Name of the object of interest.
235     * @param attrMap
236     *     Map of attribute-values assoicated with this object.
237     * @throws IdRepoException If there are repository related error conditions.
238     * @throws SSOException If identity's single sign on token is invalid.
239     */
240    public abstract String create(SSOToken token, IdType type, String name,
241            Map<String, Set<String>> attrMap) throws IdRepoException, SSOException;
242
243    /**
244     * Deletes an identity.
245     *
246     * @param token
247     *     Single sign on token of identity performing the task.
248     * @param type
249     *     Identity type of this object.
250     * @param name
251     *     Name of the object of interest.
252     * @throws IdRepoException If there are repository related error conditions.
253     * @throws SSOException If identity's single sign on token is invalid.
254     */
255    public abstract void delete(SSOToken token, IdType type, String name)
256            throws IdRepoException, SSOException;
257
258    /**
259     * Set the values of attributes of the identity.
260     *
261     * @param token
262     *     Single sign on token of identity performing the task.
263     * @param type
264     *     Identity type of this object.
265     * @param name
266     *     Name of the object of interest.
267     * @param attributes
268     *     Map of attribute-values to set or add.
269     * @param isAdd
270     *     if <code>true</code> add the attribute-values; otherwise
271     *     replaces the attribute-values.
272     * @throws IdRepoException If there are repository related error conditions.
273     * @throws SSOException If identity's single sign on token is invalid.
274     */
275    public abstract void setAttributes(SSOToken token, IdType type,
276            String name, Map<String, Set<String>> attributes, boolean isAdd) throws IdRepoException,
277            SSOException;
278
279    /**
280     *
281     * Set the values of binary attributes the identity.
282     *
283     * @param token
284     *     Single sign on token of identity performing the task.
285     * @param type
286     *     Identity type of this object.
287     * @param name
288     *     Name of the object of interest.
289     * @param attributes
290     *     Map of binary attribute-values to set or add.
291     * @param isAdd
292     *     if <code>true</code> add the attribute-values; otherwise
293     *     replaces the attribute-values.
294     * @throws IdRepoException If there are repository related error conditions.
295     * @throws SSOException If identity's single sign on token is invalid.
296     */
297    public abstract void setBinaryAttributes(SSOToken token, IdType type,
298            String name, Map<String, byte[][]> attributes, boolean isAdd) throws IdRepoException,
299            SSOException;
300
301    /**
302     *
303     * Changes password of identity.
304     *
305     * @param token Single sign on token of identity performing the task.
306     * @param type identity type of this object.
307     * @param name name of the object of interest.
308     * @param attrName password attribute name
309     * @param oldPassword old password
310     * @param newPassword new password
311     * @throws IdRepoException If there are repository related error conditions.
312     * @throws SSOException If identity's single sign on token is invalid.
313     */
314    public void changePassword(SSOToken token, IdType type,
315            String name, String attrName, String oldPassword,
316            String newPassword) throws IdRepoException, SSOException {
317
318            Object args[] = { this.getClass().getName() };
319            throw new IdRepoUnsupportedOpException(IdRepoBundle.BUNDLE_NAME,
320                    "228", args);
321    }
322
323    /**
324     * Removes the attributes from the identity.
325     *
326     * @param token
327     *     Single sign on token of identity performing the task.
328     * @param type
329     *     Identity type of this object.
330     * @param name
331     *     Name of the object of interest.
332     * @param attrNames
333     *     Set of attribute names to remove.
334     * @throws IdRepoException If there are repository related error conditions.
335     * @throws SSOException If identity's single sign on token is invalid.
336     */
337    public abstract void removeAttributes(SSOToken token, IdType type,
338            String name, Set<String> attrNames) throws IdRepoException, SSOException;
339
340    /**
341     * Search for specific type of identities.
342     *
343     * @param token
344     *     Single sign on token of identity performing the task.
345     * @param type
346     *     Identity type of this object.
347     * @param pattern
348     *     pattern to search for.
349     * @param maxTime
350     *     maximum wait time for search.
351     * @param maxResults
352     *     maximum records to return.
353     * @param returnAttrs
354     *     Set of attribute names to return.
355     * @param returnAllAttrs
356     *     return all attributes
357     * @param filterOp
358     *     filter condition.
359     * @param avPairs
360     *     additional search conditions.
361     * @return RepoSearchResults
362     * @throws IdRepoException If there are repository related error conditions.
363     * @throws SSOException If identity's single sign on token is invalid.
364     */
365    public abstract RepoSearchResults search(SSOToken token, IdType type,
366            String pattern, int maxTime, int maxResults, Set<String> returnAttrs,
367            boolean returnAllAttrs, int filterOp, Map<String, Set<String>> avPairs, 
368            boolean recursive) throws IdRepoException, SSOException;
369
370    /**
371     * Modify membership of the identity. Set of members is
372     * a set of unique identifiers of other identities.
373     *
374     * @param token
375     *     Single sign on token of identity performing the task.
376     * @param type
377     *     Identity type of this object.
378     * @param name
379     *     Name of the object of interest.
380     * @param members
381     *     Set of names to be added as members of name
382     * @param membersType
383     *     IdType of members.
384     * @param operation
385     *     operations to perform on members ADDMEMBER or REMOVEMEMBER.
386     * @throws IdRepoException If there are repository related error conditions.
387     * @throws SSOException If identity's single sign on token is invalid.
388     */
389    public abstract void modifyMemberShip(SSOToken token, IdType type,
390            String name, Set<String> members, IdType membersType, int operation)
391            throws IdRepoException, SSOException;
392
393    /**
394     * Returns the memberships of an identity. For example, returns the groups or roles that a user belongs to. The
395     * list retrieved here for a user MUST be consistent with member queries against the corresponding groups.
396     *
397     * @param token
398     *     Single sign on token of identity performing the task.
399     * @param type
400     *     Identity type of this object.
401     * @param name
402     *     Name of the object of interest.
403     * @param membersType
404     *     IdType of members of name object.
405     * @return
406     *     Set of of members belongs to <code>name</code>
407     * @throws IdRepoException If there are repository related error conditions.
408     * @throws SSOException If identity's single sign on token is invalid.
409     */
410    public abstract Set<String> getMembers(SSOToken token, IdType type, String name,
411            IdType membersType) throws IdRepoException, SSOException;
412
413    /**
414     * Returns the memberships of an identity. For example, returns the
415     * groups or roles that a user belongs to.
416     *
417     * @param token
418     *     Single sign on token of identity performing the task.
419     * @param type
420     *     Identity type of this object.
421     * @param name
422     *     Name of the object of interest.
423     * @param membershipType
424     *     IdType of memberships to return.
425     * @return
426     *     Set of objects that <code>name</code> is a member of.
427     * @throws IdRepoException If there are repository related error conditions.
428     * @throws SSOException If identity's single sign on token is invalid.
429     */
430    public abstract Set<String> getMemberships(SSOToken token, IdType type,
431            String name, IdType membershipType) throws IdRepoException,
432            SSOException;
433
434    /**
435     * This method is used to assign a service to the given identity.
436     * The behavior of this method will be different, depending on
437     * how each plugin will implement the services model. The map
438     * of attribute-values has already been validated and default
439     * values have already been inherited by the framework.
440     * The plugin has to verify if the service is assigned (in which
441     * case it should throw an exception), and assign the service
442     * and the attributes to the identity (if supported).
443     *
444     *
445     * @param token
446     *     Single sign on token of identity performing the task.
447     * @param type
448     *     Identity type of this object.
449     * @param name
450     *     Name of the object of interest.
451     * @param serviceName
452     *     service to assign
453     * @param stype
454     * @param attrMap
455     *     Map of attribute-values.
456     * @throws IdRepoException If there are repository related error conditions.
457     * @throws SSOException If identity's single sign on token is invalid.
458     */
459    public abstract void assignService(SSOToken token, IdType type,
460            String name, String serviceName, SchemaType stype, Map<String, Set<String>> attrMap)
461            throws IdRepoException, SSOException;
462
463    /**
464     * Returns the set of services assigned to this identity.
465     * The framework has to check if the values are objectclasses,
466     * then map it to service names. Or if they are servicenames, then
467     * there is no mapping needed.
468     *
469     * @param token
470     *     Single sign on token of identity performing the task.
471     * @param type
472     *     Identity type of this object.
473     * @param name
474     *     Name of the object of interest.
475     * @param mapOfServicesAndOCs
476     * @return
477     *     Set of name of services assigned to <code>name</code>
478     * @throws IdRepoException If there are repository related error conditions.
479     * @throws SSOException If identity's single sign on token is invalid.
480     */
481    public abstract Set<String> getAssignedServices(SSOToken token, IdType type,
482            String name, Map<String, Set<String>> mapOfServicesAndOCs) throws IdRepoException,
483            SSOException;
484
485    /**
486     * If the service is already assigned to the identity then
487     * this method unassigns the service and removes the related
488     * attributes from the entry.
489     *
490     * @param token
491     *     Single sign on token of identity performing the task.
492     * @param type
493     *     Identity type of this object.
494     * @param name
495     *     Name of the object of interest.
496     * @param serviceName
497     *     Service name to remove.
498     * @param attrMap
499     *     Map of attribute-values to remove
500     * @throws IdRepoException If there are repository related error conditions.
501     * @throws SSOException If identity's single sign on token is invalid.
502     */
503    public abstract void unassignService(SSOToken token, IdType type,
504            String name, String serviceName, Map<String, Set<String>> attrMap)
505            throws IdRepoException, SSOException;
506
507    /**
508     * Returns the attribute values of the service attributes.
509     *
510     * @param token
511     *     Single sign on token of identity performing the task.
512     * @param type
513     *     Identity type of this object.
514     * @param name
515     *     Name of the object of interest.
516     * @param serviceName
517     *     Name of service.
518     * @param attrNames
519     *     Set of attribute names.
520     * @return
521     *     Map of attribute-values.
522     * @throws IdRepoException If there are repository related error conditions.
523     * @throws SSOException If identity's single sign on token is invalid.
524     */
525    public abstract Map<String, Set<String>> getServiceAttributes(SSOToken token, IdType type,
526            String name, String serviceName, Set<String> attrNames)
527            throws IdRepoException, SSOException;
528
529    /**
530     * Returns the requested binary attribute values of the service attributes
531     * as an array of bytes.
532     *
533     * @param token
534     *     Single sign on token of identity performing the task.
535     * @param type
536     *     Identity type of this object.
537     * @param name
538     *     Name of the object of interest.
539     * @param serviceName
540     *     Name of service.
541     * @param attrNames
542     *     Set of attribute names.
543     * @return
544     *     Map of attribute-values.
545     * @throws IdRepoException If there are repository related error conditions.
546     * @throws SSOException If identity's single sign on token is invalid.
547     */
548    public abstract Map<String, byte[][]> getBinaryServiceAttributes(SSOToken token, IdType type,
549            String name, String serviceName, Set<String> attrNames)
550            throws   IdRepoException, SSOException;
551
552    /**
553     * Modifies the attribute values of the service attributes.
554     *
555     * @param token
556     *     Single sign on token of identity performing the task.
557     * @param type
558     *     Identity type of this object.
559     * @param name
560     *     Name of the object of interest.
561     * @param serviceName
562     *     Name of service.
563     * @param sType
564     * @param attrMap
565     *     map of attribute-values.
566     * @throws IdRepoException If there are repository related error conditions.
567     * @throws SSOException If identity's single sign on token is invalid.
568     */
569    public abstract void modifyService(SSOToken token, IdType type,
570            String name, String serviceName, SchemaType sType, Map<String, Set<String>> attrMap)
571            throws IdRepoException, SSOException;
572
573    /**
574     * Adds a listener for changes in the repository
575     *
576     * @param token
577     *     Single sign on token of identity performing the task.
578     * @param listener
579     * @return status code
580     * @throws IdRepoException If there are repository related error conditions.
581     * @throws SSOException If identity's single sign on token is invalid.
582     */
583    public abstract int addListener(SSOToken token, IdRepoListener listener)
584            throws IdRepoException, SSOException;
585
586    /**
587     * Removes the listener added using <code> addListener </code> method. This
588     * is called by the IdRepo framework when the plugin is being shutdown due
589     * to configuration change, so that a new instance can be created with the
590     * new configuration map.
591     * 
592     */
593    public abstract void removeListener();
594
595    /**
596     * Return the configuration map
597     * 
598     * @return configuration map
599     */
600    public Map<String, Set<String>> getConfiguration() {
601        return configMap;
602    }
603
604    /**
605     * Returns the fully qualified name for the identity. It is expected that
606     * the fully qualified name would be unique, hence it is recommended to
607     * prefix the name with the data store name or protocol. Used by IdRepo
608     * framework to check for equality of two identities
609     * 
610     * @param token
611     *            administrator SSOToken that can be used by the datastore to
612     *            determine the fully qualified name
613     * @param type
614     *            type of the identity
615     * @param name
616     *            name of the identity
617     * 
618     * @return fully qualified name for the identity within the data store
619     * @throws IdRepoException If there are repository related error conditions.
620     * @throws SSOException If identity's single sign on token is invalid.
621     */
622    public String getFullyQualifiedName(SSOToken token, IdType type, 
623            String name) throws IdRepoException, SSOException {
624        return ("default://" + type.toString() + "/" + name);
625    }
626
627    /**
628     * Returns <code>true</code> if the data store supports authentication of
629     * identities. Used by IdRepo framework to authenticate identities.
630     * 
631     * @return <code>true</code> if data store supports authentication of of
632     *         identities; else <code>false</code>
633     */
634    public boolean supportsAuthentication() {
635        return (false);
636    }
637
638    /**
639     * Returns <code>true</code> if the data store successfully authenticates
640     * the identity with the provided credentials. In case the data store
641     * requires additional credentials, the list would be returned via the
642     * <code>IdRepoException</code> exception.
643     * 
644     * @param credentials
645     *            Array of callback objects containing information such as
646     *            username and password.
647     * 
648     * @return <code>true</code> if data store authenticates the identity;
649     *         else <code>false</code>
650     */
651    public boolean authenticate(Callback[] credentials) throws IdRepoException,
652            com.sun.identity.authentication.spi.AuthLoginException {
653        return (false);
654    }
655}