Creating User ID custom transformation types

Some authentication methods, such as SAML return the user ID a specific format that cannot be used directly because BMC Helix Single Sign-On does not provide a required option for transforming the user ID. In such situations, in addition to the default transformation options  provided by BMC Helix SSO, custom transformation options are required. 

As a user with system administrator privileges on the BMC Helix SSO server, you can create custom plugins to add complex transformations options to the Transformation list.

Perform the following tasks to create custom transformation IDs:


If you have BMC Helix SSO deployed in high availability mode, install the plug-in on all servers in the cluster before configuring a realm to use the new transformation.

Task 1: Verify the prerequisites are met

Before creating a new plugin, ensure the following prerequisites are met:

  • You must have JDK (not JRE) installed on the BMC Helix SSO server
  • The JAVA_HOME variable must point to the directory where the JDK is located.
  • On the BMC Helix SSO server, download the Apache Maven tool Open link archive.

Task 2: Create a new transformation plugin

  1. Unpack the Apache Maven tool archive to <maven_dir>.
  2. Add the PATH system variable path to the <maven dir>/bin directory.
  3. To check version,  run the following command:

    mvn –version
  4. Unpack the to CustomTransformationTemplate.
  5. Locate the BMC Helix SSO libraries folder. 
    Usually, it can be found in <RSSO Tomcat>/webapps/RSSO/WEB-INF/lib
  6. Find the sdk-plugins-<version>.jar file inside the path, and copy it into the CustomTransformationTemplate folder.
  7. Ensure that you have the correct dependencies set:
    • In the CustomTransformationTemplate/pom.xml file, check the <version > value inside the <dependency> element. If required, correct it according to the <version> part of the sdk-plugins-<version>.jar file.
    • In the CustomTransformationTemplate/build.cmd file, check the –Dversion argument in the first line and change it if required.

Task 3: Incorporate code changes

  1. Go to the CustomTransformationTemplate\java\src\main\java\com\bmc\rsso\plugins\transformation\custom folder.
    1. Create a copy of the file.
    2. Open this file and change the class name accordingly.
    3. Open CustomTransformationTemplate\ src\main\resources\META-INF\services\com.bmc.rsso.plugins.transformation.spi.UserIdTransformation file, and change the class name inside it accordingly.
  2. Open the .java file and make changes to the following functions:

    1. Content of the transform () function
    2. Returned value of the getStrategyName() function. 
      The return value is what you see in the console. Do not use any white spaces or special characters in the name.
    3. (Optional) Content of the getDescription() function. 
      This only leaves a comment when getDescription argument is used with Java. It does not change anything in the console or functionality.

Task 4: Build and deploy the new plugin

  1. Run the CustomTransformationTemplate/build.bat file.
    The newly created .jar file is located in CustomTransformationTemplate/target.
  2. Copy the .jar file into <RSSO Tomcat>/webapps/RSSO/WEB-INF/lib.


    If you need any additional libraries for the transformation plugin, save the libraries to the following directory: <RSSO Tomcat>/webapps/RSSO/WEB-INF/lib.

  3. Restart the BMC Helix SSO server.

Task 5: Verify the new transformation option is deployed to the BMC Helix SSO server

  1. Log in to the BMC Helix SSO Admin Console. 

  2. Navigate to the Realm tab, and open any available authentication method for editing.

  3. Verify the newly configured entry in available in the User ID Transformation list. 

Was this page helpful? Yes No Submitting... Thank you