fwAccessControl  8.4.2
Egroups-related functions

Functions

dyn_mapping fwAccessControl_queryLdapCern (string baseDN, string filter, dyn_string &exceptionInfo, dyn_string attrs="", bool exceptionOnTooMuchResults=true)
 
dyn_mapping fwAccessControl_queryLdapCernRecursive (string egroup, dyn_string attrNames, dyn_string &exceptionInfo, bool exceptionOnTooMuchResults=true)
 
private dyn_mapping _fwAccessControl_recursiveLdapQuery (string egroup, dyn_string attrNames, dyn_string &searchedEgroups, dyn_string &exceptionInfo, mapping connInfo, bool exceptionOnTooMuchResults=true)
 
dyn_mapping fwAccessControl_queryLdapFor (string queryTarget, string egroup, dyn_string ldapAttrNames, dyn_string &exceptionInfo, mapping connInfo, bool exceptionOnTooMuchResults=true)
 
void fwAccessControl_setEgroupSyncForGroup (string groupName, string egroupName, dyn_string &exceptionInfo) synchronized(_fwAccessControl_mutex)
 
void fwAccessControl_getEgroupSyncForGroup (string groupName, string &egroupName, dyn_string &exceptionInfo) synchronized(_fwAccessControl_mutex)
 
void fwAccessControl_getEgroupDetails (string egroupName, string &egroupDescription, dyn_string &includedGroupNames, dyn_string &includedUserNames, mapping &otherInfo, dyn_string &exceptionInfo, bool recursive=false)
 
dyn_mapping fwAccessControl_getEgroupSubgroups (string egroupName, dyn_string &exceptionInfo, string attrNames="", string childType="", dyn_string otherFilters=makeDynString())
 
dyn_string fwAccessControl_getEgroupList (dyn_string &exceptionInfo, string nameFilter="", dyn_string otherFilters=makeDynString())
 
string fwAccessControl_egroupToDomainName (string egroupName)
 
string fwAccessControl_egroupToRoleName (string egroupName)
 
string fwAccessControl_domainNameToEgroup (string domainName, dyn_string &exceptionInfo)
 
string fwAccessControl_roleNameToEgroup (string roleName, dyn_string &exceptionInfo)
 
void fwAccessControl_egroupToAccessRight (string egroupName, string &accessRight, int &privNumber, dyn_string &exceptionInfo)
 
string fwAccessControl_accessRightToEgroup (string accessRight, dyn_string &exceptionInfo)
 
void fwAccessControl_egroupGetDomainPrivileges (string domainEgroup, dyn_string &privilegeNames, dyn_string &privilegeEgroups, dyn_string &exceptionInfo)
 
void fwAccessControl_getConfigurationFromEgroup (string configurationEgroup, dyn_string &domainEgroups, dyn_string &domainNames, dyn_string &roleEgroups, dyn_string &roleNames, dyn_string &exceptionInfo)
 
void fwAccessControl_getDomainFromEgroup (string domainEgroup, string &domainName, string &domainComment, dyn_string &privilegeEgroups, dyn_string &privilegeNames, dyn_string &exceptionInfo)
 
void fwAccessControl_getRoleFromEgroup (string roleEgroup, string &roleName, string &roleComment, dyn_string &accessRights, dyn_string &privilegeEgroups, dyn_string &memberEgroups, dyn_string &childRoleEgroups, dyn_string &exceptionInfo)
 

Variables

const string fwAccessControl_egroupsBaseDN ="OU=e-groups,OU=Workgroups,DC=cern,DC=ch"
 
const string fwAccessControl_Egroup_FullNamePrefix = "EGROUP:"
 
const string fwAccessControl_Egroup_topicConfiguration = "fwAccessControl configuration"
 

Detailed Description

Function Documentation

dyn_mapping fwAccessControl_queryLdapCern ( string  baseDN,
string  filter,
dyn_string &  exceptionInfo,
dyn_string  attrs = "",
bool  exceptionOnTooMuchResults = true 
)

Query data from CERN LDAP Server

Parameters
baseDN(string) IN BaseDN for LDAP query
filter(string) IN Filter for LDAP query
exceptionInfo(dyn_string) IN/OUT standard exception-handling variable
attrs(dyn_string) IN is optional with default value '""' a list of LDAP attributes to be queried. When empty (or default), all the attributes will be returned
exceptionOnTooMuchResults(bool) IN is optional with default value 'true' specifies what happens if ldapSearch returns with error code 4 (Size limit exceeded); if set to true, a framework exception is thrown into the exceptionInfo and possibly also a mesage in the log is placed, or PVSS exception is thrown; if set to false, then no framework/PVSS exception is thrown - instead, the exceptionInfo parameter will be set to ("INFO","Too many search results","4"), which would allow to catch this situation in the code upstream)
Returns
value of type 'dyn_mapping', the results of a query being the list of entries; each entry is a mapping, and "DN" (the canonical identifier) is always present; if there are more attributes of the same type, then the value is of dyn-type, not a scalar (e.g. more than one telephone number)
dyn_mapping fwAccessControl_queryLdapCernRecursive ( string  egroup,
dyn_string  attrNames,
dyn_string &  exceptionInfo,
bool  exceptionOnTooMuchResults = true 
)

Alternative recursive method to LDAP query

Recursive processing is implemented on client-side in CTRL, instead of the server, for the reasons of performance. Each child-entry (eg. a egroup) is queries separately

Parameters
egroup(string) IN the name of the object being queried
attrNames(dyn_string) IN
exceptionInfo(dyn_string) IN/OUT
exceptionOnTooMuchResults(bool) IN is optional with default value 'true'
Returns
value of type 'dyn_mapping'
private dyn_mapping _fwAccessControl_recursiveLdapQuery ( string  egroup,
dyn_string  attrNames,
dyn_string &  searchedEgroups,
dyn_string &  exceptionInfo,
mapping  connInfo,
bool  exceptionOnTooMuchResults = true 
)

Recursively query users from an egroup (internal)

Parameters
egroup(string) IN the name of egroup being queried
attrNames(dyn_string) IN the list of LDAP attributes to query
searchedEgroups(dyn_string) IN/OUT can be used to exclude e-groups from the search by placing items in it when initially calling the function
exceptionInfo(dyn_string) IN/OUT standard exception-handling variable
connInfo(mapping) IN parameters for LDAP connection; should contain the keys/values "hostName", "authMethod","userName","password"
exceptionOnTooMuchResults(bool) IN is optional with default value 'true'
Returns
value of type 'dyn_mapping' the results of the query
dyn_mapping fwAccessControl_queryLdapFor ( string  queryTarget,
string  egroup,
dyn_string  ldapAttrNames,
dyn_string &  exceptionInfo,
mapping  connInfo,
bool  exceptionOnTooMuchResults = true 
)

Execute a single query to an LDAP e-group to get either its members or other e-groups in it.

Not recursive, returns either a list of members or e-groups on the "top level"!

Parameters
queryTarget(string) IN what to query; "members" will query the members of egroup, "egroups": list of egroups, yet not being fwAccessControl Roles/Configs/Privileges/Domains any other string means the egroup information itself
egroup(string) IN the name of the egroup
ldapAttrNames(dyn_string) IN the list of attributes to be queries
exceptionInfo(dyn_string) IN/OUT standard exception-handling library
connInfo(mapping) IN parameters for LDAP connection
exceptionOnTooMuchResults(bool) IN is optional with default value 'true', specifies if exception should be raised if LDAP responses with information "too much results"
Returns
value of type 'dyn_mapping' being a list of results, each being a mapping where keys are the names of attributes
void fwAccessControl_setEgroupSyncForGroup ( string  groupName,
string  egroupName,
dyn_string &  exceptionInfo 
)

Modifies the configuration of egroup-synchronization mapping

Please note that this function does check if egroup actually exists, if only LDAP extension is loaded. To disable the synchronization for the egroup, use an empty string as egroupName

Parameters
groupName(string) IN the name for which the mapping-to-egroup is modified
egroupName(string) IN the name of egroup to be synchronized into the groupName
exceptionInfo(dyn_string) IN/OUT standard exception-handling variable
void fwAccessControl_getEgroupSyncForGroup ( string  groupName,
string &  egroupName,
dyn_string &  exceptionInfo 
)

Retrieves the configuration of egroup-synchronization mapping

Parameters
groupName(string) IN the name of the group for which the mapping is retrieved
egroupName(string) OUT on return will contain the egroup name mapped to the group
exceptionInfo(dyn_string) OUT standard exception-handling variable
void fwAccessControl_getEgroupDetails ( string  egroupName,
string &  egroupDescription,
dyn_string &  includedGroupNames,
dyn_string &  includedUserNames,
mapping &  otherInfo,
dyn_string &  exceptionInfo,
bool  recursive = false 
)

Retrieve details about a egroup using a LDAP lookup.

Parameters
egroupName(string) IN the name of egroup to query
egroupDescription(string) OUT on return will contain the "Description" field of egroup
includedGroupNames(dyn_string) OUT on return will contain the list of included egroups (only direct children, no recursive query!)
includedUserNames(dyn_string) OUT on return will contain the list of users (only direct children, no recursive query)
otherInfo(mapping) OUT on return will contain all the other information about the egroup; keys are the LDAP attribute names
exceptionInfo(dyn_string) OUT standard exception-handling variable
recursive(bool) IN is optional with default value 'false' (NOT IMPLEMENTED YET) allows to query groups and members recursively
dyn_mapping fwAccessControl_getEgroupSubgroups ( string  egroupName,
dyn_string &  exceptionInfo,
string  attrNames = "",
string  childType = "",
dyn_string  otherFilters = makeDynString() 
)

Extracts the list of child egroups for specified egroup, allowing to specify the types of children, attributes and filters.

The function has two modes of operations: a lookup of egroups through a filter, or a lookup of children of a specifed egroups (also with filtering); the mode of operation is determined by the egroupName paramater.

TL;DR (examples worth a thousand words):
  • query all egroups matching a name pattern
    dyn_mapping privilegeRes=fwAccessControl_getEgroupSubgroups("test-fwACPrivilege*", exceptionInfo);
  • query for all egroups representing roles, and matching a specific name pattern; note that we specify empty string as the egroupName and we specify the filtering of names through the otherFilters parameter;
    dyn_mapping result=fwAccessControl_getEgroupSubgroups("", exceptionInfo,
    "",fwAccessControl_EgroupLookup_Roles, makeDynString("cn=*-MyDCS-*"));
  • for the specified egroup, query all the details ("attributes"); note that the egroupName parameter is empty, and we specify egroup name in the otherFilters parameter
    dyn_mapping result=fwAccessControl_getEgroupSubgroups("", exceptionInfo,"*","",makeDynString("cn=test-fwACRole-MyDCS-expert"));
  • for the specified egroup, query the list of granted access rights; this query needs to return the list of children (that is why we specify the egroup name in the first parameter) and we specify the type of the children in the childType parameter
    dyn_mapping privilegeRes=fwAccessControl_getEgroupSubgroups("test-fwACRole-MyDCS-expert", exceptionInfo,
    "", fwAccessControl_EgroupLookup_Privileges);
  • get the list of roles holding the specified access right; to do that we need a list of groups being a parent of the specified access right egroup, and being of type "role"; this is the most advanced way of specifying the otherFilters parameter with LDAP-specific syntax for filters; we also specify that we want additional attributes to be retrieved: the description and the date of last modification of the egroup:
    dyn_mapping privilegeRes=fwAccessControl_getEgroupSubgroups("", exceptionInfo,
    "description,whenChanged",fwAccessControl_EgroupLookup_Roles,
    makeDynString("member=cn=test-fwACPrivilege-MyDCS-1-Monitor"+","+fwAccessControl_egroupsBaseDN));
Parameters
egroupName: (INPUT)
  • if empty (""), it activates the egroup-search mode of operation (and applies filters specified in further parameters); With no filters specified, will return the list of all egroups;
  • if contains (one or many) wildcard characters, "*", it will again activate a egroup-search mode applying the value of this parameter as the filter
  • otherwise, it activates the "children lookup" mode of operation; the egroup specified in this parameter will be queried for children, and it is the list of children that is returned; the filters specified in the chidType and otherFilters parameters do apply (see below); Note that it is the name of the egroup ("cn" attribute in LDAP) that should be used, rather than the "dn"). The otherFilters parameter allows for advanced queries (see its description)
exceptionInfo,:standard exception-handling variable
attrNames,:comma-separated list of LDAP attributes to be queried; note that the values for the ["DN"] and ["cn"] will always be returned;the attributes specified here, if they exist for the returned objects, will then also be queried. Special cases:
  • "" (default): only ["DN"] and ["cn"] are returned
  • "*" : all the attributes available for objects are returned;
childType,:allows to select child egroups of specific type (also called "topic" in the egroups web interface or "adminDescription" attribute in LDAP); by default, empty, means no filtering. The following predefined constants may be used to retrieve egroups that are applicable to the fwAccessControl egroup-synchronization:
  • fwAccessControl_EgroupLookup_Configurations : egroup-sync configurations ("fwAccessControl configuration" topic)
  • fwAccessControl_EgroupLookup_Domains : access control domains ("fwAccessControl domain" topic)
  • fwAccessControl_EgroupLookup_Privileges : access control privilege/access right ("fwAccessControl privilege" topic)
  • fwAccessControl_EgroupLookup_Roles : access control roles/groups ("fwAccessControl role" topic)
otherFilters(by default empty): list of additional LDAP filters appended to the LDAP query; these should be in form of string "ATTRIB=VALUE", without brackets, and they will be used to form the filter
Returns
list of mapping variables, each mapping describes one egroup result, and it will always have the values in the ["DN"] (Distinguished Name) and ["cn"] (Common Name) attributes, which identify the LDAP object; in addition, they may have values in the keys requested with attrNames parameter; if there are multiple attributes of the same type for the same object, the value of the concerned key will be a dyn_ list of values instead.
dyn_string fwAccessControl_getEgroupList ( dyn_string &  exceptionInfo,
string  nameFilter = "",
dyn_string  otherFilters = makeDynString() 
)

Look up egroups matching a search criteria

By default (no filters) will return the list of all egroups.

Parameters
exceptionInfo(dyn_string) OUT standard exception-handling variable
nameFilter(string) IN is optional with default value '""' specify a filter on the name of the egroup; the wildcard character '*' could be used inside the filter
otherFilters(dyn_string) IN is optional, default empty; a list of other filters, in form of strings 'attribute=value'; the list is then converted to the LDAP filter string, with the logical "and" operator; note that there should be no brackets around the tokens passed in the list
Returns
value of type 'dyn_string' the list of matching egroups
string fwAccessControl_egroupToDomainName ( string  egroupName)

Extracts domain name from a egroup name

The name of the domain is the string after the last "-" character in the egroup name.

Parameters
egroupName(string) IN the name of the egroup
Returns
value of type 'string' the name of the domain
string fwAccessControl_egroupToRoleName ( string  egroupName)

Extracts role name from a egroup name

The name of the role (group) is the last strings separated by the "-" character in the egroup name. If the string found is "--", then it will be converted to a "-" in a name, instead of being treated as a separator.

Examples: A-B-C => C A-B–C -> B-C A_B-C_D-E_F -> E_F

Parameters
egroupName(string) IN the name of the egroup
Returns
value of type 'string' the name of role
string fwAccessControl_domainNameToEgroup ( string  domainName,
dyn_string &  exceptionInfo 
)

Converts domain name to a egroup name

To find a matching egroup, the following methods are applied

  • try to look up from the domain full name; it should contain a string such as "EGROUP:xxxx", and then the "xxxx" is returned (actually the prefix is the fwAccessControl_Egroup_FullNamePrefix constant)
  • for the SYSTEM domain, the predefined egroup SCADA-fwACDomain-SYSTEM is retured
  • a lookup in LDAP, with a filter on egroup type and wildarded name
Parameters
domainName(string) IN the name of the domain
exceptionInfo(dyn_string) standard exception-handling parameter
Returns
value of type 'string' the name of the egroup for this domain
string fwAccessControl_roleNameToEgroup ( string  roleName,
dyn_string &  exceptionInfo 
)

Converts role (group) name to a egroup name

To find a matching egroup, three methods are applied

  • a lookup in LDAP, with a filter on egroup type and name
  • if the previous fais, try to look up in the group-to-egroup mapping
  • if the previous also fails, try to look up from the groups full name; it should contain a string such as "EGROUP:xxxx", and then the "xxxx" is returned (actually the prefix should be the fwAccessControl_Egroup_FullNamePrefix constant)
Parameters
roleName(string) IN the name of the domain
exceptionInfo(dyn_string) OUT standard exception-handling variable
Returns
value of type 'string' the name of the role(group) for this domain
void fwAccessControl_egroupToAccessRight ( string  egroupName,
string &  accessRight,
int &  privNumber,
dyn_string &  exceptionInfo 
)

Extracts access right from a egroup name

The lookup is done in the following way

  • the details of privilege egroup are queried checking that the type is "fwAccessControl privilege"
  • the last string after the "-" character is the privilege name; the "__" string may be used to have spaces in the name
  • the last-but-one string before the "-" characters is the privilege number
  • the parent of the egroup is looked up (it needs to be of type "fwAccessControl domain", and then its name is decoded to become the domain name The domain name and privilege name are combined to get the accessRight string.
Parameters
egroupName(string) IN the name of the egroup (needs to be of "fwAccessControl privilege" type)
accessRight(string) OUT on return will contain the name of the access right in form of a "Domain:Privilege" string
privNumber(int) OUT on return will contain the privilege number inside the domain
exceptionInfo(dyn_string) OUT standard exception handling variable
string fwAccessControl_accessRightToEgroup ( string  accessRight,
dyn_string &  exceptionInfo 
)

Converts access right to a egroup name

To find a matching egroup the following is done

  • the access right is separated into domain name and privilege name
  • a egroup for domain is looked up
  • for the domain egroup, the list of "child" privilege egroups is retrieved
  • the one matching the privilege name is returned
Parameters
accessRight(string) IN the name of the access right, in the format "Domain:Privilege"; spaces in pivilege name are replaced to "__"
exceptionInfo(dyn_string) OUT standard exception handling variable
Returns
value of type 'string' the name of the egroup
void fwAccessControl_egroupGetDomainPrivileges ( string  domainEgroup,
dyn_string &  privilegeNames,
dyn_string &  privilegeEgroups,
dyn_string &  exceptionInfo 
)

Retrieves the list of privileges of a domain using LDAP query

Note that the egroups that are privileges need to :

  • be the members of the egroup that represents the domain
  • be of type (egroup topis) "fwAccessControl privilege"
  • follow the naming scheme of dash-separated strings, with the last being the privilege name and one-but-last is privilege number (level) ; for instance "MyDCS-Subdetector-3-expert" would yield a privilege level with number 3 and name expert
Parameters
domainEgroup(string) IN the name of the egroup for the domain
privilegeNames(dyn_string) OUT on return will contain the list of privilege names, sorting according to their numbers spaces in pivilege name are replaced to "__" in egroup names
privilegeEgroups(dyn_string) OUT on return will contain the list of egroup names corresponsing to the list in the privilegeNames
exceptionInfo(dyn_string) OUT standard exception-handling variable
void fwAccessControl_getConfigurationFromEgroup ( string  configurationEgroup,
dyn_string &  domainEgroups,
dyn_string &  domainNames,
dyn_string &  roleEgroups,
dyn_string &  roleNames,
dyn_string &  exceptionInfo 
)

Retrieve the EgroupSynchronization Configuration from LDAP

Parameters
configurationEgroup(string) IN the name of the configuration egroup
domainEgroups(dyn_string) OUT list of egroups defining domains in this configuration
domainNames(dyn_string) OUT list of names of the domains corresponding to domanEgroups
roleEgroups(dyn_string) OUT list of role (group) egroups in this configuration
roleNames(dyn_string) OUT list of role (group) banes corresponding to roleEgroups
exceptionInfo(dyn_string) OUT standard exception-handling variable
void fwAccessControl_getDomainFromEgroup ( string  domainEgroup,
string &  domainName,
string &  domainComment,
dyn_string &  privilegeEgroups,
dyn_string &  privilegeNames,
dyn_string &  exceptionInfo 
)

Retrieve domain information from a egroup using a LDAP query

Parameters
domainEgroup(string) IN the name of the domain egroup being queried
domainName(string) OUT returns the name of the domain
domainComment(string) OUT returns the comment of the domain as defined in the "description" attribute
privilegeEgroups(dyn_string) OUT returns the list of egroups for privileges inside the domain
privilegeNames(dyn_string) OUT returns the list of privilege names inside the domain (corresponding to privilegeEgroups )
exceptionInfo(dyn_string) OUT standard exception handling variable

A useful LDAP query that does the data extraction from the commandline:

/usr/bin/ldapsearch -x -h xldap.cern.ch -b "OU=e-groups,OU=Workgroups,DC=cern,DC=ch" "(&(adminDescription=fwAccessControl privilege)(memberOf=CN=test-fwACDomain-MyDCS,OU=e-groups,OU=Workgroups,DC=cern,DC=ch))" cn
void fwAccessControl_getRoleFromEgroup ( string  roleEgroup,
string &  roleName,
string &  roleComment,
dyn_string &  accessRights,
dyn_string &  privilegeEgroups,
dyn_string &  memberEgroups,
dyn_string &  childRoleEgroups,
dyn_string &  exceptionInfo 
)

Retrieve role information from a egroup using a LDAP query

Parameters
roleEgroup(string) IN the name of the role (group) egroup being queried
roleName(string) OUT returns the name of the role (group)
roleComment(string) OUT returns the comment of the role as defined in the "description" attribute
accessRights(dyn_string) OUT returns the list of access rights granted to this role; access rights are in the form "Domain:Privilege"
privilegeEgroups(dyn_string) OUT returns the list of egroups corresponding to accessRights
memberEgroups(dyn_string) OUT returns the list of member egroups (egroups that define lists of users)
childRoleEgroups(dyn_string) OUT returns the list of child role egroups (for role-inheritance)
exceptionInfo(dyn_string) OUT standard exception handling variable

Variable Documentation

const string fwAccessControl_egroupsBaseDN ="OU=e-groups,OU=Workgroups,DC=cern,DC=ch"

LDAP Base DN where egroups information is stored

const string fwAccessControl_Egroup_FullNamePrefix = "EGROUP:"

prefix in the full name of the role or domain specifying the egroup name

const string fwAccessControl_Egroup_topicConfiguration = "fwAccessControl configuration"

names of egroups "topics" used to distinguish the special egroups here