Skip to main content

Making changes with iddriver

The iddriver program reads a file, usually generated by idtrack , that describes changes to make on target systems. The iddriver program then sends these changes to the idtm and idwfm services.

Best practice

It is possible to write a custom script to generate a custom work file without idtrack to make complicated or dynamic changes to users, user attributes, or user group memberships. This method is not recommended because it allows automation direct access to Transaction Monitor Service (idtm), bypassing the authorization workflow. Instead, the recommended method is to use API calls in the idtrack.psl script to make changes to users or user group membership.

Usage

Run iddriver with the following arguments:

  iddriver [-f <filename>] [options]...

where: -f tells iddriver to use the input file <filename>. If the -f option is not specified, then stdin is used as the source of input. You must use CTRL+Z on a new line to end the input from stdin.

The following server options are only needed if the services are not running on the local host:

Argument

Description

-idtmserver <servername>

The host running the idtm service

-idtmsvcid <svcid>

The service id that idtm is listening on

-idwfmserver <servername>

The host running the idwfm service

-idwfmsvcid <svcid>

The service id that idwfm is listening on

To just print what would be sent and not contact any service, type:

iddriver -n

Input format

The input that iddriver receives, either in a file or from stdin, has to be in KVGroup format. The input can contain multiple types of requests that touch different users. The following are examples of different types of input.

Single request

The following is an example of single addUser request. Note that if passwords are included in the request they must be encrypted. Any account attributes omitted will be set using the configuration.

# KVGROUP-V1.0
"addUser" "AD" = {
  "fullname" = "John Doe"
  "password" = "<encrypted password value>"
  "shortid" = "johnd"
  "template" = "user"
  "accountid" = "johnd"
  "addAttrs" "" = {
    "accountDisabled" = "f"
    "displayName" = "John Doe"
    "givenName" = "Doe"
    "sn" = "John"
    "userPrincipalName" = "johnd@server.local"
  }
}
Workflow containing multiple requests in a single batch

The following is an example of a workflow containing multiple requests in a single batch. Note that:

  • The KVGroup name is case sensitive, and it must match the case of the user as it exists in the user database table.

  • Submitting workflow requests using iddriver triggers the execution of Bravura Security Fabric plugins after the request is submitted. Primarily the attribute validation, authorizer modification, and operation rewrite plugins. This will only happen if the appropriate plugin is already configured.

    # KVGROUP-V1.0
"workflow" "JOHND" = {
  "metadata" "" = {
    "requester" = "bobs"
         
    "requestReason" = "Adding new user -> John Doe"
    "requesterEmail" = "bobs@company.com"
  }
  "operation" "template" = {
    "metadata" "" = {
      "targetID" = "WIN2003AD"
      "template" = "WIN2003AD"
    }
  }
  "operation" "enable" = {
    "metadata" "" = {
      "targetID" = "WIN2003AD"
      "account" "" = {
        "longid" = "user1"
        "targetID" = "WIN2003AD"
      }
    }
  }
  "operation" "delete" = {
    "metadata" "" = {
      "targetID" = "WIN2003AD"
      "account" "" = {
        "longid" = "user2"
        "targetID" = "WIN2003AD"
      }
    }
  }
  "operation" "groupuseradd" = {
    "metadata" "" = {
      "targetID" = "WIN2003AD"
      "groupid" = "CN=Cert Publishers,CN=Users,DC=WIN2003AD,DC=psynch,DC=com"
      "account" "" = {
        "longid" = "user3"
        "targetID" = "WIN2003AD"
      }
    }
  }
  "operation" "groupuserdelete" = {
    "metadata" "" = {
      "targetID" = "WIN2003AD"
      "groupid" = "CN=Cert Publishers,CN=Users,DC=matrix02,DC=psynch,DC=com"
      "account" "" = {
        "longid" = "user4"
        "targetID" = "WIN2003AD"
      }
    }
  }
  "operation" "disable" = {
    "metadata" "" = {
      "targetID" = "WIN2003AD"
      "account" "" = {
        "longid" = "user5"
        "targetID" = "WIN2003AD"
      }
    }
  }
  "requestAttributes" "" = {
    "FIRST_NAME" = "John"
    "LAST_NAME" = "Doe"
  }
}
Update operation

The following is an example of a workflow containing an update operation. Note that:

  • The requestAttributes KVGroup contains a list of Bravura Security Fabric profile and request attributes which have to be properly defined in Bravura Security Fabric .

  • For each Attribute value in the requestAttributes KVGroup there must be a key-value pair. Attributes with multiplue values must have a multiple keys in the requestAttributes KVGroup.

  • If an update operation is performed, then the account KVGroup within the metadata KVGroup must contain all target systems that are affected by the update of the profile and request attribute – basically all target systems that the profile and request attribute is mapped to.

    "workflow" "JOHND" = {
  "operation" "update" = {
    "metadata" "" = {
      "targetID" = "WIN2003AD"
      "account" "" = {
        "longid" = "JOHND"
        "targetID" = "WIN2003AD"
      }
    }
  }
  "requestAttributes" "" = {
      "EMAIL" = "johnd@example.com"
      "NTLOGON" = "johnd"
      "OTHERPHONE" = "555-555-4565"
      "OTHERPHONE" = "555-555-4567"
  }
}
Group membership

When adding a new user, use the allGroups KVGroup to provide the list of groups the user needs to belong to.

"addUser" "AD" = {
    "shortid" = "joeb"
    "userid" = "joeb"
    "accountid" = "joeb"
    "fullname" = "Joe Black"
    "template" = "AD"
    "allGroups" "" = {
       "group" = "CN=ad-admin,OU=Calgary,DC=company,DC=dom"
       "group" = "CN=ad-alltech,OU=Calgary,DC=company,DC=dom"
       "group" = "CN=ad-allsales,OU=Calgary,DC=company,DC=dom"
       "group" = "CN=ad-remotesales,OU=Calgary,DC=company,DC=dom"
       "group" = "CN=Domain Users,CN=Users,DC=company,DC=dom"
    }
}

When modifying a user’s group membership using moduser, addGroups and allGroups are used in the following ways:

  • If addGroups is supplied, then the request is sent to add the user to each listed group.

  • If allGroups is supplied, then a request is created to modify the user’s group memberships so that the user only belongs to the listed groups; in effect, removing the user from group’s that the user belongs to that are not on the list, and adding the user to group’s on the list that the user does not currently belong to.

Container's distinguished name

A container’s distinguished name can be used in iddriver input. Note that:

  • A container’s distinguished name is part of general input and is not part of addAttrs.

  • The addAttrs KVGroup contains account attributes that have to be properly configured in Bravura Security Fabric before they are used. The names of the account attributes are case sensitive.

    "addUser" "AD" = {
    "shortid" = "rons"
    "userid" = "rons"
    "accountid" = "rons"
    "fullname" = "Ron Smith"
    "template" = "AD"
    "_container_dn" = "ou=Sales,DC=company,DC=dom"
    "addAttrs" "" = {
        "accountDisabled" = "f"
        "displayName" = "ronsmith"
        "givenName" = "smith"
        "sn" = "ron"
        "userPrincipalName" = "ronsmith@sales.company.com"
    }
}
In this section: