Creating Custom Authentication Plugins in OAM 11gR2

Introduction

Plugins are one of the most useful and important features of Oracle Access Manager (OAM) when trying to customize the solution to meet an organization’s specific SSO requirements.

There are two types of plugins in OAM:

• Out of the box (OOB) plugins: There are many types of authentication plugins that come pre-packaged with OAM such as useridentification, userauthentication plugin, etc.
• Custom plugins: If/when OOB plugins won’t meet your requirements, OAM supports the ability for developers/integrators to extend the functionality of the product by way of custom plugins.

Creating Custom Plugins in OAM

Here, we’ve compiled a guide to walk you through the process for creating custom plugins for OAM 11gR2.

STEP 1: Create a sample java project, for this example we’ll call it SAMPLEPLUGIN.

STEP 2: Add these jars to the build path of the java project:

felix.jar,felix-service.jar,extensibility_lifecycle.jar,identity- provider.jar,oam-plugin.jar,utilities.jar.

The jars can be found at:  $OAM_DOMAIN/servers/oam_server1/tmp/_WL_user/oam_server_11.1.2.0.0/xxxx/APP-INF/lib/

STEP 3.  Create a class which should extend AbstractAuthenticationPlugIn and implements the process method. The process method contains the custom logic of the plugin.

STEP 4. Please note that the project name,class name and metadat.xml file name should match exactly.

STEP 5. The following code can be used to fetch the username and password from the login page:

CredentialParam keypassword =    context.getCredential().getParam(PluginConstants.KEY_USERNAME);

CredentialParam keypassword =  context.getCredential().getParam(PluginConstants.KEY_PASSWORD);

STEP 6. If you want to read any parameters which are declared in the xml file and need to be fetched at runtime then then this code may be used:

String stepName = context.getStringAttribute(PluginConstants.KEY_STEP_NAME);

String identityStoreRef =    PlugInUtil.getFlowParam(stepName,”KEY_IDENTITY_STORE_REF”, context);

STEP 7. This code may be used to authenticate users against the identity store:

provider = UserIdentityProviderFactory.getProvider(identityStoreRef);

boolean isAuthenticated =              provider.authenticateUser(this.userName,this.password);

STEP 8. If you would like to fetch a particular attribute of the authenticated user.

AuthnUser userauth = new AuthnUser();

userauth.setUserName(this.userName);

List<String> attributeNames = Arrays.asList(“cn”);

resultMap = provider.getUserAttributes(userauth, attributeNames);

String resultAttributeValue = resultMap.get(“cn”);

STEP 9. If you are authenticating any user, the following are mandatory responses which need to be set.

if(isAuthenticated){

status = ExecutionStatus.SUCCESS;

subject.getPrincipals().add(new OAMUserPrincipal(this.userName));

subject.getPrincipals().add(new OAMUserDNPrincipal(“cn=”+this.userName+”,dc=user,dc=com”));

subject.getPrincipals().add(new OAMGUIDPrincipal(this.userName));

context.setSubject(subject);

/*Setting first response*/

PluginResponse rsp = new PluginResponse();

rsp.setName(PluginConstants.KEY_RETURN_ATTRIBUTE);

rsp.setType(PluginAttributeContextType.LITERAL);

rsp.setValue(provider.getReturnAttributes());

context.addResponse(rsp);

/*Setting second response*/

IDPAdmin idpAdmin = UserIdentityProviderFactory.getIDPAdmin();

String runtimeIDStore = idpAdmin.getDefaultProviderName();

rsp = new PluginResponse();

rsp.setName(PluginConstants.KEY_IDENTITY_STORE_REF);

rsp.setType(PluginAttributeContextType.LITERAL);

rsp.setValue(runtimeIDStore);

/*Setting third response*/

rsp.setName(PluginConstants.KEY_AUTHENTICATED_USER_NAME);

rsp.setType(PluginAttributeContextType.LITERAL);

rsp.setValue(this.userName);

context.addResponse(rsp)

}

STEP 10:  To set custom responses in the plugin use this code:

/* Custom responses*/

rsp = new PluginResponse();

rsp.setName(“ResultParameter”);

rsp.setType(PluginAttributeContextType.SESSION);

rsp.setValue(resultAttributeValue);

context.addResponse(rsp);

*This plugin response can be fetched by using $session.attr.ResultParameter in the policy response.*

STEP 11:  If you have any third party jars then create a folder lib at the same level as of src and add the jars to the folder.

STEP 12: Create a folder META-INF under src folder and create a file MANIFEST.MF in it.

STEP 13: Following is how the contents of the MANIFEST file will appear, where the Bundle-Name and Bundle-SymbolicName are same as the project name. Please note: if you have any third party jars you include them under Bundle-ClassPath.

STEP 14: Create a metadata xml (SAMPLEPLUGIN.xml) under src folder whose file name should be same as project name. Note that the plugin name used in this xml will be displayed once your plugin is imported successfully in OAM.

STEP 15: To create the jar in eclipse right click on project->export->JAVA->jar.

STEP 16: After that click next it will ask for jar name(SAMPLEPLUGIN.jar) which should be the same as the project name.

STEP 17: Then click on next->next it has two option either generate the manifest file or use an existing manifest file. Select use an existing manifest file and select the manifest file that you created.

STEP 18: Upload the jar using OAM console. Navigate to System configurations->Plugins->import plugin and select the jar created.

STEP 19: Once the jar is uploaded its status will change to uploaded.

STEP 20: Select the plugin and click on distribute and refresh the table.  Now the plugin status will change to distributed.

STEP 21: Now select the plugin and click on Activate Selected to activate the plugin for its use.

Congratulations! You’ve successfully created a custom Oracle Access Manager plugin. Hopefully, this guide helped you along the way. If you still have questions or are stuck, reach out to us and we’ll see if we can help.