BookStack Code Mirror - bookstack/blob - app/Access/LdapService.php

   1 <?php
   2
   3 namespace BookStack\Access;
   4
   5 use BookStack\Exceptions\JsonDebugException;
   6 use BookStack\Exceptions\LdapException;
   7 use BookStack\Uploads\UserAvatars;
   8 use BookStack\Users\Models\User;
   9 use ErrorException;
  10 use Illuminate\Support\Facades\Log;
  11
  12 /**
  13  * Class LdapService
  14  * Handles any app-specific LDAP tasks.
  15  */
  16 class LdapService
  17 {
  18     /**
  19      * @var resource|\LDAP\Connection
  20      */
  21     protected $ldapConnection;
  22
  23     protected array $config;
  24     protected bool $enabled;
  25
  26     public function __construct(
  27         protected Ldap $ldap,
  28         protected UserAvatars $userAvatars,
  29         protected GroupSyncService $groupSyncService
  30     ) {
  31         $this->config = config('services.ldap');
  32         $this->enabled = config('auth.method') === 'ldap';
  33     }
  34
  35     /**
  36      * Check if groups should be synced.
  37      */
  38     public function shouldSyncGroups(): bool
  39     {
  40         return $this->enabled && $this->config['user_to_groups'] !== false;
  41     }
  42
  43     /**
  44      * Search for attributes for a specific user on the ldap.
  45      *
  46      * @throws LdapException
  47      */
  48     private function getUserWithAttributes(string $userName, array $attributes): ?array
  49     {
  50         $ldapConnection = $this->getConnection();
  51         $this->bindSystemUser($ldapConnection);
  52
  53         // Clean attributes
  54         foreach ($attributes as $index => $attribute) {
  55             if (str_starts_with($attribute, 'BIN;')) {
  56                 $attributes[$index] = substr($attribute, strlen('BIN;'));
  57             }
  58         }
  59
  60         // Find user
  61         $userFilter = $this->buildFilter($this->config['user_filter'], ['user' => $userName]);
  62         $baseDn = $this->config['base_dn'];
  63
  64         $followReferrals = $this->config['follow_referrals'] ? 1 : 0;
  65         $this->ldap->setOption($ldapConnection, LDAP_OPT_REFERRALS, $followReferrals);
  66         $users = $this->ldap->searchAndGetEntries($ldapConnection, $baseDn, $userFilter, $attributes);
  67         if ($users['count'] === 0) {
  68             return null;
  69         }
  70
  71         return $users[0];
  72     }
  73
  74     /**
  75      * Get the details of a user from LDAP using the given username.
  76      * User found via configurable user filter.
  77      *
  78      * @throws LdapException|JsonDebugException
  79      */
  80     public function getUserDetails(string $userName): ?array
  81     {
  82         $idAttr = $this->config['id_attribute'];
  83         $emailAttr = $this->config['email_attribute'];
  84         $displayNameAttr = $this->config['display_name_attribute'];
  85         $thumbnailAttr = $this->config['thumbnail_attribute'];
  86
  87         $user = $this->getUserWithAttributes($userName, array_filter([
  88             'cn', 'dn', $idAttr, $emailAttr, $displayNameAttr, $thumbnailAttr,
  89         ]));
  90
  91         if (is_null($user)) {
  92             return null;
  93         }
  94
  95         $userCn = $this->getUserResponseProperty($user, 'cn', null);
  96         $formatted = [
  97             'uid'   => $this->getUserResponseProperty($user, $idAttr, $user['dn']),
  98             'name'  => $this->getUserResponseProperty($user, $displayNameAttr, $userCn),
  99             'dn'    => $user['dn'],
 100             'email' => $this->getUserResponseProperty($user, $emailAttr, null),
 101             'avatar' => $thumbnailAttr ? $this->getUserResponseProperty($user, $thumbnailAttr, null) : null,
 102         ];
 103
 104         if ($this->config['dump_user_details']) {
 105             throw new JsonDebugException([
 106                 'details_from_ldap'        => $user,
 107                 'details_bookstack_parsed' => $formatted,
 108             ]);
 109         }
 110
 111         return $formatted;
 112     }
 113
 114     /**
 115      * Get a property from an LDAP user response fetch.
 116      * Handles properties potentially being part of an array.
 117      * If the given key is prefixed with 'BIN;', that indicator will be stripped
 118      * from the key and any fetched values will be converted from binary to hex.
 119      */
 120     protected function getUserResponseProperty(array $userDetails, string $propertyKey, $defaultValue)
 121     {
 122         $isBinary = str_starts_with($propertyKey, 'BIN;');
 123         $propertyKey = strtolower($propertyKey);
 124         $value = $defaultValue;
 125
 126         if ($isBinary) {
 127             $propertyKey = substr($propertyKey, strlen('BIN;'));
 128         }
 129
 130         if (isset($userDetails[$propertyKey])) {
 131             $value = (is_array($userDetails[$propertyKey]) ? $userDetails[$propertyKey][0] : $userDetails[$propertyKey]);
 132             if ($isBinary) {
 133                 $value = bin2hex($value);
 134             }
 135         }
 136
 137         return $value;
 138     }
 139
 140     /**
 141      * Check if the given credentials are valid for the given user.
 142      *
 143      * @throws LdapException
 144      */
 145     public function validateUserCredentials(?array $ldapUserDetails, string $password): bool
 146     {
 147         if (is_null($ldapUserDetails)) {
 148             return false;
 149         }
 150
 151         $ldapConnection = $this->getConnection();
 152
 153         try {
 154             $ldapBind = $this->ldap->bind($ldapConnection, $ldapUserDetails['dn'], $password);
 155         } catch (ErrorException $e) {
 156             $ldapBind = false;
 157         }
 158
 159         return $ldapBind;
 160     }
 161
 162     /**
 163      * Bind the system user to the LDAP connection using the given credentials
 164      * otherwise anonymous access is attempted.
 165      *
 166      * @param resource|\LDAP\Connection $connection
 167      *
 168      * @throws LdapException
 169      */
 170     protected function bindSystemUser($connection): void
 171     {
 172         $ldapDn = $this->config['dn'];
 173         $ldapPass = $this->config['pass'];
 174
 175         $isAnonymous = ($ldapDn === false || $ldapPass === false);
 176         if ($isAnonymous) {
 177             $ldapBind = $this->ldap->bind($connection);
 178         } else {
 179             $ldapBind = $this->ldap->bind($connection, $ldapDn, $ldapPass);
 180         }
 181
 182         if (!$ldapBind) {
 183             throw new LdapException(($isAnonymous ? trans('errors.ldap_fail_anonymous') : trans('errors.ldap_fail_authed')));
 184         }
 185     }
 186
 187     /**
 188      * Get the connection to the LDAP server.
 189      * Creates a new connection if one does not exist.
 190      *
 191      * @throws LdapException
 192      *
 193      * @return resource|\LDAP\Connection
 194      */
 195     protected function getConnection()
 196     {
 197         if ($this->ldapConnection !== null) {
 198             return $this->ldapConnection;
 199         }
 200
 201         // Check LDAP extension in installed
 202         if (!function_exists('ldap_connect') && config('app.env') !== 'testing') {
 203             throw new LdapException(trans('errors.ldap_extension_not_installed'));
 204         }
 205
 206         // Disable certificate verification.
 207         // This option works globally and must be set before a connection is created.
 208         if ($this->config['tls_insecure']) {
 209             $this->ldap->setOption(null, LDAP_OPT_X_TLS_REQUIRE_CERT, LDAP_OPT_X_TLS_NEVER);
 210         }
 211
 212         // Configure any user-provided CA cert files for LDAP.
 213         // This option works globally and must be set before a connection is created.
 214         if ($this->config['tls_ca_cert']) {
 215             $this->configureTlsCaCerts($this->config['tls_ca_cert']);
 216         }
 217
 218         $ldapHost = $this->parseServerString($this->config['server']);
 219         $ldapConnection = $this->ldap->connect($ldapHost);
 220
 221         if ($ldapConnection === false) {
 222             throw new LdapException(trans('errors.ldap_cannot_connect'));
 223         }
 224
 225         // Set any required options
 226         if ($this->config['version']) {
 227             $this->ldap->setVersion($ldapConnection, $this->config['version']);
 228         }
 229
 230         // Start and verify TLS if it's enabled
 231         if ($this->config['start_tls']) {
 232             try {
 233                 $started = $this->ldap->startTls($ldapConnection);
 234             } catch (\Exception $exception) {
 235                 $error = $exception->getMessage() . ' :: ' . ldap_error($ldapConnection);
 236                 ldap_get_option($ldapConnection, LDAP_OPT_DIAGNOSTIC_MESSAGE, $detail);
 237                 Log::info("LDAP STARTTLS failure: {$error} {$detail}");
 238                 throw new LdapException('Could not start TLS connection. Further details in the application log.');
 239             }
 240             if (!$started) {
 241                 throw new LdapException('Could not start TLS connection');
 242             }
 243         }
 244
 245         $this->ldapConnection = $ldapConnection;
 246
 247         return $this->ldapConnection;
 248     }
 249
 250     /**
 251      * Configure TLS CA certs globally for ldap use.
 252      * This will detect if the given path is a directory or file, and set the relevant
 253      * LDAP TLS options appropriately otherwise throw an exception if no file/folder found.
 254      *
 255      * Note: When using a folder, certificates are expected to be correctly named by hash
 256      * which can be done via the c_rehash utility.
 257      *
 258      * @throws LdapException
 259      */
 260     protected function configureTlsCaCerts(string $caCertPath): void
 261     {
 262         $errMessage = "Provided path [{$caCertPath}] for LDAP TLS CA certs could not be resolved to an existing location";
 263         $path = realpath($caCertPath);
 264         if ($path === false) {
 265             throw new LdapException($errMessage);
 266         }
 267
 268         if (is_dir($path)) {
 269             $this->ldap->setOption(null, LDAP_OPT_X_TLS_CACERTDIR, $path);
 270         } else if (is_file($path)) {
 271             $this->ldap->setOption(null, LDAP_OPT_X_TLS_CACERTFILE, $path);
 272         } else {
 273             throw new LdapException($errMessage);
 274         }
 275     }
 276
 277     /**
 278      * Parse an LDAP server string and return the host suitable for a connection.
 279      * Is flexible to formats such as 'ldap.example.com:8069' or 'ldaps://ldap.example.com'.
 280      */
 281     protected function parseServerString(string $serverString): string
 282     {
 283         if (str_starts_with($serverString, 'ldaps://') || str_starts_with($serverString, 'ldap://')) {
 284             return $serverString;
 285         }
 286
 287         return "ldap://{$serverString}";
 288     }
 289
 290     /**
 291      * Build a filter string by injecting common variables.
 292      * Both "${var}" and "{var}" style placeholders are supported.
 293      * Dollar based are old format but supported for compatibility.
 294      */
 295     protected function buildFilter(string $filterString, array $attrs): string
 296     {
 297         $newAttrs = [];
 298         foreach ($attrs as $key => $attrText) {
 299             $escapedText = $this->ldap->escape($attrText);
 300             $oldVarKey = '${' . $key . '}';
 301             $newVarKey = '{' . $key . '}';
 302             $newAttrs[$oldVarKey] = $escapedText;
 303             $newAttrs[$newVarKey] = $escapedText;
 304         }
 305
 306         return strtr($filterString, $newAttrs);
 307     }
 308
 309     /**
 310      * Get the groups a user is a part of on ldap.
 311      *
 312      * @throws LdapException
 313      * @throws JsonDebugException
 314      */
 315     public function getUserGroups(string $userName): array
 316     {
 317         $groupsAttr = $this->config['group_attribute'];
 318         $user = $this->getUserWithAttributes($userName, [$groupsAttr]);
 319
 320         if ($user === null) {
 321             return [];
 322         }
 323
 324         $userGroups = $this->groupFilter($user);
 325         $allGroups = $this->getGroupsRecursive($userGroups, []);
 326
 327         if ($this->config['dump_user_groups']) {
 328             throw new JsonDebugException([
 329                 'details_from_ldap'             => $user,
 330                 'parsed_direct_user_groups'     => $userGroups,
 331                 'parsed_recursive_user_groups'  => $allGroups,
 332             ]);
 333         }
 334
 335         return $allGroups;
 336     }
 337
 338     /**
 339      * Get the parent groups of an array of groups.
 340      *
 341      * @throws LdapException
 342      */
 343     private function getGroupsRecursive(array $groupsArray, array $checked): array
 344     {
 345         $groupsToAdd = [];
 346         foreach ($groupsArray as $groupName) {
 347             if (in_array($groupName, $checked)) {
 348                 continue;
 349             }
 350
 351             $parentGroups = $this->getGroupGroups($groupName);
 352             $groupsToAdd = array_merge($groupsToAdd, $parentGroups);
 353             $checked[] = $groupName;
 354         }
 355
 356         $groupsArray = array_unique(array_merge($groupsArray, $groupsToAdd), SORT_REGULAR);
 357
 358         if (empty($groupsToAdd)) {
 359             return $groupsArray;
 360         }
 361
 362         return $this->getGroupsRecursive($groupsArray, $checked);
 363     }
 364
 365     /**
 366      * Get the parent groups of a single group.
 367      *
 368      * @throws LdapException
 369      */
 370     private function getGroupGroups(string $groupName): array
 371     {
 372         $ldapConnection = $this->getConnection();
 373         $this->bindSystemUser($ldapConnection);
 374
 375         $followReferrals = $this->config['follow_referrals'] ? 1 : 0;
 376         $this->ldap->setOption($ldapConnection, LDAP_OPT_REFERRALS, $followReferrals);
 377
 378         $baseDn = $this->config['base_dn'];
 379         $groupsAttr = strtolower($this->config['group_attribute']);
 380
 381         $groupFilter = 'CN=' . $this->ldap->escape($groupName);
 382         $groups = $this->ldap->searchAndGetEntries($ldapConnection, $baseDn, $groupFilter, [$groupsAttr]);
 383         if ($groups['count'] === 0) {
 384             return [];
 385         }
 386
 387         return $this->groupFilter($groups[0]);
 388     }
 389
 390     /**
 391      * Filter out LDAP CN and DN language in a ldap search return.
 392      * Gets the base CN (common name) of the string.
 393      */
 394     protected function groupFilter(array $userGroupSearchResponse): array
 395     {
 396         $groupsAttr = strtolower($this->config['group_attribute']);
 397         $ldapGroups = [];
 398         $count = 0;
 399
 400         if (isset($userGroupSearchResponse[$groupsAttr]['count'])) {
 401             $count = (int) $userGroupSearchResponse[$groupsAttr]['count'];
 402         }
 403
 404         for ($i = 0; $i < $count; $i++) {
 405             $dnComponents = $this->ldap->explodeDn($userGroupSearchResponse[$groupsAttr][$i], 1);
 406             if (!in_array($dnComponents[0], $ldapGroups)) {
 407                 $ldapGroups[] = $dnComponents[0];
 408             }
 409         }
 410
 411         return $ldapGroups;
 412     }
 413
 414     /**
 415      * Sync the LDAP groups to the user roles for the current user.
 416      *
 417      * @throws LdapException
 418      * @throws JsonDebugException
 419      */
 420     public function syncGroups(User $user, string $username): void
 421     {
 422         $userLdapGroups = $this->getUserGroups($username);
 423         $this->groupSyncService->syncUserWithFoundGroups($user, $userLdapGroups, $this->config['remove_from_groups']);
 424     }
 425
 426     /**
 427      * Save and attach an avatar image, if found in the ldap details, and attach
 428      * to the given user model.
 429      */
 430     public function saveAndAttachAvatar(User $user, array $ldapUserDetails): void
 431     {
 432         if (is_null(config('services.ldap.thumbnail_attribute')) || is_null($ldapUserDetails['avatar'])) {
 433             return;
 434         }
 435
 436         try {
 437             $imageData = $ldapUserDetails['avatar'];
 438             $this->userAvatars->assignToUserFromExistingData($user, $imageData, 'jpg');
 439         } catch (\Exception $exception) {
 440             Log::info("Failed to use avatar image from LDAP data for user id {$user->id}");
 441         }
 442     }
 443 }