BookStack Code Mirror - bookstack/blob - app/Auth/Access/Saml2Service.php

   1 <?php namespace BookStack\Auth\Access;
   2
   3 use BookStack\Auth\User;
   4 use BookStack\Exceptions\JsonDebugException;
   5 use BookStack\Exceptions\SamlException;
   6 use BookStack\Exceptions\UserRegistrationException;
   7 use Exception;
   8 use OneLogin\Saml2\Auth;
   9 use OneLogin\Saml2\Error;
  10 use OneLogin\Saml2\IdPMetadataParser;
  11 use OneLogin\Saml2\ValidationError;
  12
  13 /**
  14  * Class Saml2Service
  15  * Handles any app-specific SAML tasks.
  16  */
  17 class Saml2Service extends ExternalAuthService
  18 {
  19     protected $config;
  20
  21     /**
  22      * Saml2Service constructor.
  23      */
  24     public function __construct(RegistrationService $registrationService, User $user)
  25     {
  26         parent::__construct($registrationService, $user);
  27
  28         $this->config = config('saml2');
  29     }
  30
  31     /**
  32      * Initiate a login flow.
  33      * @throws Error
  34      */
  35     public function login(): array
  36     {
  37         $toolKit = $this->getToolkit();
  38         $returnRoute = url('/saml2/acs');
  39         return [
  40             'url' => $toolKit->login($returnRoute, [], false, false, true),
  41             'id' => $toolKit->getLastRequestID(),
  42         ];
  43     }
  44
  45     /**
  46      * Initiate a logout flow.
  47      * @throws Error
  48      */
  49     public function logout(): array
  50     {
  51         $toolKit = $this->getToolkit();
  52         $returnRoute = url('/');
  53
  54         try {
  55             $url = $toolKit->logout($returnRoute, [], null, null, true);
  56             $id = $toolKit->getLastRequestID();
  57         } catch (Error $error) {
  58             if ($error->getCode() !== Error::SAML_SINGLE_LOGOUT_NOT_SUPPORTED) {
  59                 throw $error;
  60             }
  61
  62             $this->actionLogout();
  63             $url = '/';
  64             $id = null;
  65         }
  66
  67         return ['url' => $url, 'id' => $id];
  68     }
  69
  70     /**
  71      * Process the ACS response from the idp and return the
  72      * matching, or new if registration active, user matched to the idp.
  73      * Returns null if not authenticated.
  74      * @throws Error
  75      * @throws SamlException
  76      * @throws ValidationError
  77      * @throws JsonDebugException
  78      * @throws UserRegistrationException
  79      */
  80     public function processAcsResponse(?string $requestId): ?User
  81     {
  82         $toolkit = $this->getToolkit();
  83         $toolkit->processResponse($requestId);
  84         $errors = $toolkit->getErrors();
  85
  86         if (!empty($errors)) {
  87             throw new Error(
  88                 'Invalid ACS Response: '.implode(', ', $errors)
  89             );
  90         }
  91
  92         if (!$toolkit->isAuthenticated()) {
  93             return null;
  94         }
  95
  96         $attrs = $toolkit->getAttributes();
  97         $id = $toolkit->getNameId();
  98
  99         return $this->processLoginCallback($id, $attrs);
 100     }
 101
 102     /**
 103      * Process a response for the single logout service.
 104      * @throws Error
 105      */
 106     public function processSlsResponse(?string $requestId): ?string
 107     {
 108         $toolkit = $this->getToolkit();
 109         $redirect = $toolkit->processSLO(true, $requestId, false, null, true);
 110
 111         $errors = $toolkit->getErrors();
 112
 113         if (!empty($errors)) {
 114             throw new Error(
 115                 'Invalid SLS Response: '.implode(', ', $errors)
 116             );
 117         }
 118
 119         $this->actionLogout();
 120         return $redirect;
 121     }
 122
 123     /**
 124      * Do the required actions to log a user out.
 125      */
 126     protected function actionLogout()
 127     {
 128         auth()->logout();
 129         session()->invalidate();
 130     }
 131
 132     /**
 133      * Get the metadata for this service provider.
 134      * @throws Error
 135      */
 136     public function metadata(): string
 137     {
 138         $toolKit = $this->getToolkit();
 139         $settings = $toolKit->getSettings();
 140         $metadata = $settings->getSPMetadata();
 141         $errors = $settings->validateMetadata($metadata);
 142
 143         if (!empty($errors)) {
 144             throw new Error(
 145                 'Invalid SP metadata: '.implode(', ', $errors),
 146                 Error::METADATA_SP_INVALID
 147             );
 148         }
 149
 150         return $metadata;
 151     }
 152
 153     /**
 154      * Load the underlying Onelogin SAML2 toolkit.
 155      * @throws Error
 156      * @throws Exception
 157      */
 158     protected function getToolkit(): Auth
 159     {
 160         $settings = $this->config['onelogin'];
 161         $overrides = $this->config['onelogin_overrides'] ?? [];
 162
 163         if ($overrides && is_string($overrides)) {
 164             $overrides = json_decode($overrides, true);
 165         }
 166
 167         $metaDataSettings = [];
 168         if ($this->config['autoload_from_metadata']) {
 169             $metaDataSettings = IdPMetadataParser::parseRemoteXML($settings['idp']['entityId']);
 170         }
 171
 172         $spSettings = $this->loadOneloginServiceProviderDetails();
 173         $settings = array_replace_recursive($settings, $spSettings, $metaDataSettings, $overrides);
 174         return new Auth($settings);
 175     }
 176
 177     /**
 178      * Load dynamic service provider options required by the onelogin toolkit.
 179      */
 180     protected function loadOneloginServiceProviderDetails(): array
 181     {
 182         $spDetails = [
 183             'entityId' => url('/saml2/metadata'),
 184             'assertionConsumerService' => [
 185                 'url' => url('/saml2/acs'),
 186             ],
 187             'singleLogoutService' => [
 188                 'url' => url('/saml2/sls')
 189             ],
 190         ];
 191
 192         return [
 193             'baseurl' => url('/saml2'),
 194             'sp' => $spDetails
 195         ];
 196     }
 197
 198     /**
 199      * Check if groups should be synced.
 200      */
 201     protected function shouldSyncGroups(): bool
 202     {
 203         return $this->config['user_to_groups'] !== false;
 204     }
 205
 206     /**
 207      * Calculate the display name
 208      */
 209     protected function getUserDisplayName(array $samlAttributes, string $defaultValue): string
 210     {
 211         $displayNameAttr = $this->config['display_name_attributes'];
 212
 213         $displayName = [];
 214         foreach ($displayNameAttr as $dnAttr) {
 215             $dnComponent = $this->getSamlResponseAttribute($samlAttributes, $dnAttr, null);
 216             if ($dnComponent !== null) {
 217                 $displayName[] = $dnComponent;
 218             }
 219         }
 220
 221         if (count($displayName) == 0) {
 222             $displayName = $defaultValue;
 223         } else {
 224             $displayName = implode(' ', $displayName);
 225         }
 226
 227         return $displayName;
 228     }
 229
 230     /**
 231      * Get the value to use as the external id saved in BookStack
 232      * used to link the user to an existing BookStack DB user.
 233      */
 234     protected function getExternalId(array $samlAttributes, string $defaultValue)
 235     {
 236         $userNameAttr = $this->config['external_id_attribute'];
 237         if ($userNameAttr === null) {
 238             return $defaultValue;
 239         }
 240
 241         return $this->getSamlResponseAttribute($samlAttributes, $userNameAttr, $defaultValue);
 242     }
 243
 244     /**
 245      * Extract the details of a user from a SAML response.
 246      */
 247     protected function getUserDetails(string $samlID, $samlAttributes): array
 248     {
 249         $emailAttr = $this->config['email_attribute'];
 250         $externalId = $this->getExternalId($samlAttributes, $samlID);
 251
 252         $defaultEmail = filter_var($samlID, FILTER_VALIDATE_EMAIL) ? $samlID : null;
 253         $email = $this->getSamlResponseAttribute($samlAttributes, $emailAttr, $defaultEmail);
 254
 255         return [
 256             'external_id' => $externalId,
 257             'name' => $this->getUserDisplayName($samlAttributes, $externalId),
 258             'email' => $email,
 259             'saml_id' => $samlID,
 260         ];
 261     }
 262
 263     /**
 264      * Get the groups a user is a part of from the SAML response.
 265      */
 266     public function getUserGroups(array $samlAttributes): array
 267     {
 268         $groupsAttr = $this->config['group_attribute'];
 269         $userGroups = $samlAttributes[$groupsAttr] ?? null;
 270
 271         if (!is_array($userGroups)) {
 272             $userGroups = [];
 273         }
 274
 275         return $userGroups;
 276     }
 277
 278     /**
 279      *  For an array of strings, return a default for an empty array,
 280      *  a string for an array with one element and the full array for
 281      *  more than one element.
 282      */
 283     protected function simplifyValue(array $data, $defaultValue)
 284     {
 285         switch (count($data)) {
 286             case 0:
 287                 $data = $defaultValue;
 288                 break;
 289             case 1:
 290                 $data = $data[0];
 291                 break;
 292         }
 293         return $data;
 294     }
 295
 296     /**
 297      * Get a property from an SAML response.
 298      * Handles properties potentially being an array.
 299      */
 300     protected function getSamlResponseAttribute(array $samlAttributes, string $propertyKey, $defaultValue)
 301     {
 302         if (isset($samlAttributes[$propertyKey])) {
 303             return $this->simplifyValue($samlAttributes[$propertyKey], $defaultValue);
 304         }
 305
 306         return $defaultValue;
 307     }
 308
 309     /**
 310      * Process the SAML response for a user. Login the user when
 311      * they exist, optionally registering them automatically.
 312      * @throws SamlException
 313      * @throws JsonDebugException
 314      * @throws UserRegistrationException
 315      */
 316     public function processLoginCallback(string $samlID, array $samlAttributes): User
 317     {
 318         $userDetails = $this->getUserDetails($samlID, $samlAttributes);
 319         $isLoggedIn = auth()->check();
 320
 321         if ($this->config['dump_user_details']) {
 322             throw new JsonDebugException([
 323                 'id_from_idp' => $samlID,
 324                 'attrs_from_idp' => $samlAttributes,
 325                 'attrs_after_parsing' => $userDetails,
 326             ]);
 327         }
 328
 329         if ($userDetails['email'] === null) {
 330             throw new SamlException(trans('errors.saml_no_email_address'));
 331         }
 332
 333         if ($isLoggedIn) {
 334             throw new SamlException(trans('errors.saml_already_logged_in'), '/login');
 335         }
 336
 337         $user = $this->getOrRegisterUser($userDetails);
 338         if ($user === null) {
 339             throw new SamlException(trans('errors.saml_user_not_registered', ['name' => $userDetails['external_id']]), '/login');
 340         }
 341
 342         if ($this->shouldSyncGroups()) {
 343             $groups = $this->getUserGroups($samlAttributes);
 344             $this->syncWithGroups($user, $groups);
 345         }
 346
 347         auth()->login($user);
 348         return $user;
 349     }
 350 }