Configuring authorization by using LDAP groups

Authorize roles in App Connect Enterprise against a Lightweight Directory Access Protocol (LDAP) or Secure LDAP (LDAPS) server.

1. LDAP authorization can be applied only to LDAP authenticated users. If LDAP authentication is not enabled, enable it now as described in Enabling LDAP authentication.
2. Open the node.conf.yaml file for the integration node, or the server.conf.yaml file for the integration server by using a YAML editor.

   If you are not able to access a YAML editor, you can edit the file by using a plain text editor. You must ensure that you do not include any tab characters. Tab characters are not valid in YAML and would cause your configuration to fail. If you are using a plain text editor, ensure that you use a YAML validation tool to validate the content of your file.

   If you run commands that modify settings for an integration node, or an integration server that is managed by an integration node, the modified settings are saved in a .conf.yaml file. The .conf.yaml file is located in the overrides directory. For example, C:\ProgramData\IBM\MQSI\components\acev11node\overrides\node.conf.yaml for an integration node, and C:\ProgramData\IBM\MQSI\components\acev11node\servers\myNodeServer\overrides\server.conf.yaml for an integration server managed by an integration node. If a property is set in the integration node's base node.conf.yaml file, and also in the overrides directory (\overrides\node.conf.yaml), the property value that is set in the overrides directory is used. For more information, see Configuring an integration node by modifying the node.conf.yaml file.

   If you have previously run commands that modify the independent integration server, those modified settings are saved in a .conf.yaml file in the overrides directory, for example, <work directory>/overrides/server.conf.yaml. If a property is set in the integration server's server.conf.yaml file, and also in the overrides directory (/overrides/server.conf.yaml), the property value that is set in the overrides directory is used. For more information, see Configuring an integration server by modifying the server.conf.yaml file.

3. Enable authorization by setting the authorizationEnabled property value to true in the .yaml configuration file:

     #  Authorization
     authorizationEnabled: true     # Clients web user role will be authorized when set true  
   

4. Set the authorizationMode property to 'ldap' in the .yaml configuration file:

   authorizationMode: 'ldap'       # Set authorization mode. Choose 1 of : ldap, file or mq   
   

5. Optional: Create roles in App Connect Enterprise by configuring the .yaml configuration files.

   The roles viewRole and adminRole are supplied by default in the .yaml configuration file. The node.conf.yaml and server.conf.yaml files allow free-form names for roles that are not predefined in App Connect Enterprise. In the following example, the roles supportRole, manager, administrator and developer are created.

   Permissions:           
       # Set Admin Security Authorization file permissions by web user role using 'read+:write+:execute+' , or 'all+'
       # '+' grants permission, '-' denies permission
       # e.g. define the following web user roles 'viewRole' and 'adminRole'
       viewRole:  'read+:write-:execute-'
       adminRole: 'all+'adminRole: 'all+'
       
   
       supportRole:'read+:write-:execute+' 
       manager: 'read+:write-:execute-' 
       administrator:'all+' 
       developer: 'read+:write-:execute+' 
   

6. Set admin security authorization file permissions for roles in the .yaml configuration file, by specifying a combination of read, write, and execute, or all, with + to grant permission, and - to deny permission, for example:

   Permissions:           
       # Set Admin Security Authorization file permissions by web user role using 'read+:write+:execute+' , or 'all+'
       # '+' grants permission, '-' denies permission
       # e.g. define the following web user roles 'viewRole' and 'adminRole'
       viewRole:  'read+:write-:execute-'
       adminRole: 'all+'

   In this example, users with the role viewRole are granted read permission only, and users with the role adminRole have permission for all actions.

   This step is identical whether you are using LDAP authorization or file-based authorization. For more information, see Setting file-based permissions.

7. Optional: Set admin security authorization file permissions for roles in the .yaml configuration file for each named integration server managed by an integration node. Specify a combination of read, write, and execute, or all, with + to grant permission, and - to deny permission, for example:

   Server:
       # Set Admin Security Authorization file permissions for each named Integration Server
          #server01:
            #Permissions:
               viewRole:  'read+:write-:execute-'
               adminRole: 'all+'
          #server02:
             #Permissions:
               viewRole:  'read+:write-:execute+'
               adminRole: 'all+'
   

   In this example, users with the role adminRole have permission for all actions on server01 and server02. Users with the role viewRole are granted read permission only on server01, and read and execute permission on server02.

   This step is identical whether you are using LDAP authorization or file-based authorization. For more information, see Setting file-based permissions. Every integration server that is managed by an integration node inherits the appropriate permissions from the node.conf.yaml file. Integration servers do not inherit permission settings defined for the integration node itself.

8. Optional: Map values of LDAP attributes on LDAP objects to names of roles in App Connect Enterprise by configuring the .yaml configuration file, as shown in the following example:

   Security:
     LdapAuthorizeAttributeToRoleMap:
       'graham': 'adminRole'    # (user mapped to role)
       'martin': 'viewRole'    # (user mapped to role)
       'DB_ADMIN':'adminRole'      # (field mapped to role)
       'NETWORK_ADMIN':'viewRole'  # (field mapped to role)
       'o=AceViewersGroup',o=groups,ou=ace': 'viewRole'  # (group mapped to role)
       'o=AceAdminsGroup',o=groups,ou=ace':  'viewRole'  # (group mapped to role)
    

   If you have existing LDAP attributes and existing roles in App Connect Enterprise with different names, you must map from one to the other. If LDAP objects have attribute names that do not match names of defined roles in App Connect Enterprise, access is denied. You do not need to map in the following cases:

   • If values of LDAP group attributes match the names of roles in App Connect Enterprise.
   • If you configure LDAP attribute values to match names of existing roles in App Connect Enterprise.
   • If you create roles in App Connect Enterprise with names identical to values of LDAP attributes.

   The node.conf.yaml and server.conf.yaml files allow free-form names for roles that are not predefined in App Connect Enterprise.

   LDAP allows free-form names for values of attributes. The names of values of attributes are not predefined in LDAP.

   Note:

   In LDAP, roles in App Connect Enterprise are derived from LDAP group search attributes. For example, cn, dn, email, location.

   Multiple group membership gives the user multiple roles in App Connect Enterprise. For example, AceAdmin, AceViewer, AceDeveloper. When a user tries to perform an action, all roles are tried until permission is granted.

   Template syntax allows LDAP to use information about the authenticated user to search for groups. In the ldapAuthorizeUrl parameters in the .yaml configuration file, you can use {{dn}} to substitute the users distinguished name, and {{username}} to substitute the username.

   
   #ldapAuthorizeUrl: ldap[s]://server[:port]/baseDN[?[attr_name][?[base|sub]][?filter_expr]]  # ldap authorization search url

   ldap:

   (Required) An LDAP URL begins with the protocol prefix "ldap." The protocol prefix "ldap" indicates an entry or entries accessible from the LDAP server that is running on the specified hostname at the specified port number.

   s:

   (Optional) Specifies whether SSL is used. Default is not to use SSL.

   server:

   (Required) The name or IP address of the LDAP server to contact. You must use the same server that you used for authentication.

   port:

   (Required) The port to connect to. Default is 389 (non-SSL). For LDAP servers with SSL enabled, the port is typically 636.

   baseDN

   (Required) The LDAP Distinguished Name. It identifies the base object of the LDAP search.

   attr_name:

   (Optional) String used to indicate which attributes are returned from the entry. For example, uid, cn, or email address. Default is uid.

   base|sub:

   (Optional) Specifies the scope of the search to run in the specified LDAP server. The allowable scopes are "base" for a base object search, or "sub" for a subtree search. If base is defined, the authentication is faster because the DN of the user can be constructed from the attr_name, and baseDN values. If sub is selected, a search must be run before the DN can be resolved. Default is sub.

   filter_expr:

   (Optional) A valid LDAP filter expression that can use template syntax to substitute the details of the authenticated user; for example:

   • {{dn}} is replaced with the user's distinguished name.
   • {{username}} is replaced with the user's username attribute value.

   Therefore, you can use filters like the following examples.

   • (member={{dn}}) matches groups where the authenticated user's distinguished name is set as a member attribute value.
   • (cn={{username}}) matches an entry where the authenticated user's username is set as the cn attribute value.

You now have options on how to configure LDAP authorization.

• Authorize a single LDAP group to have a role in App Connect Enterprise. See step 9.
• Authorize multiple LDAP groups to have roles in App Connect Enterprise. See step 10.
• Authorize an LDAP authenticated user's LDAP attributes to have a role in App Connect Enterprise. See step 11.

9. Optional: Authorize a single LDAP group to have a role in IBM App Connect Enterprise by setting values for ldapAuthorizeUrl in the .yaml configuration file.

   Before you do this step, ensure that you set admin security authorization file permissions as required for roles in App Connect Enterprise. Also, ensure that you complete any required mapping of LDAP attribute names to names of roles in App Connect Enterprise.See step 5, step 6, step 7, and step 8.

   In the following example, an LDAP authenticated user, graham , is a member of a single group in LDAP, which has the distinguished name (dn) cn=administrator,ou=groups,o=ace , as shown in the following LDAP configurations:

    
    ObjectClass: Person
    dn: cn=graham,ou=users,o=ace
    cn: graham
   
   
    ObjectClass: groupOfNames
    dn: cn=administrator,ou=groups,o=ace
    cn: administrator
    Member: cn=graham,ou=users,o=ace
    Member: cn=martin,ou=users,o=ace
   

   To authorize the single LDAP group with distinguished name (dn) cn=administrator,ou=groups,o=ace to have the role adminRole in IBM App Connect Enterprise, set the values for ldapAuthorizeUrl in the .yaml configuration file as shown in the following example:

   • localhost is the server
   • :10389 is the port
   • o=groups,ou=ace is the baseDN (Distinguished name)
   • ?cn is the attr_name
   • ?sub indicates that a subset of the LDAP tree structure is to be searched
   • ?(member={{dn}}) is the filter_expr

   ldapAuthorizeUrl: 'ldap://localhost:10389/o=groups,ou=ace?cn?sub?(member={{dn}})'  # ldap authorization search url'  

   When the LDAP-authenticated user graham attempts to complete an action on the integration node or integration server, a search confirms that the LDAP distinguished name (dn) cn=administrator,ou=groups,o=ace is authorized to have the role adminRole in App Connect Enterprise. The LDAP-authenticated user graham is a member of the LDAP group cn=administrator,ou=groups,o=ace, so permission to complete the action is granted.

   For more information about the parameters in ldapAuthorizeUrl, see step 8.

10. Optional: Authorize multiple LDAP groups to roles in App Connect Enterprise by setting values for ldapAuthorizeUrl in the .yaml configuration file.

    Before you do this step, ensure that you set admin security authorization file permissions as required for roles in App Connect Enterprise. Also, ensure that you complete any required mapping of LDAP attribute names to names of roles in App Connect Enterprise. See step 5, step 6, step 7, and step 8.

    In the following example, the LDAP-authenticated user, martin, is a member of two groups in LDAP, with the distinguished names (dn) cn=administrator,ou=groups,o=ace, and cn=viewer,ou=groups,o=ace, as shown in the following LDAP configurations:

    
     ObjectClass: Person
     dn: cn=martin,ou=users,o=ace
     cn: martin
    
     ObjectClass: groupOfNames
     dn: cn=administrator,ou=groups,o=ace
     cn: administrator
     Member: cn=graham,ou=users,o=ace
     Member: cn=martin,ou=users,o=ace
    
     ObjectClass: groupOfNames
     dn: cn=viewer,ou=groups,o=ace
     cn: viewer
     Member: cn=graham,ou=users,o=ace
     Member: cn=martin,ou=users,o=ace

    To authorize the LDAP group with distinguished name (dn) cn=administrator,ou=groups,o=ace to have the role adminRole in App Connect Enterprise, and authorize the LDAP group with distinguished name (dn) cn=viewer,ou=groups,o=ace to have the role, viewRole in App Connect Enterprise, configure the .conf.yaml file with the values in the following example:

    • localhost is the server
    • :10389 is the port
    • o=groups,ou=ace is the baseDN (Distinguished name)
    • ?cn is the attr_name
    • ?sub indicates that a subset of the LDAP tree structure is to be searched
    • ?(member={{dn}}) is the filter_expr

    ldapAuthorizeUrl: 'ldapAuthorizeUrl: 'ldap://localhost:10389/o=groups,ou=ace?cn?sub?(member={{dn}})'  # ldap authorization search url'  
    

    When the LDAP-authenticated user martin attempts to complete an action on the integration node or integration server, a search confirms that the LDAP distinguished name (dn) cn=viewer,ou=groups,o=ace is authorized to have the role viewRole in App Connect Enterprise. The LDAP-authenticated user martin is a member of the LDAP group cn=viewer,ou=groups,o=ace. Therefore, the user martin is granted the permissions that are set for the role viewRole in the .yaml configuration file of the integration server or integration node. See step 6 and step 7. Each role is checked until permission is either granted or rejected. The LDAP-authenticated user martin is also a member of the LDAP group cn=administrator,ou=groups,o=ace. Therefore, the user martin is granted the permissions that are set for the role adminRole in the .yaml configuration file of the integration server or integration node.

    For more information about the parameters in ldapAuthorizeUrl, see step 8.

11. Optional: Authorize an authenticated user's LDAP attributes to have a role in App Connect Enterprise by setting values for ldapAuthorizeUrl in the .yaml configuration file.

    Before you do this step, set admin security authorization file permissions as required for roles in App Connect Enterprise. Also, complete any required mapping of LDAP attribute names to names of roles in App Connect Enterprise.See step 5, step 6, step 7, and step 8.

    In the following example, the LDAP attribute job has the value administrator as shown in the following LDAP configuration:

    
     ObjectClass: Person
     dn: cn=graham,ou=users,o=ace
     cn: graham
     job:administrator

    To authorize the LDAP attribute job with the value administrator to have the role adminRole in App Connect Enterprise, configure the .conf.yaml file with the values that are shown in the following example:

    • localhost is the server
    • :10389 is the port
    • o=users,ou=ace is the baseDN (Distinguished name)
    • ?job is the attr_name
    • ?sub indicates that a subset of the LDAP tree structure is to be searched
    • cn={{username}} is the filter_expr

    ldapAuthorizeUrl: 'ldap://localhost:10389/o=users,ou=ace?job?sub?(cn={{username}}) # ldap authorization search url'
    

    The LDAP-authenticated user graham attempts to complete an action on the integration node or integration server. A search confirms that the LDAP attribute name job, with the value administrator is authorized to have the role adminRole in App Connect Enterprise. The LDAP-authenticated user graham has an LDAP attribute job with the value, administrator, so permission to complete the action is granted.

    For more information about the parameters in ldapAuthorizeUrl, see step 8.

12. Save the modified file.
13. Restart the integration node or integration server for the changes to take effect.

# Admin Security
  #  Authentication
  basicAuth: true                                                    
  ldapUrl: 'ldap://localhost:10389/ou=users,o=ace?cn?sub'  
  #ldapBindDn: ldap::adminAuthentication                              
  #ldapBindPassword: ldap::adminAuthentication                        
  #  Authorization
  authorizationEnabled: true     # Clients web user role will be authorized when set true
  authorizationMode: 'ldap'       # Set authorization mode. Choose 1 of : ldap, file or mq                   
  ldapAuthorizeUrl: 'ldap://localhost:10389/o=users,ou=ace?description?sub?(member={{dn}})'  
  #ldapAuthorizeUrl: 'ldap://localhost:10389/o=groups,ou=ace?employeeType?sub?(cn={{username}})'  
  

Security:
  LdapAuthorizeAttributeToRoleMap:
    'graham': 'adminRole'    # (user mapped to role)
    'martin': 'viewRole'    # (user mapped to role)
    'DB_ADMIN':'adminRole'      # (field mapped to role)
    'NETWORK_ADMIN':'viewRole'  # (field mapped to role)
    'o=AceViewersGroup',o=groups,ou=ace': 'viewRole'  # (group mapped to role)
    'o=AceAdminsGroup',o=groups,ou=ace':  'viewRole'  # (group mapped to role)
    
    'administrators':'adminRole'
    'developers': 'supportRole'
    'managers': 'viewRole' 
    
  Permissions:
    # Set Admin Security Authorization file permissions by web user role using 'read+:write+:execute+' , or 'all+'
    # '+' grants permission, '-' denies permission
    # e.g. define the following web user roles 'viewRole' and 'adminRole'
    viewRole:  'read+:write-:execute-'
    adminRole: 'all+'
    supportRole:'read+:write-:execute+' 

    #manager: 'read+:write-:execute-' 
    #administrator:'all+' 
    #developer: 'read+:write-:execute+' 

Server:
    # Set Admin Security Authorization file permissions for each named Integration Server
       #server01:
         #Permissions:
            viewRole:  'read+:write-:execute-'
            adminRole: 'all+'
       #server02:
          #Permissions:
            viewRole:  'read+:write-:execute+'
            adminRole: 'all+'