Request a Demo
4.6. Integration with OpenLDAP and Active Directory
Prev UpChapter 4. Installation and SetupHome Next

4.6. Integration with OpenLDAP and Active Directory #

PPEM supports authentication using the directory services OpenLDAP and Active Directory. Within the integration, roles are assigned to LDAP users in the web application using directory service user groups.

For more information about authentication and authorization, refer to Authentication and Authorization Operation Scheme.

The integration process includes the following steps:

Create a User Group in a Directory Service

Create a user group in OpenLDAP or Active Directory. For Active Directory, two ways of creating a user group are supported:

Important

Users added to groups must be created in OpenLDAP or Active Directory with the following configuration parameters required for PPEM:

  • first_name: The first name of the user.

  • last_name: The last name of the user.

  • email: The email address of the user.

  • login: The login of the user.

  • password: The password of the user.

You must specify a value in the string format for each parameter.

For more information about creating user groups, refer to the official OpenLDAP documentation or to the official Microsoft documentation on Active Directory.

Create a User Group in OpenLDAP

  1. Create a user group configuration file in the LDIF format and specify the following parameters: 

    dn: user_group_DN
objectClass: posixGroup
cn: user_group_name
gidNumber: user_group_ID
memberUid: user_ID

    Where:

    • dn: The distinguished name (DN) of the user group.

      You can specify the following attributes:

      • cn: The unique name of the user group.

      • ou: The organizational unit where the user group will be located.

      • dc: The components of the domain that will be associated with the user group. For example, example.com.

    • cn: The unique name of the user group.

    • gidNumber: The unique ID of the user group.

    • memberUid: The unique IDs of users that will be added to the group.

  2. Create a user group in OpenLDAP: 

    ldapadd -x -D "cn=admin,dc=example,dc=com" -W -f example-group.ldif

    Where:

    • -D: The distinguished name of the OpenLDAP administrator.

    • -W: The password request.

    • -f: The name of the user group configuration file.

  3. Ensure that the user group was created successfully: 

    ldapsearch -x -b "ou=groups,dc=example,dc=com" "(cn=examplegroup)"

Create a User Group in Active Directory using ADUC

  1. In the Active Directory GUI, go to the organizational unit (OU) where the user group will be located.

  2. Click Create → Group.

  3. In the opened window, specify the user group parameters.

  4. Click OK.

  5. Add users to the group:

    1. Go to the user group properties by double-clicking it.

    2. Select Member Of and add users to the group.

Create a User Group in Active Directory Using PowerShell

  1. Create a user group: 

    New-ADGroup -Path "OU=Groups,OU=Example,DC=example,DC=com" -Name "GROUPMSAD" -GroupScope Global -GroupCategory Distribution

    Where:

    • -Path: The distinguished name (DN) of the user group.

      You can specify the following attributes:

      • OU: The organizational unit where the user group will be located.

      • DC: The components of the domain that will be associated with the user group.

    • -Name: The unique name of the user group.

  2. Add users to the group: 

    Add -ADGroupMember GROUPMSAD -Members user1,user2,user3

    Where:

    • -ADGroupMember: The unique name of the group to which users will be added.

    • -Members: The unique IDs of users that will be added to the group.

Configure Integration with a Directory Service

  1. In the ppem-manager.yml manager configuration file, add the ldap section and specify integration parameters:

    • OpenLDAP: 

      ldap:
type: directory_service_type
url: directory_service_network_address
use_ssl: true or false
base_dn: directory_service_base_DN
bind_username: directory_service_username
bind_password: directory_service_user_password
group_class: user_group_object_class
group_members_attr: user_group_member_attribute
group_name_attr: user_group_name_attribute
prefix_group_dn: DN_prefix_for_user_groups
prefix_user_dn: DN_prefix_for_users
user_class: user_object_class
user_display_name_attr: user_display_name_attribute
user_email_attr: user_email_attribute
user_name_attr: user_login_attribute
user_first_name_attr: user_first_name_attribute
user_last_name_attr: user_last_name_attribute
user_job_title_attr: user_job_title_attribute
user_membership_attr: user_group_membership_attribute
user_phone_attr: user_phone_attribute
user_sync_interval: manager_and_directory_service_synchronization_time

    • Active Directory: 

      ldap:
type: directory_service_type
url: directory_service_network_address
base_dn: directory_service_base_DN
bind_username: directory_service_username
bind_password: directory_service_user_password
user_sync_interval: manager_and_directory_service_synchronization_time

    Where:

    • type: The type of the directory service.

      Possible values:

      • openldap

      • ms_active_directory

    • url: The network address of the directory service.

    • bind_username: The name of the directory service user for integration with PPEM.

      The value format depends on the directory service:

      • For OpenLDAP, a complete distinguished name (DN) is usually specified. For example, cn=admin,ou=users,dc=example,dc=com.

      • For Active Directory, a value in the username@domain format is usually specified. For example, admin@example.com.

    • bind_password: The password of the directory service user for integrating with PPEM.

    • base_dn: The base distinguished name of the directory service.

    • prefix_user_dn: The distinguished name prefix for users.

      If this parameter is specified, users are searched using the prefix_user_dn,base_dn distinguished name. To search for users in the entire directory, specify "".

      Optional parameter.

    • prefix_group_dn: The distinguished name prefix for user groups.

      If this parameter is specified, user groups are searched using the prefix_group_dn,base_dn distinguished name. To search for user groups in the entire directory, specify "".

      Optional parameter.

    • user_class: The name of the user object class.

      Optional parameter for Active Directory.

    • user_name_attr: The name of the user login attribute.

      Default value: cn for OpenLDAP, sAMAccountName for Active Directory.

      Optional parameter for Active Directory.

    • user_first_name_attr: The name of the user first name attribute.

      Default value: givenName.

      Optional parameter.

    • user_last_name_attr: The name of the user last name attribute.

      Default value: sn.

      Optional parameter.

    • user_display_name_attr: The name of the user display name attribute.

      Default value: displayName.

      Optional parameter.

    • user_email_attr: The name of the user email address attribute.

      Default value: mail.

      Optional parameter.

    • user_phone_attr: The name of the user phone number attribute.

      Default value: telephoneNumber.

      Optional parameter.

    • user_job_title_attr: The name of the user job title attribute.

      Default value: title.

      Optional parameter.

    • user_membership_attr: The name of the user group membership attribute.

      Default value for Active Directory: memberOf.

      Optional parameter.

    • group_class: The name of the user group object class.

      Default value for Active Directory: group.

    • group_name_attr: The name of the user group name attribute.

      Default value: cn.

      Optional parameter.

    • group_members_attr: The name of the group member attribute.

    • group_filter: The filter for searching user groups. For example, (&(objectClass=group)(cn=*PPEM*)).

      Optional parameter.

    • group_membership_filter: The filter for searching groups of which the specified user is a member. For example, (&(objectClass=group)(uniqueMember=%USER_DN%)).

      Optional parameter.

    • group_list_size_limit: The maximum number of user groups that can be received from the directory service.

      Optional parameter.

    • user_sync_interval: Synchronization time between the manager and directory service.

      Default value: 5m.

      Optional parameter.

    • ssl_cert_skip_verify: Specifies whether verification of the directory service server certificate is skipped.

      Possible values:

      • true

      • false

      Optional parameter.

    • ssl_root_ca: The path to the file in the PEM format with the CA certificate on the directory service server.

      Optional parameter.

  2. Restart the PPEM service: 

    systemctl restart ppem.service

Configure Authorization in PPEM

  1. Log in to the web application under a user with the System administrator role.

    For more information about roles, refer to User Roles and Privileges.

  2. Create a user group.

    In doing so, from LDAP group, select the LDAP group for which you want to configure authorization. If the LDAP group is not displayed, ensure that you configured integration with the directory service correctly.

    Roles assigned to a user group at its creation will be automatically assigned to users from the specified LDAP group when they log in to the web application.

Checking Authentication and Authorization in PPEM

  1. Log in to the web application under a directory service user. The user must be a member of the LDAP group specified when configuring authorization in PPEM.

    The login format depends on the directory service:

    • For OpenLDAP, a short user login is usually specified. For example, j.doe.

    • For Active Directory, a login in the username@domain format is usually specified. For example, j.doe@example.com.

  2. If authentication is successful, check authorization in one of the following ways:

    • In the top-right corner of the page, click the username.

      The personal account will open. It displays the email address, job title, and assigned roles of the user.

    • If you logged in to the web application under a user with the System administrator role, in the navigation panel, go to Users.

      The table of users will be displayed. Distinguished names (DNs) of LDAP users are displayed in the Login column.

Troubleshoot Authentication

The manager log is used for troubleshooting authentication.

You can specify logging parameters in the ppem-manager.yml manager configuration file. Logging can be done in a separate file or in the system journal (journalctl).

To troubleshoot authentication:

  1. Connect to the server where the manager is installed.

  2. View the manager log:

    • If logging is done in a separate file: 

      -- Output recent PPEM errors --
tail -n 1000 "path_to_the_PPEM_log_file" | grep ERROR

    • If logging is done in the system journal: 

      -- Output PPEM errors for the last 5 minutes --
journalctl --since "5m ago" -u ppem.service -g ERROR

  3. Perform the actions required for troubleshooting authentication.

Prev Up Next
4.5. Integration with External Data Sources Home 4.7. Connecting the Manager and Agents to Instances via SSL
epub pdf