> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/connector-configuration/scriptconnector/groovyscriptconnector.md). # Configuring the Groovy Script connector This page describes how to configure and use flexible 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 {% stepper %} {% step %} **Enable the Test Connection Object rule.** Needed if you will use the connector for synchronization — the rule and the script that goes with it. Without them, synchronization fails with an error saying it cannot connect to the target system. {% endstep %} {% step %} **Use the Save handler for both Add and Modify.** Point both provisioning rules at the same handler. The implementation is legacy in this respect, and splitting them across two handlers does not work. {% endstep %} {% step %} **Fill in both synchronization fields.** `SQL Query / Directory filter` and `Source attribute names` are mandatory on the OpenIAM side. {% endstep %} {% endstepper %} {% hint style="warning" %} **None of these three fail when you save.** A missing Test Connection rule, Add and Modify split across two handlers, or either synchronization field left empty all save without complaint and then produce an error the first time the connector actually runs. {% endhint %} ## 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. {% code overflow="wrap" %} ``` 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 ``` {% endcode %} ## 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 Writing the Groovy that the connector runs — the handlers, the libraries available to them, what each one must return, and how to deploy and register the result — is covered in [Developing Groovy scripts for the Script connector](/connector-configuration/scriptconnector/script-development.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openiam.com/connector-configuration/scriptconnector/groovyscriptconnector.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.