How to extend the Platform with plugins?

1 Developing a custom Token Enhancer for the Identity Manager
- 1.1 New maven project
- 1.2 Developing the functionality
- 1.3 Build the JAR
- 1.4 Define the URI of the plugin in the Identity Manager (Oauth Server)
- 1.5 JWT Token: test
- 1.6 Resources

In this guide we are going to explain how you to extend the platform functionality by developing plugins.

This feature is only available in the Enteprise version.

Furthermore, it is currently in PREVIEW state, so when if a product wants to use it, please refer support@onesaiplatform.com for activation.

Developing a custom Token Enhancer for the Identity Manager

Suppose you want to customize the way the JWT token is built at the Identity Manager.

New maven project

First of all, start by creating a new maven project on which you’ll develop the proposed functionality.

In order to guarantee 100% compatibility with the platform’s modules, version 1.5.9.RELEASE of Spring Boot and Java 1.8 should be used.

Developing the functionality

Let's start by creating a class that implements the interface TokenEnhancer on where we are going to add a simple property to the Oauth Access Token.

In order for the Authorization Server to use this Enhancer, you’ll need to create a @Configuration class which will extend AuthorizationServerConfigurerAdapter. In such class, you’ll override the method which configures the endpoints.

In this configure method, you’ll add the PluginTokenEnhancer itself to the existing Token Enhancer Chain:

In this way, your enhancer will be applied as the last link of the Enhancer Chain, before building the final JWT token.

In this Configuration class, you will declare a @PostConstruct to modify de TokenServices in order to add the enhancer:

package com.minsait.onesait.platform.plugin.configuration;

import java.util.Arrays;

import javax.annotation.PostConstruct;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Lazy;
import org.springframework.security.oauth2.provider.token.DefaultTokenServices;
import org.springframework.security.oauth2.provider.token.TokenEnhancer;
import org.springframework.security.oauth2.provider.token.TokenEnhancerChain;
import org.springframework.security.oauth2.provider.token.store.JwtAccessTokenConverter;

import com.minsait.onesait.platform.plugin.utils.PluginTokenEnhancer;

@Configuration
@Lazy(false)
public class AuthorizationServerConfigurer {

	@Autowired
	DefaultTokenServices tokenServices;

	@Autowired
	private JwtAccessTokenConverter jwtAccessTokenConverter;

	@Autowired
	private TokenEnhancer tokenEnhancer;

	@PostConstruct
	public void modifyServices() {
		final TokenEnhancerChain chain = new TokenEnhancerChain();
		chain.setTokenEnhancers(Arrays.asList(tokenEnhancer, jwtAccessTokenConverter, pluginTokenEnhancer()));
		tokenServices.setTokenEnhancer(chain);
	}

	public TokenEnhancer pluginTokenEnhancer() {
		return new PluginTokenEnhancer();
	}
}

Build the JAR

Lightweight JAR

You will use this method when NOT using external dependencies that Spring Boot does not bring

For the Identity Manager to use the plugin, you’ll need to package the project into a JAR file, either with mvn clean install or mvn clean package

Once the JAR is built, you shall upload it to a server accesible from the internet, or at least accesible from the server where the platform is deployed.

This server or repository could be for example a Nexus, where you’ll copy the link to the JAR file:

https://nexus.onesaitplatform.com/nexus/service/local/repositories/releases/content/com/minsait/onesait/platform/onesaitplatform-base-plugin/1.0.0/onesaitplatform-base-plugin-1.0.0.jar

Or it could be the binary repository of the platform itself:

https://development.onesaitplatform.com/controlpanel/files/5e71fb0e7ec58a000bf6f966

Please note that whatever the repository is, the file needs to be public, as the Identity Manager will try to download it without any kind of authentication.

FAT JAR

You will use this method whenever you DO use external dependencies that does not come with Spring Boot

The process is slightly different. In this case you’ll want to add the maven assembly plugin to your pom.xml

<build>
	<plugins>
		<plugin>
			<artifactId>maven-assembly-plugin</artifactId>
			<configuration>
				<descriptorRefs>
					<descriptorRef>jar-with-dependencies</descriptorRef>
				</descriptorRefs>
			</configuration>
			<executions>
				<execution>
					<id>make-assembly</id> 
					<phase>package</phase> 
					<goals>
						<goal>single</goal>
					</goals>
				</execution>
			</executions>
		</plugin>
	</plugins>
</build>

Then you’ll generate your plugin with mvn package

Keep in mind that this will generate a JAR with all dependencies, and therefore considerably increase the size of the plugin.

Define the URI of the plugin in the Identity Manager (Oauth Server)

As the last step, you’ll need to let the module know where the plugin is, this is done by setting the environment variable PLUGIN_URI to the URI(s) where the JAR is located. In case there is more than one plugin, URIs must be separated with the character ';'

Now at the startup, the identity manager will attempt to find and load the plugins:

JWT Token: test

Finally, you can test your plugin by making a request to the Identity Manger and check for the new parameter that your Enhancer is adding.