Managing Associations of Provisioned Accounts to Entitlements in Groovy API

Introduction

It is possible to manage the associations between provisioned accounts and Entitlements using the Memority Synchronization service Groovy API. Reminder: "Entitlement" is a generic term which most often designates an LDAP group. It is thus possible to add/remove entries to/from LDAP groups via Groovy scripts.

Only Entitlement associations are manageable via Groovy. It is not possible to create/update/delete Entitlements per se using the Groovy API. It is thus not possible to create LDAP groups.

"Legit" Entitlements that are automatically associated to the account by Memority Synchronization service via the configuration of "Assignments" cannot be dissociated using the Groovy API:

when attempting to dissociate via the Groovy API all the groups of an account (see method dissociateAccountFromAll), "legit" groups are silently ignored (they are skipped)
when attempting to dissociate via the Groovy API a specific "legit" group (see method dissociateAccountFrom), an error occurs (a KitException is thrown)

This page describes the Groovy API enabling to perform account associations/dissociations of Entitlements.

Entitlement associations/dissociations performed in Groovy scripts are not recorded into the Memority Synchronization repository, thus Memority Synchronization service doesn't keep track of them internally. Moreover, Memority Synchronization service allows Entitlement associations via Groovy that may interfere with "traditional" Entitlements associations configured via "Assignments" (see ApplicationProfile#assignments). That's ok since Memority Synchronization service is already able to handle any external changes that may occur behind its back, such as when a local Active Directory administrator performs operations using the Windows console, bypassing Memority Synchronization service.

Configure a Provisioning Post Action

A new Action Rule postAction has been added to the Memority Synchronization configuration, it is executed after the account provisioning operation is complete.

The property postAction of type ActionRule has thus been added to ObjectSchemaMappingDefinition, as shown in the example below:

CODE

<objectSchemaMappingDefinition>

...

    <postAction>
               <script><![CDATA[
// This is the provisioned account, which will be removed from the first group to which it belongs
def account = ACCOUNT

// Find the first group to which the account belongs
def group = FIND.entitlement().associatedWithAccount(account).get(0)

// Remove the account from the group
MANAGE.entitlement().dissociateAccountFrom(account, group)
ActionOutcome.success()
]]></script>
    </postAction>

...

</objectSchemaMappingDefinition>

The provisioning "post action" is not the only place where Entitlement associations can be managed via Groovy. The "post action" has been added for convenience, but any other Groovy Rule where an account is available can manage Entitlement associations, namely ApplicationObjectActivationDefinition#customAction, which is executed when an Identity is disabled or deleted, or when an Identity is not supposed to be provisioned anymore on the application.

Groovy Bindings

This table lists the elements related to Entitlement associations available in Groovy scripts:

Binding Variable	Java Type	Description	Exemple Usage
`ACCOUNT`	`ApiObject`	The provisioned account
`FIND.entilement()`	`EntitlementFinderApi`	A service that enables to find Entitlements that can then be associated/dissociated to/from the provisioned account	`FIND.entitlement().associatedWithAccount(account)`
`MANAGE.entitlement()`	`EntitlementManagerApi`	A service that enables to associate/dissociate Entitlements to/from the provisioned account	`MANAGE.entitlement().dissociateAccountFrom(account, group)`

Entitlement Association API

This sections provides the Java API enabling to manage Entitlements associations.

EntitlementFinderApi

EntitlementFinderApi

CODE

/**
 * API used by Groovy scripts to find Entitlements.
 */
public interface EntitlementFinderApi {

    /**
     * Find all Entitlements associated with the given account.
     *
     * @param account associated with the returned Entitlements
     * @return the list of matching Entitlements, empty if none found
     */
    List<ApiObject> associatedWithAccount(ApiObject account);

    /**
     * Return all Entitlements that match the given search expression.
     *
     * @param expr the search expression
     * @return the list of matching Entitlements, empty if none found
     */
    List<ApiObject> allMatching(SearchExpression expr);

    /**
     * Return the first Entitlement that matches the given search expression.
     *
     * @param expr the search expression
     * @return the first Entitlement that matches, or <code>null</code> if none matches
     */
    ApiObject matching(SearchExpression expr);
}

EntitlementMangerApi

EntitlementManagerApi

CODE

/**
 * API used by Groovy scripts to manage Entitlements' associations.
 */
public interface EntitlementManagerApi {

    /**
     * Associate the given account with the given Entitlement. This method is idempotent.
     *
     * @param account associated with the Entitlement
     * @param entitlement associated with the account
     */
    void associateAccountTo(ApiObject account, ApiObject entitlement);

    /**
     * Dissociate the given account from the given Entitlement. This method is idempotent.
     * <p>
     * The given {@code entitlement} cannot be "legit", i.e. it was associated through Assignments.
     *
     * @param account dissociated from the Entitlement
     * @param entitlement dissociated from the account
     * @throws RuntimeException if the given {@code entitlement} is "legit", i.e. it was associated through Assignments
     */
    void dissociateAccountFrom(ApiObject account, ApiObject entitlement);

    /**
     * Dissociate the given account from the given list of Entitlements. This method is idempotent.
     * <p>
     * The given {@code entitlements} cannot be "legit", i.e. associated through Assignments.
     *
     * @param account dissociated from the Entitlements
     * @param entitlements dissociated from the account
     * @throws RuntimeException if one of the given {@code entitlements} is "legit", i.e. it was associated through Assignments
     */
    default void dissociateAccountFrom(ApiObject account, List<ApiObject> entitlements) {
        entitlements.forEach(entitlement -> dissociateAccountFrom(account, entitlement));
    }

    /**
     * Dissociate the given account from the given array of Entitlements. This method is idempotent.
     * <p>
     * The given {@code entitlements} cannot be "legit", i.e. associated through Assignments.
     *
     * @param account dissociated from the Entitlements
     * @param entitlements dissociated from the account
     * @throws RuntimeException if one of the given {@code entitlements} is "legit", i.e. it was associated through Assignments
     */
    default void dissociateAccountFrom(ApiObject account, ApiObject... entitlements) {
        dissociateAccountFrom(account, Arrays.asList(entitlements));
    }

    /**
     * Dissociate the given account from all the Entitlements it is associated with. This method is idempotent.
     * <p>
     * "Legit" Entitlements that were associated through Assignments are ignored.
     *
     * @param account dissociated from all Entitlements, except the "legit" ones that were associated through Assignments
     */
    void dissociateAccountFromAll(ApiObject account);
}

Examples of Groovy Scripts

This section provides some examples of Groovy scripts managing Entitlement associations.

Associate account to group

CODE

/*
 * Add the provisioned account to the "sales" group
 */

// Find the "sales" group
def salesGroup = FIND.entitlement().matching(expr {prop('cn').eq('sales')})

// Add the provisioned account to the "sales" group
def account = ACCOUNT
MANAGE.entitlement().associateAccountTo(account, salesGroup)
ActionOutcome.success()

Dissociate account from a specific group

CODE

/*
 * Dissociate the provisioned account from the "sales" group
 */

// Find the "sales" group
def salesGroup = FIND.entitlement().matching(expr {prop('cn').eq('sales')})

// Remove the provisioned account from the "sales" group
def account = ACCOUNT
MANAGE.entitlement().dissociateAccountFrom(account, salesGroup)
ActionOutcome.success()

Dissociate account from all groups

CODE

/*
 * Remove the provisioned account from all groups.
 */

def account = ACCOUNT
MANAGE.entitlement().dissociateAccountFromAll(account)
ActionOutcome.success()

Introduction

Configure a Provisioning Post Action

Groovy Bindings

Entitlement Association API

EntitlementFinderApi

EntitlementMangerApi

Examples of Groovy Scripts

Read Next