OpenSSO Data Store plugins must implement the class com.sun.identity.idm.IdRepo. This class has a number of abstract methods which must be implemented, and some other methods whose default implementation must be overriden in order to be able to provide a useful service.

Our IdRepo will be implemented in terms of a simplistic JDBC Data Access Object.

In order for OpenSSO to be able to load our plugin, the IdRepo subclass must have a no-args constructor for OpenSSO to call.

When OpenSSO loads our plugin, it will call its initialize() method. We use this opportunity in our implementation to initialize the Data Access Object.

There is also a chance to perform any cleanup needed when OpenSSO is finished with our plugin, by overriding the shutdown() method.

The IdRepo class also requires that implementations provide addListener() and removeListener() methods. While it is not entirely clear what these methods are for, OpenSSO will not be able to use our plugin correctly if they raise exceptions, so we provide basic no-op implementations.

	public void initialize(Map configParams) {
	      super.initialize(configParams);
	      dao = new IdDAO();
	      try {
		      dao.init();
	      } catch (SQLException e) {
		      e.printStackTrace();
	      }
      }

      public void shutdown() {
	      super.shutdown();
      }

      public int addListener(SSOToken token, IdRepoListener listener)
	      throws IdRepoException, SSOException
      {
	      // TODO: no idea what this needs to do
	      return 0;
      }

      public void removeListener() {
	      // TODO: no idea what this needs to do
      }

Data Stores can have varying capabilities in terms of the kind of subjects they support and the operations that they will perform on those subjects. In order to tell OpenSSO what our plugin is capable of we need to override the methods getSupportedTypes(), getSupportedOperations(IdType) and supportsAuthentication().

If you look at the example code, you will see that we implement these methods to declare that we only support the USER identity-type, the operations CREATE, READ and EDIT on these identities, and return true from supportsAuthentication().

	private static final Set SUPPORTED_TYPES;
	static {
		SUPPORTED_TYPES = new HashSet();
		SUPPORTED_TYPES.add(IdType.USER);
	}

	private static final Set SUPPORTED_OPS;
	static {
		SUPPORTED_OPS = new HashSet();
		// TODO: DELETE?  &  SERVICE?
		SUPPORTED_OPS.add(IdOperation.READ);
		SUPPORTED_OPS.add(IdOperation.CREATE);
		SUPPORTED_OPS.add(IdOperation.EDIT);
	}
	
	public Set getSupportedOperations(IdType type) {
		return SUPPORTED_OPS;
	}

	public Set getSupportedTypes() {
		return SUPPORTED_TYPES;
	}

	public boolean supportsAuthentication() {
		return true;
	}

Having declaired that we support CREATE, READ, EDIT and authentication for OpenSSO USER subjects, we need to provide implementations for the relevant methods of IdRepo for OpenSSO to call upon.

Other methods which we must implement (because they are abstract in IdRepo), but which provide unsuppored operations are simply implemented to raise IdRepoUnsupportedOpException.

The operations that we do implement all assert that the IdType argument they are passed is IdType.USER, enforcing the contract we've declared.

	public String create(SSOToken token, IdType type, String name,
	                     Map attrMap)
		throws IdRepoException, SSOException
	{
		assertUserType(type);
		User newUser = userFromAttributes(name, attrMap);
		try {
			dao.insertUser(newUser);
		} catch (SQLException e) {
			throw new IdRepoException(e.toString());
		}
		// TODO: "string representation of created value" wha?
		return "["+name+"]";
	}

	public boolean isExists(SSOToken token, IdType type, String name)
		throws IdRepoException, SSOException
	{
		assertUserType(type);
		try {
			return dao.loadUser(name) != null;
		} catch (SQLException e) {
			throw new IdRepoFatalException(e.toString());
		}
	}
	
	public boolean isActive(SSOToken token, IdType type, String name)
		throws IdRepoException, SSOException
	{
		// We could load the entry from the database to check a status
		// flag, but our simple schema doesn't define one; all user
		// accounts are always enabled. 
		assertUserType(type);
		return true;
	}

	public Map getAttributes(SSOToken token, IdType type, String name)
			throws IdRepoException, SSOException
	{
		assertUserType(type);
		User user;
		try {
			user = dao.loadUser(name);
		} catch (SQLException e) {
			throw new IdRepoException(e.toString());
		}
		return toAttrs(user);
	}

	public Map getAttributes(SSOToken token, IdType type, String name, Set attrNames)
		throws IdRepoException, SSOException
	{
		// TODO: should filter the results to reflect requested attrs,
		// but for the moment, lets just return then all,
		return getAttributes(token, type, name);
	}

	public Map getBinaryAttributes(SSOToken token, IdType type, String name, Set attrNames)
		throws IdRepoException, SSOException
	{
		assertUserType(type);
		// we don't have any binary attributes,
		return Collections.EMPTY_MAP;
	}

	public RepoSearchResults search(SSOToken token, IdType searchType,
			String pattern, int maxTime, int maxResults,
			Set returnAttrs, boolean returnAllAttrs, int filterOp,
			Map avPairs, boolean recursive)
		throws IdRepoException, SSOException
	{
		assertUserType(searchType);
		if ("*".equals(pattern)) {
			// TODO: other 'glob'-like matches allowed?
			pattern = null;
		}
		List users;
		Map queryParams = avPairs==null ? null : remap(avPairs);
		try {
			users = dao.search(pattern, maxResults, queryParams, filterOp);
		} catch (SQLException e) {
			throw new IdRepoException(e.toString());
		}
		Set searchResults = toDNSet(users);
		int errorCode = RepoSearchResults.SUCCESS;
		Map resultsMap = toEntryAttributeSetMap(users);
		return new RepoSearchResults(searchResults,
		                             errorCode,
		                             resultsMap,
		                             searchType);
	}

	public void setAttributes(SSOToken token, IdType type, String name, Map attributes, boolean isAdd)
		throws IdRepoException, SSOException
	{
		// TODO: not sure what isAdd indicates
		assertUserType(type);
		try {
			// load user and copy changed properties
			User user = dao.loadUser(name);
			Map props = attrMapToPropMap(attributes);
			copyProperties(user, props);
			dao.updateUser(user);
		} catch (SQLException e) {
			e.printStackTrace();
			throw new IdRepoException(e.toString());
		}
	}

	public void setBinaryAttributes(SSOToken token, IdType type, String name, Map attributes, boolean isAdd)
		throws IdRepoException, SSOException
	{
		assertUserType(type);
		// don't support any binary attributes, so nothing to do
	}

	public void removeAttributes(SSOToken token, IdType type, String name, Set attrNames)
		throws IdRepoException, SSOException
	{
		assertUserType(type);
		// at the moment, there are no attributes that can resonably be
		// removed.  We could in theory set the columns to 'null' in
		// the database, except we've deliberately defined the columns
		// to dissallow this.
	}

	public boolean authenticate(Callback[] credentials) throws IdRepoException, AuthLoginException {
		// Obtain user name and password from credentials and authenticate
		String username = null;
		String password = null;
		for (int i = 0; i < credentials.length; i++) {
			Callback cred = credentials[i];
			if (cred instanceof NameCallback) {
				username = ((NameCallback)cred).getName();
			} else if (cred instanceof PasswordCallback) {
				char[] passwd = ((PasswordCallback)cred).getPassword();
				if (passwd != null) {
					password = new String(passwd);
				}
			}
		}
		if (username == null || password == null) {
			Object args[] = { getClass().getName() };
			throw new IdRepoException(IdRepoBundle.BUNDLE_NAME, "221", args);
		}
		User user;
		try {
			user = dao.loadUser(username);
		} catch (SQLException e) {
			throw new IdRepoException(e.toString());
		}
		return user != null && password.equals(user.getPassword());
	}

To see the utility methods used in implementing the public interface above, and the the source code for the Data Access Object, take a look at the full source of JDBCIdRepo, IdDAO, User and PropertyNameRemapper.

This section attempts to describe how OpenSSO will actually use our plugin to perform different actions.

We will create a realm to test the IdRepo implementation within. Log in to the admin OpenSSO console and click New.. in 'Realms':

On the subsequent 'New Realm' screen, enter a name for the realm, and select OK, leaving all other settings at their default values:

Select the realm which we just added:

Now, in the configuration screen for the 'test' realm, select the 'Data Stores' tab:

Now click New.. in the 'Data Stores' section:

We are now prompted for the name and type for the new datastore. The type selected must be Access Manager Repository Plug-in. After entering a name, click Next:

The configurables for the repository plugin must now be supplied. On the step 2 screen, enter the name of our IdRepo implementation class. Leaving all other configuration settings as they are, click Finish:

If there are any problems loading this plugin, exception stacktraces will appear in $CONFIG_DIR/opensso/debug/amIdm (assuming you have debugging emabled in $CONFIG_DIR/AMConfig.properties).

If, once loaded, the console has problems using the plugin, exception stacktraces will be logged to $CONFIG_DIR/opensso/debug/amConsole

Finally, delete the default flat-file datastore that was created with the realm by ticking the box next to 'files' in the Data Stores list and then clicking Delete

Select the 'Subjects' tab within the 'test' realm configuration. Ensure that things like adding new users and selecting / editing users attiributes works as expected:

Note that the sub-tabs appearing under the 'Subjects' tab should corespond with the values returned by the getSupportedTypes() method of your IdRepo implementation.

For our 'test' realm, select the 'Authentication' tab:

On the 'Authentication' page, scrolling down past the 'General' section should reveal the 'Module Instances'. Select New for 'Module Instances':

On the New Modual Instance page, enter the name 'testDataStore', select type 'Data Store', and select OK:

Back on the 'test' realm authentication page, we now need to create an authentication chain making use of the authentication module instance we just created. Select New in the 'Authentication Chaining' area:

On the 'New Authentication Chain' page, enter a name, 'testservice' for the new chain, and select OK:

The next page allows us to specify properties for the new chain. There are are initially no entries in the chain, so select Add:

A new entry will be added to the list. This entry should have 'Instance' set to 'testDataStore' and 'Criteria' set to 'REQUIRED'. Select Save and then Back to Authentication to finish the new authentication chain:

Finally, remove the default LDAP authentication configuration by deleting first the 'ldapservice' authentication chain, and then the 'LDAP' module instance: