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