You can post comments and questions regarding the documentation provided below on the Documentation Feedback Wiki Page. The page will open in a new window.

Building Custom Identity Repository Service Plug-ins

An identity repository is a data store where information about users and groups in a company or enterprise is stored. The OpenSSO Identity Repository Service is a model by which plug-ins can be written that allow communication with different types of identity repositories external to an installation of the OpenSSO server (including, for example, LDAP-based data stores and Novell and Oracle databases).

Identity Repository Service

The Identity Repository Service provides a pluggable framework for managing external data stores and databases. The main goals of the Identity Repository Service are:

To provide a list of identity repositories that can provide user attributes for purposes of authentication and authorization.
To combine the attributes and values obtained from different repositories.
To specify one or more identity repository per realm to store OpenSSO service configurations for users and roles.

The Java package com.sun.identity.idm contains the Identity Repository Service client interfaces provided by the AMIdentityRepository and AMIdentity classes. AMIdentityRepository allows access to one or more defined identity repositories and provides interfaces to search, create and delete identities. AMIdentity represents an identity (such as a user, a group, or a role) managed by the OpenSSO server and provides interfaces to set, modify and delete attributes, and to assign and unassign services. OpenSSO services such as the Policy Service and the Authentication Service use these interfaces to retrieve user attributes and to view membership data.

Default Identity Repository Service Plug-ins

com.sun.identity.idm.IdRepo is the interface that needs to be implemented by an Identity Repository Service plug-in. By default, the OpenSSO server includes the following plug-in implementations:

com.iplanet.am.sdk.AMSDKRepo is the implementation for Sun Java System Directory Server.
com.sun.identity.idm.plugins.ldapv3.LDAPv3Repo is the implementation for Active Directory, Generic Lightweight Directory Access Protocol version 3 (LDAPv3), and Sun Java System Directory Server with Access Manager Schema.
com.sun.identity.idm.plugins.files.FilesRepo is the implementation for the flat file repository.

You can configure for any of these identity repositories with the OpenSSO administration console by selecting the realm under which the repository will be defined and clicking the Data Stores tab.

Writing Custom Identity Repository Service Plug-ins

Following is the process to write a custom plug-in for the Identity Repository Service.

Write the plug-in module.
Modify idRepoService.xml to set up the plug-in's configuration parameters.
Modify amIdRepoService.properties to display the new plug-in and configuration parameters in the OpenSSO console.
Rebuild and redeploy the openfm.war.

To Write A Custom Plug-in for the Identity Repository Service

Implement the com.sun.identity.idm.IdRepo class.

The following methods should be implemented:

Note - The sample code is taken from com.sun.identity.idm.plugins.files.FilesRepo.java which can be viewed in the OpenSSO source code.

initialize(java.util.Map configParams): The initialization refers to the configuration parameters for the plug-in defined using the OpenSSO console. See step 3 of this procedure for more information on these parameters.

...
    /*
     * (non-Javadoc)
     * 
     * @see com.sun.identity.idm.IdRepo#initialize(java.util.Map)
     */
    public void initialize(Map configParams) {
        super.initialize(configParams);
        // Get the directory to store the identity information
        Set set = (Set) configParams.get(DIRECTORY);
        if (set != null && !set.isEmpty()) {
            directory = (String) set.iterator().next();
            try {
                initDir(directory);
            } catch (IdRepoException ide) {
                initializationException = ide;
                debug.error("FilesRepo: Init exception", ide);
            }
        }
...

getSupportedTypes() and getSupportedOperations(IdType type): getSupportedTypes() returns an IdType set (IdType.USER, IdType.ROLE, and so forth); basically the identities managed by the repository. getSupportedOperations(IdType type) returns an IdOperation set (IdOperation.READ, IdOperation.WRITE, and so forth); basically the operations which the repository supports.

...
    /*
     * (non-Javadoc)
     * 
     * @see com.sun.identity.idm.IdRepo#getSupportedOperations(
     *      com.sun.identity.idm.IdType)
     */
    public Set getSupportedOperations(IdType type) {
        return (Set) supportedOps.get(type);
    }

    /*
     * (non-Javadoc)
     * 
     * @see com.sun.identity.idm.IdRepo#getSupportedTypes()
     */
    public Set getSupportedTypes() {
        return supportedOps.keySet();
    }
...

isExists(), isActive(), getAttributes() (among others) are for identity-based operations

...
    /*
     * (non-Javadoc)
     * 
     * @see com.sun.identity.idm.IdRepo#isActive(com.iplanet.sso.SSOToken,
     *      com.sun.identity.idm.IdType, java.lang.String)
     */
    public boolean isActive(SSOToken token, IdType type, String name)
            throws IdRepoException, SSOException {
        if (initializationException != null) {
            debug.error("FilesRepo: throwing initialization exception");
            throw (initializationException);
        }
        Map attributes = getAttributes(token, type, name);
        if (attributes == null) {
            Object[] args = { NAME, name };
            throw new IdRepoException(IdRepoBundle.BUNDLE_NAME, "202", args);
        }
        Set activeVals = (Set) attributes.get(statusAttribute);
        if (activeVals == null || activeVals.isEmpty()) {
            return true;
        } else {
            Iterator it = activeVals.iterator();
            String active = (String) it.next();
            return (active.equalsIgnoreCase(statusActive) ? true : false);
        }
    }
...

addListener(...) and removeListener(...): The Identity Repository Service maintains a cache for user attributes and these methods are used to manage that cache. The service calls addListener(...) so the plug-in code should hold a pointer. When there is a change to an identity object, the listener object should be called to clear the cache.

...
/*
     * (non-Javadoc)
     * 
     * @see com.sun.identity.idm.IdRepo#addListener(com.iplanet.sso.SSOToken,
     *      com.iplanet.am.sdk.IdRepoListener)
     */
    public int addListener(SSOToken token, IdRepoListener listener)
            throws IdRepoException, SSOException {
        if (debug.messageEnabled()) {
            debug.message("FilesRepo addListener called");
        }
        repoListener = listener;
        return 0;
    }
...

Compile the classes, build a JAR, and put the JAR in the web-container-base/opensso/WEB-INF/lib directory of the staging directory created by the web container.
Look in your web container's documentation for the exact path.

Modify idRepoService.xml to create a schema for the plug-in's configuration parameters.

OpenSSO uses XML to define the configuration parameters for each plug-in. The schema for each plug-in is defined in idRepoService.xml using the <SubSchema> tag. For example, <SubSchema name="LDAPv3"> defines the configuration parameters for the generic LDAPv3 plug-in.

Note - idRepoService.xml can be viewed in the OpenSSO source code.

Each <AttributeSchema> defines the format and syntax for specific parameters to appear in the console.
The value of the i18nKey attribute of each <AttributeSchema> tag must map to a property defined in amIdRepoService.properties in order for the console to display the parameter name.
The sunIdRepoClass attribute must contain the fully qualified class name of the plug-in created in the previous step.
The i18nKey attribute of the <SubSchema> tag itself maps to the name of the plug-in defined in amIdRepoService.properties as it will be displayed as a data store option when you click New... under the Data Stores tab as in the screenshot below.

Following is the <SubSchema> code for the flat file repository plug-in.

                <SubSchema name="files"
                    inheritance="multiple"
                    i18nKey="a3000">
                    <AttributeSchema name="RequiredValueValidator"
                        type="validator"
                        syntax="string">
                        <DefaultValues>
                            <Value>com.sun.identity.sm.RequiredValueValidator</Value>
                        </DefaultValues>
                    </AttributeSchema>
                    <AttributeSchema name="sunIdRepoClass"
                        type = "single"
                        syntax = "string"
                        any="required"
                        validator="RequiredValueValidator"
                        i18nKey = "a3010">
                        <DefaultValues>
                            <Value>com.sun.identity.idm.plugins.files.FilesRepo</Value>
                        </DefaultValues>
                    </AttributeSchema>
                    <AttributeSchema name="sunFilesIdRepoDirectory"
                        type="single"
                        syntax="string"
                        validator="RequiredValueValidator"
                        i18nKey="a3020">
                        <DefaultValues>
                            <Value>@BASE_DIR@/@SERVER_URI@/idRepo/flatfiles</Value>
                        </DefaultValues>
                    </AttributeSchema>
                    <AttributeSchema name="sunFilesMonitorForChanges"
                        type="single"
                        syntax="boolean"
                        i18nKey="a3022">
                        <DefaultValues>
                            <Value>true</Value>
                        </DefaultValues>
                    </AttributeSchema>
                    <AttributeSchema name="sunFilesMonitoringTime"
                        type="single"
                        syntax="string"
                        i18nKey="a3024">
                        <DefaultValues>
                            <Value>1</Value>
                        </DefaultValues>
                    </AttributeSchema>
                    <AttributeSchema name="sunFilesObjectClasses"
                        type="list"
                        syntax="string"
                        i18nKey="a3026">
                        <DefaultValues>
                            <Value>inetorgperson</Value>
                            <Value>inetuser</Value>
                            <Value>organizationalperson</Value>
                            <Value>person</Value>
                            <Value>top</Value>
                        </DefaultValues>
                    </AttributeSchema>
                    <AttributeSchema name="sunFilesPasswordAttr"
                        type="single"
                        syntax="string"
                        i18nKey="a3030">
                        <DefaultValues>
                            <Value>userPassword</Value>
                        </DefaultValues>
                    </AttributeSchema>
                    <AttributeSchema name="sunFilesStatusAttr"
                        type="single"
                        syntax="string"
                        i18nKey="a3040">
                        <DefaultValues>
                            <Value>inetUserStatus</Value>
                        </DefaultValues>
                    </AttributeSchema>
                    <AttributeSchema name="sunFilesHashAttrs"
                        type="list"
                        syntax="string"
                        i18nKey="a3050">
                        <DefaultValues>
                            <Value>userPassword</Value>
                        </DefaultValues>
                    </AttributeSchema>
                    <AttributeSchema name="sunFilesEncryptAttrs"
                        type="list"
                        syntax="string"
                        i18nKey="a3060">
                    </AttributeSchema>
                </SubSchema>

Put the modified idRepoService.xml in the web-container-base/opensso/WEB-INF/classes directory of the staging directory created by the web container.
Look in your web container's documentation for the exact path.
Modify amIdRepoService.properties to display the plug-in's configuration parameters and names.
Information to do this is documented in Step 3.

Note - amIdRepoService.properties can be viewed in the OpenSSO source code.
Put the modified amIdRepoService.properties in the web-container-base/opensso/WEB-INF/classes directory of the staging directory created by the web container.
Look in your web container's documentation for the exact path.
Rebuild openfm.war and redeploy it.