Powered by Algolia

    Groovy Script connector

    The Groovy Script connector provides flexibility to support various types of communication with target systems, if out-of-the-box connector is not available by OpenIAM.

    Connector overview

    Connector provides ability to call groovy script on each provisioning operation (save, search, test connection, delete, resume, suspend, reset password). Login is not supported so far. For each provisioning event, developer should develop a groovy script that extends AbstractCommandExecutor. There are no restrictions on the communications ways associated with the target system. Most common are REST API calls, PL/SQL package calls, shell script invocation. Connector as all other connectors can be started in remote mode. In this case, please note that groovy files should be located on server where connector is running, path to files should start from /data/openiam/conf/iamscripts/.

    Configuring OpenIAM

    Configure provisioning connector

    There is an out-of-the-box connector, called Groovy script connector, you can find in it list by navigating to webconsole > Provisioning > Connectors. Edit this connector by going into menu connector configuration. Enable rules that are necessary. Our advice, if you are going to use Script connector in synchronization then always have Test connection object rule enabled along with script provided because otherwise synchronization process can’t be started (sync will throw an error about fail connection to target system). Due to current legacy state please consider that save handler should be used in both ‘add’ and ‘modify’ rules. Groovy script connector handlers

    Configure managed system

    You can use fields like login, password, host URL, port, connection string etc. to store secured connection details, and obtain those in groovy script handler for any operation by:

    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);

    Fill the rule fields; each filed should contain path to a proper operation handler script. Groovy script managed system

    Script development

    Note that groovy script connector caches groovy scripts on start. If you made a change in one of the handler groovy scripts, you should restart connector service.

    Test connection operation handler

    This script is important to keep status of connection on the managed system dashboard. If there is no test connection handler presented, then you won't be able to start synchronization (because before start synchronization service checks status of connection on managed system dashboard). In case your system doesn't support test connection you can simply send success response, without really checking on the connection. Please find example of script below in Appendix 1.

    Search operation handler

    Idea of this groovy script is to obtain data from source (ex.: JSON response of API) and transform it into response with connector objects. OpenIAM will receive this response and use it in synchronization. Please find example of script in Appendix 2.

    CRUD operation handler

    CRUD operations are save and delete. These scripts are going to use values that OpenIAM produces based on policy map of the managed system. Please find example of script in Appendix 3.

    Appendixes

    Disclaimer: the following code examples are only for reference; they should be refactored by developer to match your requirements.

    1. Test connection groovy handler

    import org.openiam.api.connector.model.UserConnectorObject
    import org.openiam.api.connector.user.response.TestProvisioningConnectorResponse
    import org.openiam.base.ws.ResponseStatus
    import org.openiam.connector.core.base.commands.AbstractCommandExecutor
    import org.openiam.connector.core.base.exception.ConnectorException
    

    class TestScriptConnector extends AbstractCommandExecutor<UserConnectorObject, TestProvisioningConnectorResponse> {
    

       @Override
       TestProvisioningConnectorResponse perform(UserConnectorObject userConnectorObject) throws ConnectorException {
           TestProvisioningConnectorResponse rt = new TestProvisioningConnectorResponse();
           rt.setStatus(ResponseStatus.SUCCESS);
           return rt;
       }
    }

    2. Search user groovy handler

    import org.apache.commons.collections4.CollectionUtils
    import org.apache.commons.logging.Log
    import org.apache.commons.logging.LogFactory
    import org.openiam.api.connector.model.*
    import org.openiam.api.connector.user.response.SearchUserProvisioningConnectorResponse
    import org.openiam.base.AttributeOperationEnum
    import org.openiam.base.ws.ResponseStatus
    import org.openiam.common.beans.jackson.CustomJacksonMapper
    import org.openiam.connector.core.base.commands.AbstractCommandExecutor
    import org.openiam.connector.core.base.exception.ConnectorException
    import org.springframework.context.ApplicationContext
    

    class SearchScriptConnector extends AbstractCommandExecutor<ConnectorObject, SearchUserProvisioningConnectorResponse> {
    private static final Log log = LogFactory.getLog(SearchScriptConnector.class);
    private ApplicationContext context
    

       @Override
       SearchUserProvisioningConnectorResponse perform(ConnectorObject request) throws ConnectorException {
           SearchUserProvisioningConnectorResponse rt = new SearchUserProvisioningConnectorResponse();
           CustomJacksonMapper customJacksonMapper = context.getBean(CustomJacksonMapper.class)
           ConnectorObjectMetaData meta = request.getMetaData();
           List<StringConnectorAttribute> attributes = new ArrayList<>()
           attributes.addAll(meta.getAttributes())
           String searchFilter = ""
           for (StringConnectorAttribute attribute : attributes) {
               if ("searchQuery".equalsIgnoreCase(attribute.getName())) {
                   searchFilter = attribute.getValues().get(0).getValue()
                   break
               }
           }
    

           final String WEB_SERVICE_URL = String.format("https://example.com/query/users/%s", searchFilter)
           URL obj = new URL(WEB_SERVICE_URL);
           HttpURLConnection con = (HttpURLConnection) obj.openConnection();
           con.setRequestMethod("GET");
           con.setRequestProperty("Accept", "application/json");
    

           int responseCode = con.getResponseCode();
           if (responseCode == HttpURLConnection.HTTP_OK) {
               BufferedReader reader = new BufferedReader(new InputStreamReader(
                       con.getInputStream()));
               String inputLine;
               StringBuffer response = new StringBuffer();
               while ((inputLine = reader.readLine()) != null) {
                   response.append(inputLine);
               }
               reader.close();
               List<Object> resultList = new ArrayList<>()
               /**
                * create resultList from JSON data, using customJacksonMapper
                */
    

               if (CollectionUtils.isNotEmpty(resultList)) {
                   List<UserConnectorObject> userConnectorObjects = new ArrayList<>()
                   resultList.forEach({ Object it ->
                       StringConnectorAttribute extAttr = null;
                       UserConnectorObject userConnectorObject = new UserConnectorObject();
                       userConnectorObject.setIdentityName("username")
                       userConnectorObject.setIdentityValue(it.getUserName())
                       userConnectorObject.setAttributes(new ArrayList<StringConnectorAttribute>());
                       extAttr = new StringConnectorAttribute("sourceAttributeName");
                       extAttr.addValue(new StringOperationalConnectorValue(String.valueOf(it.getValue()), AttributeOperationEnum.NO_CHANGE));
                       userConnectorObject.getAttributes().add(extAttr);
                       userConnectorObjects.add(userConnectorObject)
    

                   })
                   rt.setUserList(userConnectorObjects)
    

               }
    

    

           } else {
               rt.setStatus(ResponseStatus.FAILURE);
           }
           rt.setStatus(ResponseStatus.SUCCESS);
           return rt;
       }
    

    

       static class JSONResponse {
           /**
            * fields
            */
    

           /**
            * setters/getters
            */
    

       }
    

    }

    3. Save user groovy handler

    package org.openiam.connector.script.user
    

    import org.apache.commons.logging.Log
    import org.apache.commons.logging.LogFactory
    import org.openiam.api.connector.model.ConnectorObject
    import org.openiam.api.connector.model.ConnectorObjectMetaData
    import org.openiam.api.connector.model.StringConnectorAttribute
    import org.openiam.api.connector.user.response.SaveUserProvisioningConnectorResponse
    import org.openiam.base.ws.ResponseStatus
    import org.openiam.connector.core.base.commands.AbstractCommandExecutor
    import org.openiam.connector.core.base.exception.ConnectorErrorCode
    import org.openiam.connector.core.base.exception.ConnectorException
    import org.springframework.context.ApplicationContext
    

    import java.sql.*
    

    class SaveScriptConnector extends AbstractCommandExecutor<ConnectorObject, SaveUserProvisioningConnectorResponse> {
       private static final Log log = LogFactory.getLog(SaveScriptConnector.class);
       private ApplicationContext context
    

       @Override
       SaveUserProvisioningConnectorResponse perform(ConnectorObject userConnectorObject) throws ConnectorException {
           SaveUserProvisioningConnectorResponse response = new SaveUserProvisioningConnectorResponse();
           Connection connection = getConnection(userConnectorObject.getMetaData())
           CallableStatement callableStatement;
           response.setStatus(ResponseStatus.SUCCESS);
    

           String userName = userConnectorObject.getIdentityValue();
           String attribute1;
           String attribute2;
           List<StringConnectorAttribute> attrList = new ArrayList<StringConnectorAttribute>()
           attrList.addAll(userConnectorObject.getAttributes())
           for (StringConnectorAttribute att : attrList) {
               if (att.getName() != null) {
                   //here "username", "attribute1","attribute2" - are names of policies from policy map for user object.
                   switch (att.getName()) {
                       case "attribute1":
                           attribute1 = att.getValues().first().value
                           break;
                       case "attribute2":
                           attribute2 = att.getValues().first().value
                           break;
                   }
               }
           }
           try {
               ResultSet resultSet;
               callableStatement = connection
                       .prepareCall("{call DB.dbo.Procedure_name(?,?,?)}");
               callableStatement.setString(1, userName);
               callableStatement.setString(2, attribute1);
               callableStatement.setString(3, attribute2);
    

               callableStatement.registerOutParameter(4, Types.VARCHAR);
               callableStatement.registerOutParameter(5, Types.VARCHAR);
               callableStatement.execute();
               String status = callableStatement.getString(6);
               String message = callableStatement.getString(7);
               if (status != null && !status.equalsIgnoreCase("SUCCESS")) {
                   response.setStatus(ResponseStatus.FAILURE)
                   response.setErrorText(String.format("Status: %s, message: %s", status, message)
               }
    

           } catch (SQLException e) {
               log.error("Error was caught.")
               log.error(e)
               response.setStatus(ResponseStatus.FAILURE)
               response.setErrorText(e.getLocalizedMessage())
           } finally {
               try {
                   if (callableStatement != null) {
                       callableStatement.close();
                   }
               } catch (SQLException e) {
                   e.printStackTrace();
    

               }
           }
    

           return response;
       }
    

       protected Connection getConnection(ConnectorObjectMetaData metaData) throws ConnectorException {
           Connection sqlCon;
           try {
               final String connectionString = metaData.getUrl()
               final String jdbcDriver = "com.microsoft.sqlserver.jdbc.SQLServerDriver";
               Class.forName(jdbcDriver);
               sqlCon = DriverManager.getConnection(connectionString, metaData.getLogin(), metaData.getPassword());
           } catch (ClassNotFoundException ex) {
               log.error(ex.getMessage(), ex);
               throw new ConnectorException(ConnectorErrorCode.JDBC_DRIVER_NOT_FOUND, ex);
           } catch (Exception ex) {
               log.error(ex.getMessage(), ex);
               throw new ConnectorException(ConnectorErrorCode.UNABLE_TO_CONNECT, ex);
           }
    

           return sqlCon;
       }
    

    

    }

    Integrating with a REST API using the Script connector

    OpenIAM can integrate with applications using the connector architecture via the following methods:

    • REST APIs.
    • SOAP APIs.
    • Database SQL or stored procedures.
    • Directory level integration for applications that support LDAP authentication and authorization.

    OpenIAM’s connector model requires several operations to support a full user life cycle. These include

    • Save – Save performs create and updates.
    • Search – Allows for finding individual users and as well in bulk based on a search parameter.
    • Delete – Used to delete an account in the target application.
    • Resume – used to enable an account in the target application.
    • Suspend – used to disable an account in the target application.
    • Test Connection – used by the OpenIAM framework to check if a connection is still active
    • Login – Allows authentication into OpenIAM using this application.

    Hence, the following document provides recommendations on designing the application-level integration API considering security and the parameters for each operation.

    Security

    The application integration API should be secured using the following.

    • Communication should be over HTTPS (while this is not required, OpenIAM strongly recommends this).
    • Access to these endpoints should require a valid Bearer Token (oAuth 2.0).
      • oAuth2 is an industry standard for authorization. In this model, the OpenIAM connector will first request a token and then call the API. OpenIAM will hold this token and refresh the token when it expires.

    There are several other options, however, not recommended as they are not standard-based and lack the level of security offered by oAuth.

    • API Key. An API key is a unique identifier (usually a long string) provided by the API provider. The connector can include this key in the request headers or as a query parameter.
    • Basic Authentication. Involves sending a username and password in the request headers. The credentials are usually Base64-encoded and requires HTTPS.

    API Operations

    Save

    The save operation in OpenIAM requires three (3) APIs on the integration side as shown below.

    1. API to check if the user exists. In this case the OpenIAM connector will call an API on the application integration API to see if the user exists. If the user exists, then the next call will be to the save-user API. If the user does not exist, the next call will be to the add-user API.

    Example: GET request /user?username=abc

    Returns:

    • SUCCESS 200 CODE - user object if found.
    • FAILURE 404 CODE - not found.
    • FAILURE 500 CODE - internal server error.
    1. API to create a user in the application.

    Example: POST request /add-user

    Below, there is a sample JSON payload with the user data. If possible, try to unify User object across systems (it can/should be also used in result of SEARCH API), it will reduce connector coding.

    {
      "username": "john.doe",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      ...[any other attributes ] ....
      "phoneNumber": "123-456-7890",
         "roles": [
            {
             "operation": "ADD"
              "name": "user",
              "startDate": "2023-01-01",
              "endDate": "2023-12-31",
              "description": "123123132" // description can be used to keep request number, when the user is requested access in SelfService and request should be approved access requested in OpenIAM
            },
            {
             "operation": "ADD"
              "name": "developer",
              "startDate": "2023-05-15",
              "endDate": "2023-11-15",
              "description": "birthright access" // or it can be used to describe why this relation presented
            }
          ],
          "groups": [
                  {
                    "operation": "ADD"
                    "name": "engineering",
                    "startDate": "2023-01-01",
                    "endDate": "2023-12-31",
                    "description": "#123123132" // description can be used to keep request number, when user is requested access in SelfService and request should be approved access requested in OpenIAM
                  },
                  {
                    "operation": "ADD"
                    "name": "developers",
                    "startDate": "2023-05-15",
                    "endDate": "2023-11-15",
                    "description": "birthright access" // or it can be used to describe why this relation presented.
                  }
                ],
      "status": "Active",
      "password": "Passwd00"
    }

    Returns:

    • SUCCESS 200 CODE - can return user object after creation OR can return identity name OR can return internal ID generated by system (if applicable) etc.
    • FAILURE 400 CODE - incorrect POST request.
    • FAILURE 500 CODE - internal server error.

    Optionally, you can also split the user creation API and adding/removing roles/groups. You can also develop API to add user's assignments, and we will call this API after user will be successfully created. This can be implemented in a couple of ways:

    • Simple membership without start/end date etc. characteristics: /add-role/{username}/{role-id}.
    • POST request /add-role.

    Example 1: Single object

    {
             "operation": "ADD"
              "name": "developer",
              "startDate": "2023-05-15",
              "endDate": "2023-11-15",
              "description": "birthright access" // or it can be used to describe why this relation presented.
      }

    Example 2: Multiple operations in a single call

    [{
              "operation": "DELETE"
               "name": "developer",
               "startDate": "2023-05-15",
               "endDate": "2023-11-15",
               "description": ""
       },
       .....
        {
                "operation": "ADD"
                 "name": "user",
                 "startDate": "2023-05-15",
                 "endDate": "2023-11-15",
               "description": ""
         }
         ]
    1. API to save a user in the application.

    Example: PUT request /update-user

    Same JSON payload as in /add-user but user object will contain only fields that should be updated (not all of them).

    {
      "username": "john.doe",
      "title": "CEO",
      ...[any other attributes ] ....
      "phoneNumber": "123-456-7890",
         "roles": [
            {
              "operation": "DELETE" /
              "name": "user",
              "startDate": "2023-01-01",
              "endDate": "2023-12-31",
              "description": "" 
            },
            {
             "operation": "ADD"
              "name": "CEO",
              "startDate": "2023-09-23",
              "endDate": "2024-11-15",
              "description": "birthright access" // or it can be used to describe why this relation presented
            }
          ],
          "groups": [
                  {
                    "operation": "REMOVE"
                    "name": "engineering",
                    "startDate": "2023-01-01",
                    "endDate": "2023-12-31",
                    "description": "#4333334" // description can be used to keep request number, when user is requested access in SelfService and request should be approved access requested in OpenIAM
                  },
                  {
                    "operation": "ADD"
                    "name": "developers",
                    "startDate": "2023-05-15",
                    "endDate": "2023-11-15",
                    "description": "birthright access" // or it can be used to describe why this relation presented
                  }
                ],
      "status": "Active",
      "password": "Passwd00"
    }

    Returns:

    • SUCCESS 200 CODE - user saved successfully.
    • FAILURE 400 CODE - incorrect POST request.
    • FAILURE 500 CODE - internal server error.

    Search is used to pull users from the system so that they can be used in other operations described in this document.

    Note: You need to identify the filter that will be used.

    There are a few examples below.

    Example: POST request /users

    • Example of payload.
      • Getting only active members of engineering group.
    {
        "group": "engineering",
        "isActive": true,
    }

    OR

    • Getting all active users in the system.
    {
        "isActive": true,
    }

    OR

    • Getting all users changed since 01 Jan 2023. This is specific filter that would be needed in case you want to do delta sync (to get only recently changed users).
    {
        "lastModified": "2023-01-01",
    }

    OpenIAM can't limit you here because filters are mostly defined by the business application and its ability to search/filter data. It's preferred that the application returns a set of JSON User objects.

    Delete

    Example: DELETE request /{username}

    Returns:

    • SUCCESS 200 CODE - user deleted successfully.
    • FAILURE 4XX CODE - any errors that system can throw during deletion.
    • FAILURE 500 CODE - internal server error.

    Reset password

    Changing or resetting a password in the application.

    Example: POST request /reset-password

    Sample payload:

    {
      "username": "1234567890",
      "newPassword": "newPassword456",
      ...[any other important for system parameters] ..
    }

    Returns:

    • SUCCESS 200 CODE - password was reset successfully.
    • FAILURE 4XX CODE - any errors that system can throw during reset password. For example, policy conditions are not satisfied.
    • FAILURE 500 CODE - internal server error.

    Resume

    This API is used to enable an account.

    Example: POST request /enable/{username}

    Returns:

    • SUCCESS 200 CODE - enabled successfully.
    • FAILURE 4XX CODES - displayed if it is possible define what exactly errored out. This message will be displayed in OpenIAM interface and will help admins to identify problem.
    • FAILURE 500 CODE - internal server error.

    Suspend

    Used to disable an account.

    Example: POST request /disable/{username}

    Returns:

    • SUCCESS 200 CODE - disabled successfully.
    • FAILURE 4XX CODES - displayed if it is possible to define what exactly errored out. This message will be displayed on OpenIAM interface and will help admins to identify problem.
    • FAILURE 500 CODE - internal server error.

    Test connection

    This is an API to check connection with target system. OpenIAM calls this API by default once a minute to check system health status. However, we recommend not to implement heavy logic in the API.

    Example: Get service account by calling /user?username=abc. If user found then connection is OK, if not found - there is an error. GET request /user?username=abc.

    Returns:

    • SUCCESS 200 CODE - connection is OK.
    • FAILURE 4XX CODES - displayed if it is possible to define what exactly errored out. This message can be displayed on OpenIAM interface and will help admins to identify problem with connection.
    • FAILURE 500 CODE - internal server error.

    Login

    This operation of connector allows using target system as an authentication server. OpenIAM can call API with payload of username and password and system can reply if user was authenticated successfully. If so, the user can be logged in OpenIAM, and if not - error is displayed on login page.

    Example: POST request /verify-credentials

    Sample payload: 

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

    Returns:

    • SUCCESS 200 CODE - successfully authenticated.
    • FAILURE 4XX CODE - any errors that system can throw during authentication, such as invalid password/invalid status/user is disabled in the system etc.
    • FAILURE 500 CODE - internal server error.
    Previous
    SCIM
    Next
    Workday