Groovy Script connector

Background

To integrate with various applications and support Joiner, Mover, and Leaver processes, OpenIAM utilizes connectors. The role of connectors within the OpenIAM architecture is detailed in this document.

OpenIAM provides a variety of out-of-the-box connectors for commonly used on-premises and SaaS applications, such as Active Directory (AD), Entra ID, AWS, Google Workspace, SAP HANA, Oracle EBS, and more. These connectors enable seamless integration between OpenIAM and target applications by implementing an organization’s business requirements with minimal effort.

However, organizations often need to integrate OpenIAM with custom applications that lack a pre-built connector. These applications may have unique data structures, authentication mechanisms, or API endpoints, making standard connectors (e.g., SCIM or database connectors) insufficient. In such cases, organizations require a flexible integration approach that allows them to define their own logic while leveraging OpenIAM infrastructure.

To address these requirements, OpenIAM offers the following integration options.

• Groovy Script Connector. This is a connector framework based on Groovy, allowing implementers to focus on integration logic within Groovy scripts while OpenIAM handles the core connector functionality.
• PowerShell Script Connector being a connector framework based on .NET & PowerShell, enabling implementers to focus on integration logic in PowerShell scripts without needing to implement the core connector logic.
• Custom Java Connector is a fully custom connector developed in Java. This approach offers maximum flexibility but requires more development time compared to the scripted options above.

This documentation focuses on the Groovy Script Connector, explaining its capabilities, structure, and implementation guidelines.

Introducing the Groovy Script Connector

The Groovy Script Connector in OpenIAM provides organizations with a flexible and highly customizable approach to integration. Unlike standard connectors, this solution enables the implementation of custom business logic tailored to the specific requirements of a target system.

With this approach, organizations can leverage Groovy scripts to interact with external applications while benefiting from OpenIAM core infrastructure, including RabbitMQ for message queuing and provisioning/deprovisioning tasks. This ensures that critical operations, such as creating, updating, and deleting accounts—are executed efficiently, securely, and reliably.

Beyond standard API calls, the Groovy Script Connector supports multiple integration methods, including:

• REST API interactions, which supports HTTP requests (GET, POST, PUT, DELETE) for seamless communication with modern web services.
• SOAP API integration enabling interaction with legacy systems using XML-based web services.
• PL/SQL package execution, which allows direct execution of stored procedures in databases for advanced data operations.
• Shell script invocation that facilitates automation of system-level tasks by running scripts on the underlying infrastructure.

This versatility enables organizations to build robust, scalable, and secure integrations that align with their specific requirements.

Real-life example

Many organizations manage user data using systems that expose REST APIs but lack direct integration with OpenIAM. To address this, they often rely on manual data synchronization, such as exporting and importing CSV files, or develop custom scripts to automate data transfers.

While these homegrown scripting solutions may work initially, they become difficult to maintain over time, especially as business requirements evolve. When multiple applications are involved, different teams may implement inconsistent approaches, leading to integration challenges and higher maintenance overhead.

By leveraging the Groovy Script connector, organizations can replace manual processes and fragmented scripts with a centralized, scalable, and maintainable integration framework. The connector allows OpenIAM to directly interact with the target system’s REST APIs, ensuring seamless, automated data synchronization. This provides key benefits such as:

• Eliminating manual effort. There is no need for time-consuming file exports and imports.
• Reducing errors. Automates data transfers to prevent inconsistencies.
• Standardizing integrations. Ensures a consistent approach across multiple applications.
• Improving maintainability. Reduces reliance on custom scripts that become difficult to manage over time.

By replacing manual processes and ad-hoc scripting with automated, near real-time integration, the Groovy Script connector enhances accuracy, efficiency, and long-term maintainability, enabling organizations to focus on more strategic initiatives.

Essential preparations for implementation (using REST APIs)

Before deploying the Groovy Script connector, certain prerequisites must be met to ensure a successful and secure integration. These include API readiness, proper security configurations, and authentication mechanisms.

1. API readiness and configuration.

To facilitate communication between OpenIAM and the custom application, the following API endpoints should be available:

• POST API for creating users enables the creation of new user accounts.
• GET API for retrieving user information allows OpenIAM to fetch user details based on search parameters.
• PUT API for updating user information supports modifying user attributes.
• DELETE API for removing users handles account deletion.

2. Ensuring secure integration practices. To ensure secure API communication, organizations should implement the following security measures:

• Use HTTPS for communication. Encrypt data transmission to prevent unauthorized access.
• Implement OAuth 2.0 with bearer tokens. OpenIAM recommends using OAuth 2.0 for secure authorization, where the connector requests an access token before calling the API and refreshes it automatically when expired.
• Enable certificate-based authentication. Store required certificates securely on the OpenIAM server
• Other authentication methods (not recommended).
  • API Key authentication, which uses a unique identifier but is less secure than OAuth 2.0.
  • Basic authentication sends a username and password in request headers, requiring HTTPS to prevent exposure.

By following these preparation steps, organizations can ensure a smooth and secure integration using the Groovy Script Connector, enabling seamless communication between OpenIAM and their custom applications. The following illustration represents the process using a flow diagram.

Configuring OpenIAM

This section provides an overview of the various operations supported by the Groovy Script Connector and outlines the required configurations for its setup.

The connector supports various operations, including save, search, test connection, delete, resume, suspend, and reset password. However, authentication operations, such as login, are not currently supported.

OpenIAM offers a built-in Groovy Script Connector, which can be accessed through the webconsole by navigating to Provisioning > Connectors. To configure the connector, navigate to the Connector Configuration menu and modify its settings as needed. Ensure that the required rules are enabled based on your specific requirements.

Each rule displayed in the screenshot below can trigger a Groovy script, facilitating CRUD and search operations on target applications.

Important considerations

1. Synchronization setup. If you plan to use the Groovy Script Connector for synchronization, we strongly recommend enabling the Test Connection Object rule along with the provided script. Without this, the synchronization process will fail with an error indicating an inability to connect to the target system.
2. Save handler usage. Due to the current legacy implementation, the Save Handler should be used for both Add and Modify provisioning rules to ensure proper functionality.

3. When configuring Groovy script connector on the OpenIAM side consider that SQL Query / Directory filter and Source attribute names fields are mandatory. In case these are left empty, the following error may occur.

Configuring Managed System

Secure connection details can be stored using fields such as login, password, host URL, port, and connection string. These credentials can then be accessed within the Groovy script handler to facilitate provisioning operations.

Ensure that the rule fields are properly filled, with each field containing the path to the appropriate operation handler (path of groovy scripts).

Connection details can be used while establish connection or performing operations on target applications. Example usage through code is given below.

final String login = connectorObject.getMetaData().getLogin(); 
final String password = connectorObject.getMetaData().getPassword(); 
final String hostURL = connectorObject.getMetaData().getUrl(); 
final Integer port = connectorObject.getMetaData().getPort(); 
final String connectionString =  ConnectorObjectUtils.readMetadataAttributeValue(connectorObject.getMetaData(), ProvisionConnectorConstant.CONNECTION_STRING); // Custom Attributes stored in managed Sys Config

Integrating with the Script Connector (using REST APIs)

The integration process can be divided into two parts:

1. Defining the API structure, including endpoint setup, request formats, and response handling.
2. Developing Groovy scripts to serve as a bridge, enabling seamless communication between OpenIAM and the target system.

User lifecycle operations in OpenIAM

To fully support user life-cycle management, OpenIAM connector model includes the following key operations:

• Save manages both account creation and updates in the target system
• Search facilitates individual and bulk user lookups based on synchronization configuration parameters.
• Delete removes an account from the target system.
• Resume reactivates a suspended account.
• Suspend disables an active account.
• Test Connection verifies the connectivity to the target system.
• Login enables authentication into OpenIAM using the integrated application.

Below are some best practices for designing application-level integration APIs, focusing on security considerations and the key parameters required for each operation.

Security best practices for API integration

To ensure secure integration, the application’s API should be protected using the following measures:

• Use HTTPS for communication. It is strongly recommended for encrypting data transmission and enhancing security.
• Require a Valid Bearer Token (OAuth 2.0). The OpenIAM connector requests and stores an access token, automatically refreshing it when expired.
• Avoid less secure authentication methods (that are not recommended):
  • API Key authentication, which uses a unique identifier in request headers or query parameters.
  • Basic authentication? which sends a Base64-encoded username and password, requiring HTTPS for protection.
• Certificate-based authentication. Enhances security by using stored certificates for authentication. The required certificate must be placed on the OpenIAM server, ensuring accessibility for the connector.

API operations

The OpenIAM Groovy Script Connector requires several API operations to manage user life-cycle events. Below there is a structured overview of each operation, including purpose, API requests, and expected responses.

1. Save (create/update User). The Save operation manages user creation and updates in the target system. It consists of multiple API calls, such as

• Check if the user exists. Before creating or updating a user, OpenIAM checks if the user already exists.

API request

GET /user?username=abc 

Responses

✅ 200 SUCCESS – User object found.
❌ 404 NOT FOUND – User does not exist.
❌ 500 INTERNAL SERVER ERROR – Unexpected error.

• Create a user. If the user does not exist, OpenIAM creates a new user.

API request

POST /add-user

Sample payload

{
  "username": "john.doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phoneNumber": "123-456-7890",
  "roles": [
    {
      "operation": "ADD",
      "name": "user",
      "startDate": "2023-01-01",
      "endDate": "2023-12-31",
      "description": "123123132"
    }
  ],
  "status": "Active",
  "password": "Passwd00"
}

Responses

✅ 200 SUCCESS – User created successfully.
❌ 400 BAD REQUEST – Incorrect request format.
❌ 500 INTERNAL SERVER ERROR – Unexpected error.

• Update an existing user. If the user exists, OpenIAM updates the user's details.

API request

PUT /update-user 

Sample Payload: (Contains only fields to be updated)

{
  "username": "john.doe",
  "phoneNumber": "123-456-7890",
  "roles": [
    {
      "operation": "DELETE",
      "name": "user"
    },
    {
      "operation": "ADD",
      "name": "admin"
    }
  ]
}

Responses

✅ 200 SUCCESS – User updated successfully.
❌ 400 BAD REQUEST – Incorrect request format.
❌ 500 INTERNAL SERVER ERROR – Unexpected error.

2. Search (retrieve users). The Search API fetches user data based on filters.

• Search for active users in a Group

API request

POST /usersCopyEdit

Payload

{
  "group": "engineering",
  "isActive": true
}

• Search for all active users.

{
  "isActive": true
}

• Search for users modified since a specific date.

{
  "lastModified": "2023-01-01"
}

Response format

✅ 200 SUCCESS – Returns a list of user objects.

3. Delete (remove a user). Deletes a user from the system.

API request

DELETE /user/{username}

Responses

✅ 200 SUCCESS – User deleted successfully.
❌ 400 BAD REQUEST – Deletion failed due to system rules.
❌ 500 INTERNAL SERVER ERROR – Unexpected error.

4. Reset password. Changes or resets a user’s password.

API request

POST /reset-password

Sample payload

{
  "username": "1234567890",
  "newPassword": "newPassword456"
}

Responses

✅ 200 SUCCESS – Password reset successfully.
❌ 400 BAD REQUEST – Password policy violations.
❌ 500 INTERNAL SERVER ERROR – Unexpected error.

5. Resume (enable user account). Reactivates a suspended account.

API request

POST /enable/{username} 

Responses

✅ 200 SUCCESS – Account enabled.
❌ 400 BAD REQUEST – Unable to enable the account.
❌ 500 INTERNAL SERVER ERROR – Unexpected error.

6. Suspend (disable user account). Disables an active account.

API request

POST /disable/{username}

Responses

✅ 200 SUCCESS – Account suspended.
❌ 400 BAD REQUEST – Unable to suspend the account.
❌ 500 INTERNAL SERVER ERROR – Unexpected error.

7. Test connection. Checks the connection between OpenIAM and the target system.

API request

GET /user?username=abc

Responses

✅ 200 SUCCESS – Connection is active.
❌ 400 BAD REQUEST – Connection issues detected.
❌ 500 INTERNAL SERVER ERROR – Unexpected error.

8. Login (authentication into OpenIAM). Allows authentication using the target system as an identity provider.

API request

POST /verify-credentials

Sample payload

{
  "username": "1234567890",
  "password": "newPassword456"
}

Responses

✅ 200 SUCCESS – Authentication successful.
❌ 400 BAD REQUEST – Invalid credentials or user status.
❌ 500 INTERNAL SERVER ERROR – Unexpected error.

Groups management using OpenIAM Groovy Script connector

The OpenIAM Groovy Script Connector can also be used for Group management, including operations like searching for groups, creating groups and removing groups. Below there is a structured overview of each operation, including purpose, API requests, and expected responses.

1. Search group. The connector retrieves a list of groups based on search criteria.

• Endpoint to get a specific Group by name is given below.

GET /api/groups/search?name=Developers 

Sample JSON request

{
  "groups": [
    {
      "id": "101",
      "groupName": "Developers",
      "description": "Group for software development team",
      "status": "Active",
      "createdDate": "2023-02-10T12:00:00Z",
      "members": [
        {
          "id": "201",
          "username": "john.doe",
          "firstName": "John",
          "lastName": "Doe",
          "email": "john.doe@example.com"
        },
        {
          "id": "202",
          "username": "jane.smith",
          "firstName": "Jane",
          "lastName": "Smith",
          "email": "jane.smith@example.com"
        }
      ]
    }
  ]
}

Responses

✅ 200 SUCCESS – Returns List of Groups Objects.
❌ 400 BAD REQUEST – Invalid credentials or user status.
❌ 500 INTERNAL SERVER ERROR – Unexpected error.

• Endpoint to get all Groups is as follows.

GET /api/groups

Sample JSON request

{
  "groups": [
    {
      "id": "101",
      "groupName": "Developers",
      "description": "Group for software development team",
      "status": "Active",
      "createdDate": "2023-02-10T12:00:00Z",
      "members": [
        {
          "id": "201",
          "username": "john.doe",
          "firstName": "John",
          "lastName": "Doe",
          "email": "john.doe@example.com"
        },
        {
          "id": "202",
          "username": "jane.smith",
          "firstName": "Jane",
          "lastName": "Smith",
          "email": "jane.smith@example.com"
        }
      ]
    },
    {
      "id": "102",
      "groupName": "DevOps Team",
      "description": "Group for DevOps engineers",
      "status": "Active",
      "createdDate": "2023-03-15T14:30:00Z",
      "members": [
        {
          "id": "203",
          "username": "alex.johnson",
          "firstName": "Alex",
          "lastName": "Johnson",
          "email": "alex.johnson@example.com"
        }
      ]
    },
    {
      "id": "103",
      "groupName": "HR Team",
      "description": "Group for human resources",
      "status": "Active",
      "createdDate": "2023-04-05T10:20:00Z",
      "members": []
    },
    {
      "id": "104",
      "groupName": "Finance",
      "description": "Group for finance department",
      "status": "Inactive",
      "createdDate": "2023-01-20T09:15:00Z",
      "members": [
        {
          "id": "204",
          "username": "michael.brown",
          "firstName": "Michael",
          "lastName": "Brown",
          "email": "michael.brown@example.com"
        }
      ]
    }
  ]
}

Responses

✅ 200 SUCCESS – Returns list of Groups objects.
❌ 400 BAD REQUEST – Invalid credentials or user status.
❌ 500 INTERNAL SERVER ERROR – Unexpected error.

2. Save Group. Here, connector creates groups based on provided information.

Endpoint is as follows.

POST /api/groups

Sample JSON request

{
  "groupName": "Developers",
  "description": "Group for software development team",
  "status": "Active",
  "roles": [
    {
      "operation": "ADD",
      "name": "developer",
      "startDate": "2023-01-01",
      "endDate": "2023-12-31",
      "description": "Access to development tools"
    }
  ]
}

Responses

✅ 200 SUCCESS – Created successfully.
❌ 400 BAD REQUEST – Invalid credentials or user status.
❌ 500 INTERNAL SERVER ERROR – Unexpected error.

3. Remove Group. The Group Deletion API is used to remove an existing group from OpenIAM, ensuring proper deprovisioning and access management. Endpoint is given below.

DELETE /api/groups/{groupId}

Sample JSON request

{
  "groupId": "101"
}

Responses

✅ 200 SUCCESS – Group removed successfully.
❌ 400 BAD REQUEST – Invalid credentials or user status.
❌ 500 INTERNAL SERVER ERROR – Unexpected error.

Script development for Groovy Script Connector

Overview

This section provides guidance on developing Groovy scripts for the OpenIAM Groovy Script Connector. These scripts enable the integration of custom logic for managing user lifecycle operations.

Accessing OpenIAM connector repository

For more details, visit the OpenIAM Connector Repository, an open-source resource for developing and writing connector scripts.

Handlers/Object rules in OpenIAM Groovy Script Connectors

Handlers in OpenIAM Groovy script connectors store the absolute path to the Groovy script responsible for key operations throughout the user lifecycle. Typically, each handler is associated with its own Groovy script. However, in some cases, multiple handlers may share a single script, especially in the following scenario:

Example of Handler reusability:

ADD and MODIFY Handlers.

These handlers can utilize a single Groovy script to handle Create, Read, Update, and Delete (CRUD) operations. The general structure of the script is as follows.

• It first checks the target system to determine if the user already exists.
  • If the user does not exist, the script proceeds with user creation.
  • If the user exists, the script either modifies or deletes the user based on the request parameters.

This approach consolidates the logic into a single script, reducing redundancy and simplifying maintenance.

Common Handlers/Object rules.

1. Test Connection Handler.

• Managed System page: Referred to as the Test Connection Object Rule.
• Purpose: This handler is responsible for checking the health of the connection between OpenIAM and the target system. It ensures that the communication between the two systems is functional.

2. Search Operation Handler.

• Managed System page: Referred to as the Search Object Rule.
• Purpose: This handler is responsible for retrieving user details from the target system. It executes a search query based on the request parameters and returns the relevant user data.

3. Add/Modify Handler.

• Managed System Configuration Page: Referred to as the Add Object Rule and Modify Object Rule.
• Purpose: This handler is responsible for adding or modifying user records in the target system based on the request. It can handle both user creation and modification actions depending on whether the user already exists in the target system.

Required libraries

The following libraries are required to ensure smooth operation of the scripts and API communication:

• Jackson Library: Used for JSON parsing and serialization.
• Apache HTTP Components: Handles HTTP requests and responses.
• Apache Commons Logging: Provides logging support for tracking script execution.
• OpenIAM API Connector Classes: Supports provisioning and metadata handling.
• Spring Framework: Manages dependency injection and provides the application context.
• Java Collections: Utilized for handling lists, maps, and other collections.
• Apache Commons Collections: Provides utility methods for collection operations, making it easier to work with complex data structures.

These components work together to ensure efficient API communication, response processing, and the overall execution of the Groovy script.

Follow this link to check example group scripts Group Scripts.

Example:

Implementing the Test connection handler

Purpose: The Test Connection Handler verifies the connectivity between OpenIAM and the target system. If the system does not support a test connection, the script can return a success response without performing an actual connection check.

Here is a flowchart representation of the Test Connection Handler.

Example Test connection script can be found here.

Implementing the Search operation handler

Purpose: The Search Operation Handler transforms external API responses (JSON format) into OpenIAM-compatible connector objects. OpenIAM utilizes this response for synchronization operations.

Example Search operation script can be found here.

Implementing CRUD operation handlers (ADD/MODIFY handlers)

Purpose: The CRUD Operation Handler manages saving, updating, and deleting users based on the policy map configured in the managed system.

Example Save operation script can be found here.

Deployment of Groovy Script connector

This section focuses on the deployment of the Groovy Script Connector. The connector can be deployed as either a local or remote connector.

• Local connectors are deployed on the same machine where OpenIAM is installed.
• Remote connectors are deployed on a remote machine and communicate with OpenIAM through a specified RabbitMQ queue, which is configured in the application.properties file during deployment.

Key considerations for deploying a remote connector

1. Vault communication.
   • The remote connector must communicate with Vault, a critical component for managing passwords, to retrieve RabbitMQ credentials.
2. Handling Vault unavailability.
   • If the remote server cannot reach Vault, RabbitMQ credentials can be supplied directly in the application.properties file.
   • Any encryption strategy can be used to securely store these credentials, preventing direct exposure.

Registering a connector with OpenIAM

To register a connector in OpenIAM, ensure that it is correctly linked to the connector queue, which can be viewed and configured under. Go to webconsole > Provisioning > Connectors, then select and edit the desired connector.

Detailed deployment strategies

For a comprehensive guide on deploying the connector using different strategies, refer to the following documentation:

• Deploying Connectors via RPM.
• Deploying Connectors via Docker.
• Deploying Connectors via Kubernetes.

Can a single Groovy Script Connector be used for multiple target applications or Managed Systems?

Answer: Yes, a single Groovy Script Connector can be used for more than one target application or managed system.

Example

Consider two different applications that operate on the same principles and have a similar API structure (if they are REST API-based systems) or a similar database schema (but with different database names).

In such cases

• We can create two managed systems in OpenIAM that utilize the same handlers for performing tasks like:

  • Test connection.
  • Search operations.
  • Saving user information.

• The differentiation between the managed systems occurs through:

  • API Endpoints or Database Names. These values are provided to the handlers dynamically.
  • Managed System configuration. Custom attributes can be defined within each managed system configuration to specify the unique API endpoints or database names.

• Extracting Custom Attributes in Handlers.

  • During execution, the handler can retrieve the relevant custom attributes from the calling managed system.
  • This allows the same connector logic to be reused across multiple applications while maintaining flexibility.

By leveraging this approach, reusability and manageability are significantly improved, reducing redundancy and simplifying maintenance.