Merge pull request #1787 from BookStackApp/saml2_auth

SAML2 Authentication

.env.example.complete

@@ -201,6 +201,28 @@ LDAP_USER_TO_GROUPS=false
 LDAP_GROUP_ATTRIBUTE="memberOf"
 LDAP_REMOVE_FROM_GROUPS=false
 
+# SAML authentication configuration
+# Refer to https://www.bookstackapp.com/docs/admin/saml2-auth/
+SAML2_NAME=SSO
+SAML2_ENABLED=false
+SAML2_AUTO_REGISTER=true
+SAML2_EMAIL_ATTRIBUTE=email
+SAML2_DISPLAY_NAME_ATTRIBUTES=username
+SAML2_EXTERNAL_ID_ATTRIBUTE=null
+SAML2_IDP_ENTITYID=null
+SAML2_IDP_SSO=null
+SAML2_IDP_SLO=null
+SAML2_IDP_x509=null
+SAML2_ONELOGIN_OVERRIDES=null
+SAML2_DUMP_USER_DETAILS=false
+SAML2_AUTOLOAD_METADATA=false
+
+# SAML group sync configuration
+# Refer to https://www.bookstackapp.com/docs/admin/saml2-auth/
+SAML2_USER_TO_GROUPS=false
+SAML2_GROUP_ATTRIBUTE=group
+SAML2_REMOVE_FROM_GROUPS=false
+
 # Disable default third-party services such as Gravatar and Draw.IO
 # Service-specific options will override this option
 DISABLE_EXTERNAL_SERVICES=false

app/Auth/Access/ExternalAuthService.php

@@ -0,0 +1,83 @@
+<?php namespace BookStack\Auth\Access;
+
+use BookStack\Auth\Role;
+use BookStack\Auth\User;
+use Illuminate\Database\Eloquent\Builder;
+
+class ExternalAuthService
+{
+    /**
+     * Check a role against an array of group names to see if it matches.
+     * Checked against role 'external_auth_id' if set otherwise the name of the role.
+     */
+    protected function roleMatchesGroupNames(Role $role, array $groupNames): bool
+    {
+        if ($role->external_auth_id) {
+            return $this->externalIdMatchesGroupNames($role->external_auth_id, $groupNames);
+        }
+
+        $roleName = str_replace(' ', '-', trim(strtolower($role->display_name)));
+        return in_array($roleName, $groupNames);
+    }
+
+    /**
+     * Check if the given external auth ID string matches one of the given group names.
+     */
+    protected function externalIdMatchesGroupNames(string $externalId, array $groupNames): bool
+    {
+        $externalAuthIds = explode(',', strtolower($externalId));
+
+        foreach ($externalAuthIds as $externalAuthId) {
+            if (in_array(trim($externalAuthId), $groupNames)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Match an array of group names to BookStack system roles.
+     * Formats group names to be lower-case and hyphenated.
+     * @param array $groupNames
+     * @return \Illuminate\Support\Collection
+     */
+    protected function matchGroupsToSystemsRoles(array $groupNames)
+    {
+        foreach ($groupNames as $i => $groupName) {
+            $groupNames[$i] = str_replace(' ', '-', trim(strtolower($groupName)));
+        }
+
+        $roles = Role::query()->where(function (Builder $query) use ($groupNames) {
+            $query->whereIn('name', $groupNames);
+            foreach ($groupNames as $groupName) {
+                $query->orWhere('external_auth_id', 'LIKE', '%' . $groupName . '%');
+            }
+        })->get();
+
+        $matchedRoles = $roles->filter(function (Role $role) use ($groupNames) {
+            return $this->roleMatchesGroupNames($role, $groupNames);
+        });
+
+        return $matchedRoles->pluck('id');
+    }
+
+    /**
+     * Sync the groups to the user roles for the current user
+     * @param \BookStack\Auth\User $user
+     * @param array $userGroups
+     */
+    public function syncWithGroups(User $user, array $userGroups)
+    {
+        // Get the ids for the roles from the names
+        $groupsAsRoles = $this->matchGroupsToSystemsRoles($userGroups);
+
+        // Sync groups
+        if ($this->config['remove_from_groups']) {
+            $user->roles()->sync($groupsAsRoles);
+            $this->userRepo->attachDefaultRole($user);
+        } else {
+            $user->roles()->syncWithoutDetaching($groupsAsRoles);
+        }
+    }
+}

app/Auth/Access/LdapService.php

@@ -1,19 +1,17 @@
 <?php namespace BookStack\Auth\Access;
 
 use BookStack\Auth\Access;
-use BookStack\Auth\Role;
 use BookStack\Auth\User;
 use BookStack\Auth\UserRepo;
 use BookStack\Exceptions\LdapException;
 use Illuminate\Contracts\Auth\Authenticatable;
-use Illuminate\Database\Eloquent\Builder;
 
 /**
  * Class LdapService
  * Handles any app-specific LDAP tasks.
  * @package BookStack\Services
  */
-class LdapService
+class LdapService extends Access\ExternalAuthService
 {
 
     protected $ldap;
@@ -351,65 +349,6 @@ class LdapService
     public function syncGroups(User $user, string $username)
     {
         $userLdapGroups = $this->getUserGroups($username);
-
+        $this->syncWithGroups($user, $userLdapGroups);
-        // Get the ids for the roles from the names
-        $ldapGroupsAsRoles = $this->matchLdapGroupsToSystemsRoles($userLdapGroups);
-
-        // Sync groups
-        if ($this->config['remove_from_groups']) {
-            $user->roles()->sync($ldapGroupsAsRoles);
-            $this->userRepo->attachDefaultRole($user);
-        } else {
-            $user->roles()->syncWithoutDetaching($ldapGroupsAsRoles);
-        }
-    }
-
-    /**
-     * Match an array of group names from LDAP to BookStack system roles.
-     * Formats LDAP group names to be lower-case and hyphenated.
-     * @param array $groupNames
-     * @return \Illuminate\Support\Collection
-     */
-    protected function matchLdapGroupsToSystemsRoles(array $groupNames)
-    {
-        foreach ($groupNames as $i => $groupName) {
-            $groupNames[$i] = str_replace(' ', '-', trim(strtolower($groupName)));
-        }
-
-        $roles = Role::query()->where(function (Builder $query) use ($groupNames) {
-            $query->whereIn('name', $groupNames);
-            foreach ($groupNames as $groupName) {
-                $query->orWhere('external_auth_id', 'LIKE', '%' . $groupName . '%');
-            }
-        })->get();
-
-        $matchedRoles = $roles->filter(function (Role $role) use ($groupNames) {
-            return $this->roleMatchesGroupNames($role, $groupNames);
-        });
-
-        return $matchedRoles->pluck('id');
-    }
-
-    /**
-     * Check a role against an array of group names to see if it matches.
-     * Checked against role 'external_auth_id' if set otherwise the name of the role.
-     * @param \BookStack\Auth\Role $role
-     * @param array $groupNames
-     * @return bool
-     */
-    protected function roleMatchesGroupNames(Role $role, array $groupNames)
-    {
-        if ($role->external_auth_id) {
-            $externalAuthIds = explode(',', strtolower($role->external_auth_id));
-            foreach ($externalAuthIds as $externalAuthId) {
-                if (in_array(trim($externalAuthId), $groupNames)) {
-                    return true;
-                }
-            }
-            return false;
-        }
-
-        $roleName = str_replace(' ', '-', trim(strtolower($role->display_name)));
-        return in_array($roleName, $groupNames);
     }
 }

app/Auth/Access/Saml2Service.php

@@ -0,0 +1,395 @@
+<?php namespace BookStack\Auth\Access;
+
+use BookStack\Auth\User;
+use BookStack\Auth\UserRepo;
+use BookStack\Exceptions\JsonDebugException;
+use BookStack\Exceptions\SamlException;
+use Exception;
+use Illuminate\Support\Str;
+use OneLogin\Saml2\Auth;
+use OneLogin\Saml2\Error;
+use OneLogin\Saml2\IdPMetadataParser;
+use OneLogin\Saml2\ValidationError;
+
+/**
+ * Class Saml2Service
+ * Handles any app-specific SAML tasks.
+ */
+class Saml2Service extends ExternalAuthService
+{
+    protected $config;
+    protected $userRepo;
+    protected $user;
+    protected $enabled;
+
+    /**
+     * Saml2Service constructor.
+     */
+    public function __construct(UserRepo $userRepo, User $user)
+    {
+        $this->config = config('saml2');
+        $this->userRepo = $userRepo;
+        $this->user = $user;
+        $this->enabled = config('saml2.enabled') === true;
+    }
+
+    /**
+     * Initiate a login flow.
+     * @throws Error
+     */
+    public function login(): array
+    {
+        $toolKit = $this->getToolkit();
+        $returnRoute = url('/saml2/acs');
+        return [
+            'url' => $toolKit->login($returnRoute, [], false, false, true),
+            'id' => $toolKit->getLastRequestID(),
+        ];
+    }
+
+    /**
+     * Initiate a logout flow.
+     * @throws Error
+     */
+    public function logout(): array
+    {
+        $toolKit = $this->getToolkit();
+        $returnRoute = url('/');
+
+        try {
+            $url = $toolKit->logout($returnRoute, [], null, null, true);
+            $id = $toolKit->getLastRequestID();
+        } catch (Error $error) {
+            if ($error->getCode() !== Error::SAML_SINGLE_LOGOUT_NOT_SUPPORTED) {
+                throw $error;
+            }
+
+            $this->actionLogout();
+            $url = '/';
+            $id = null;
+        }
+
+        return ['url' => $url, 'id' => $id];
+    }
+
+    /**
+     * Process the ACS response from the idp and return the
+     * matching, or new if registration active, user matched to the idp.
+     * Returns null if not authenticated.
+     * @throws Error
+     * @throws SamlException
+     * @throws ValidationError
+     * @throws JsonDebugException
+     */
+    public function processAcsResponse(?string $requestId): ?User
+    {
+        $toolkit = $this->getToolkit();
+        $toolkit->processResponse($requestId);
+        $errors = $toolkit->getErrors();
+
+        if (!empty($errors)) {
+            throw new Error(
+                'Invalid ACS Response: '.implode(', ', $errors)
+            );
+        }
+
+        if (!$toolkit->isAuthenticated()) {
+            return null;
+        }
+
+        $attrs = $toolkit->getAttributes();
+        $id = $toolkit->getNameId();
+
+        return $this->processLoginCallback($id, $attrs);
+    }
+
+    /**
+     * Process a response for the single logout service.
+     * @throws Error
+     */
+    public function processSlsResponse(?string $requestId): ?string
+    {
+        $toolkit = $this->getToolkit();
+        $redirect = $toolkit->processSLO(true, $requestId, false, null, true);
+
+        $errors = $toolkit->getErrors();
+
+        if (!empty($errors)) {
+            throw new Error(
+                'Invalid SLS Response: '.implode(', ', $errors)
+            );
+        }
+
+        $this->actionLogout();
+        return $redirect;
+    }
+
+    /**
+     * Do the required actions to log a user out.
+     */
+    protected function actionLogout()
+    {
+        auth()->logout();
+        session()->invalidate();
+    }
+
+    /**
+     * Get the metadata for this service provider.
+     * @throws Error
+     */
+    public function metadata(): string
+    {
+        $toolKit = $this->getToolkit();
+        $settings = $toolKit->getSettings();
+        $metadata = $settings->getSPMetadata();
+        $errors = $settings->validateMetadata($metadata);
+
+        if (!empty($errors)) {
+            throw new Error(
+                'Invalid SP metadata: '.implode(', ', $errors),
+                Error::METADATA_SP_INVALID
+            );
+        }
+
+        return $metadata;
+    }
+
+    /**
+     * Load the underlying Onelogin SAML2 toolkit.
+     * @throws Error
+     * @throws Exception
+     */
+    protected function getToolkit(): Auth
+    {
+        $settings = $this->config['onelogin'];
+        $overrides = $this->config['onelogin_overrides'] ?? [];
+
+        if ($overrides && is_string($overrides)) {
+            $overrides = json_decode($overrides, true);
+        }
+
+        $metaDataSettings = [];
+        if ($this->config['autoload_from_metadata']) {
+            $metaDataSettings = IdPMetadataParser::parseRemoteXML($settings['idp']['entityId']);
+        }
+
+        $spSettings = $this->loadOneloginServiceProviderDetails();
+        $settings = array_replace_recursive($settings, $spSettings, $metaDataSettings, $overrides);
+        return new Auth($settings);
+    }
+
+    /**
+     * Load dynamic service provider options required by the onelogin toolkit.
+     */
+    protected function loadOneloginServiceProviderDetails(): array
+    {
+        $spDetails = [
+            'entityId' => url('/saml2/metadata'),
+            'assertionConsumerService' => [
+                'url' => url('/saml2/acs'),
+            ],
+            'singleLogoutService' => [
+                'url' => url('/saml2/sls')
+            ],
+        ];
+
+        return [
+            'baseurl' => url('/saml2'),
+            'sp' => $spDetails
+        ];
+    }
+
+    /**
+     * Check if groups should be synced.
+     */
+    protected function shouldSyncGroups(): bool
+    {
+        return $this->enabled && $this->config['user_to_groups'] !== false;
+    }
+
+    /**
+     * Calculate the display name
+     */
+    protected function getUserDisplayName(array $samlAttributes, string $defaultValue): string
+    {
+        $displayNameAttr = $this->config['display_name_attributes'];
+
+        $displayName = [];
+        foreach ($displayNameAttr as $dnAttr) {
+            $dnComponent = $this->getSamlResponseAttribute($samlAttributes, $dnAttr, null);
+            if ($dnComponent !== null) {
+                $displayName[] = $dnComponent;
+            }
+        }
+
+        if (count($displayName) == 0) {
+            $displayName = $defaultValue;
+        } else {
+            $displayName = implode(' ', $displayName);
+        }
+
+        return $displayName;
+    }
+
+    /**
+     * Get the value to use as the external id saved in BookStack
+     * used to link the user to an existing BookStack DB user.
+     */
+    protected function getExternalId(array $samlAttributes, string $defaultValue)
+    {
+        $userNameAttr = $this->config['external_id_attribute'];
+        if ($userNameAttr === null) {
+            return $defaultValue;
+        }
+
+        return $this->getSamlResponseAttribute($samlAttributes, $userNameAttr, $defaultValue);
+    }
+
+    /**
+     * Extract the details of a user from a SAML response.
+     */
+    public function getUserDetails(string $samlID, $samlAttributes): array
+    {
+        $emailAttr = $this->config['email_attribute'];
+        $externalId = $this->getExternalId($samlAttributes, $samlID);
+
+        $defaultEmail = filter_var($samlID, FILTER_VALIDATE_EMAIL) ? $samlID : null;
+        $email = $this->getSamlResponseAttribute($samlAttributes, $emailAttr, $defaultEmail);
+
+        return [
+            'external_id' => $externalId,
+            'name' => $this->getUserDisplayName($samlAttributes, $externalId),
+            'email' => $email,
+            'saml_id' => $samlID,
+        ];
+    }
+
+    /**
+     * Get the groups a user is a part of from the SAML response.
+     */
+    public function getUserGroups(array $samlAttributes): array
+    {
+        $groupsAttr = $this->config['group_attribute'];
+        $userGroups = $samlAttributes[$groupsAttr] ?? null;
+
+        if (!is_array($userGroups)) {
+            $userGroups = [];
+        }
+
+        return $userGroups;
+    }
+
+    /**
+     *  For an array of strings, return a default for an empty array,
+     *  a string for an array with one element and the full array for
+     *  more than one element.
+     */
+    protected function simplifyValue(array $data, $defaultValue)
+    {
+        switch (count($data)) {
+            case 0:
+                $data = $defaultValue;
+                break;
+            case 1:
+                $data = $data[0];
+                break;
+        }
+        return $data;
+    }
+
+    /**
+     * Get a property from an SAML response.
+     * Handles properties potentially being an array.
+     */
+    protected function getSamlResponseAttribute(array $samlAttributes, string $propertyKey, $defaultValue)
+    {
+        if (isset($samlAttributes[$propertyKey])) {
+            return $this->simplifyValue($samlAttributes[$propertyKey], $defaultValue);
+        }
+
+        return $defaultValue;
+    }
+
+    /**
+     *  Register a user that is authenticated but not already registered.
+     */
+    protected function registerUser(array $userDetails): User
+    {
+        // Create an array of the user data to create a new user instance
+        $userData = [
+            'name' => $userDetails['name'],
+            'email' => $userDetails['email'],
+            'password' => Str::random(32),
+            'external_auth_id' => $userDetails['external_id'],
+            'email_confirmed' => true,
+        ];
+
+        $existingUser = $this->user->newQuery()->where('email', '=', $userDetails['email'])->first();
+        if ($existingUser) {
+            throw new SamlException(trans('errors.saml_email_exists', ['email' => $userDetails['email']]));
+        }
+
+        $user = $this->user->forceCreate($userData);
+        $this->userRepo->attachDefaultRole($user);
+        $this->userRepo->downloadAndAssignUserAvatar($user);
+        return $user;
+    }
+
+    /**
+     * Get the user from the database for the specified details.
+     */
+    protected function getOrRegisterUser(array $userDetails): ?User
+    {
+        $isRegisterEnabled = $this->config['auto_register'] === true;
+        $user = $this->user
+          ->where('external_auth_id', $userDetails['external_id'])
+          ->first();
+
+        if ($user === null && $isRegisterEnabled) {
+            $user = $this->registerUser($userDetails);
+        }
+
+        return $user;
+    }
+
+    /**
+     * Process the SAML response for a user. Login the user when
+     * they exist, optionally registering them automatically.
+     * @throws SamlException
+     * @throws JsonDebugException
+     */
+    public function processLoginCallback(string $samlID, array $samlAttributes): User
+    {
+        $userDetails = $this->getUserDetails($samlID, $samlAttributes);
+        $isLoggedIn = auth()->check();
+
+        if ($this->config['dump_user_details']) {
+            throw new JsonDebugException([
+                'id_from_idp' => $samlID,
+                'attrs_from_idp' => $samlAttributes,
+                'attrs_after_parsing' => $userDetails,
+            ]);
+        }
+
+        if ($userDetails['email'] === null) {
+            throw new SamlException(trans('errors.saml_no_email_address'));
+        }
+
+        if ($isLoggedIn) {
+            throw new SamlException(trans('errors.saml_already_logged_in'), '/login');
+        }
+
+        $user = $this->getOrRegisterUser($userDetails);
+        if ($user === null) {
+            throw new SamlException(trans('errors.saml_user_not_registered', ['name' => $userDetails['external_id']]), '/login');
+        }
+
+        if ($this->shouldSyncGroups()) {
+            $groups = $this->getUserGroups($samlAttributes);
+            $this->syncWithGroups($user, $groups);
+        }
+
+        auth()->login($user);
+        return $user;
+    }
+}

app/Auth/Role.php

@@ -4,6 +4,13 @@ use BookStack\Auth\Permissions\JointPermission;
 use BookStack\Auth\Permissions\RolePermission;
 use BookStack\Model;
 
+/**
+ * Class Role
+ * @property string $display_name
+ * @property string $description
+ * @property string $external_auth_id
+ * @package BookStack\Auth
+ */
 class Role extends Model
 {
 

app/Config/saml2.php

@@ -0,0 +1,148 @@
+<?php
+
+return [
+
+    // Display name, shown to users, for SAML2 option
+    'name' => env('SAML2_NAME', 'SSO'),
+    // Toggle whether the SAML2 option is active
+    'enabled' => env('SAML2_ENABLED', false),
+    // Enable registration via SAML2 authentication
+    'auto_register' => env('SAML2_AUTO_REGISTER', true),
+
+    // Dump user details after a login request for debugging purposes
+    'dump_user_details' => env('SAML2_DUMP_USER_DETAILS', false),
+
+    // Attribute, within a SAML response, to find the user's email address
+    'email_attribute' => env('SAML2_EMAIL_ATTRIBUTE', 'email'),
+    // Attribute, within a SAML response, to find the user's display name
+    'display_name_attributes' => explode('|', env('SAML2_DISPLAY_NAME_ATTRIBUTES', 'username')),
+    // Attribute, within a SAML response, to use to connect a BookStack user to the SAML user.
+    'external_id_attribute' => env('SAML2_EXTERNAL_ID_ATTRIBUTE', null),
+
+    // Group sync options
+    // Enable syncing, upon login, of SAML2 groups to BookStack groups
+    'user_to_groups' => env('SAML2_USER_TO_GROUPS', false),
+    // Attribute, within a SAML response, to find group names on
+    'group_attribute' => env('SAML2_GROUP_ATTRIBUTE', 'group'),
+    // When syncing groups, remove any groups that no longer match. Otherwise sync only adds new groups.
+    'remove_from_groups' => env('SAML2_REMOVE_FROM_GROUPS', false),
+
+    // Autoload IDP details from the metadata endpoint
+    'autoload_from_metadata' => env('SAML2_AUTOLOAD_METADATA', false),
+
+    // Overrides, in JSON format, to the configuration passed to underlying onelogin library.
+    'onelogin_overrides' => env('SAML2_ONELOGIN_OVERRIDES', null),
+
+
+    'onelogin' => [
+        // If 'strict' is True, then the PHP Toolkit will reject unsigned
+        // or unencrypted messages if it expects them signed or encrypted
+        // Also will reject the messages if not strictly follow the SAML
+        // standard: Destination, NameId, Conditions ... are validated too.
+        'strict' => true,
+
+        // Enable debug mode (to print errors)
+        'debug' => env('APP_DEBUG', false),
+
+        // Set a BaseURL to be used instead of try to guess
+        // the BaseURL of the view that process the SAML Message.
+        // Ex. http://sp.example.com/
+        //     http://example.com/sp/
+        'baseurl' => null,
+
+        // Service Provider Data that we are deploying
+        'sp' => [
+            // Identifier of the SP entity  (must be a URI)
+            'entityId' => '',
+
+            // Specifies info about where and how the <AuthnResponse> message MUST be
+            // returned to the requester, in this case our SP.
+            'assertionConsumerService' => [
+                // URL Location where the <Response> from the IdP will be returned
+                'url' => '',
+                // SAML protocol binding to be used when returning the <Response>
+                // message.  Onelogin Toolkit supports for this endpoint the
+                // HTTP-POST binding only
+                'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST',
+            ],
+
+            // Specifies info about where and how the <Logout Response> message MUST be
+            // returned to the requester, in this case our SP.
+            'singleLogoutService' => [
+                // URL Location where the <Response> from the IdP will be returned
+                'url' => '',
+                // SAML protocol binding to be used when returning the <Response>
+                // message.  Onelogin Toolkit supports for this endpoint the
+                // HTTP-Redirect binding only
+                'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
+            ],
+
+            // Specifies constraints on the name identifier to be used to
+            // represent the requested subject.
+            // Take a look on lib/Saml2/Constants.php to see the NameIdFormat supported
+            'NameIDFormat' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
+            // Usually x509cert and privateKey of the SP are provided by files placed at
+            // the certs folder. But we can also provide them with the following parameters
+            'x509cert' => '',
+            'privateKey' => '',
+        ],
+        // Identity Provider Data that we want connect with our SP
+        'idp' => [
+            // Identifier of the IdP entity  (must be a URI)
+            'entityId' => env('SAML2_IDP_ENTITYID', null),
+            // SSO endpoint info of the IdP. (Authentication Request protocol)
+            'singleSignOnService' => [
+                // URL Target of the IdP where the SP will send the Authentication Request Message
+                'url' => env('SAML2_IDP_SSO', null),
+                // SAML protocol binding to be used when returning the <Response>
+                // message.  Onelogin Toolkit supports for this endpoint the
+                // HTTP-Redirect binding only
+                'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
+            ],
+            // SLO endpoint info of the IdP.
+            'singleLogoutService' => [
+                // URL Location of the IdP where the SP will send the SLO Request
+                'url' => env('SAML2_IDP_SLO', null),
+                // URL location of the IdP where the SP will send the SLO Response (ResponseLocation)
+                // if not set, url for the SLO Request will be used
+                'responseUrl' => '',
+                // SAML protocol binding to be used when returning the <Response>
+                // message.  Onelogin Toolkit supports for this endpoint the
+                // HTTP-Redirect binding only
+                'binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect',
+            ],
+            // Public x509 certificate of the IdP
+            'x509cert' => env('SAML2_IDP_x509', null),
+            /*
+             *  Instead of use the whole x509cert you can use a fingerprint in
+             *  order to validate the SAMLResponse, but we don't recommend to use
+             *  that method on production since is exploitable by a collision
+             *  attack.
+             *  (openssl x509 -noout -fingerprint -in "idp.crt" to generate it,
+             *   or add for example the -sha256 , -sha384 or -sha512 parameter)
+             *
+             *  If a fingerprint is provided, then the certFingerprintAlgorithm is required in order to
+             *  let the toolkit know which Algorithm was used. Possible values: sha1, sha256, sha384 or sha512
+             *  'sha1' is the default value.
+             */
+            // 'certFingerprint' => '',
+            // 'certFingerprintAlgorithm' => 'sha1',
+            /* In some scenarios the IdP uses different certificates for
+             * signing/encryption, or is under key rollover phase and more
+             * than one certificate is published on IdP metadata.
+             * In order to handle that the toolkit offers that parameter.
+             * (when used, 'x509cert' and 'certFingerprint' values are
+             * ignored).
+             */
+            // 'x509certMulti' => array(
+            //      'signing' => array(
+            //          0 => '<cert1-string>',
+            //      ),
+            //      'encryption' => array(
+            //          0 => '<cert2-string>',
+            //      )
+            // ),
+        ],
+    ],
+
+];

app/Config/services.php

@@ -130,6 +130,6 @@ return [
         'group_attribute' => env('LDAP_GROUP_ATTRIBUTE', 'memberOf'),
         'remove_from_groups' => env('LDAP_REMOVE_FROM_GROUPS', false),
         'tls_insecure' => env('LDAP_TLS_INSECURE', false),
-    ]
+    ],
 
 ];

app/Exceptions/JsonDebugException.php

@@ -0,0 +1,25 @@
+<?php namespace BookStack\Exceptions;
+
+use Exception;
+
+class JsonDebugException extends Exception
+{
+
+    protected $data;
+
+    /**
+     * JsonDebugException constructor.
+     */
+    public function __construct($data)
+    {
+        $this->data = $data;
+    }
+
+    /**
+     * Covert this exception into a response.
+     */
+    public function render()
+    {
+        return response()->json($this->data);
+    }
+}

app/Exceptions/SamlException.php

@@ -0,0 +1,6 @@
+<?php namespace BookStack\Exceptions;
+
+class SamlException extends NotifyException
+{
+
+}

app/Http/Controllers/Auth/LoginController.php

@@ -119,6 +119,7 @@ class LoginController extends Controller
     {
         $socialDrivers = $this->socialAuthService->getActiveDrivers();
         $authMethod = config('auth.method');
+        $samlEnabled = config('saml2.enabled') === true;
 
         if ($request->has('email')) {
             session()->flashInput([
@@ -127,7 +128,11 @@ class LoginController extends Controller
             ]);
         }
 
-        return view('auth.login', ['socialDrivers' => $socialDrivers, 'authMethod' => $authMethod]);
+        return view('auth.login', [
+          'socialDrivers' => $socialDrivers,
+          'authMethod' => $authMethod,
+          'samlEnabled' => $samlEnabled,
+        ]);
     }
 
     /**
@@ -141,4 +146,23 @@ class LoginController extends Controller
         session()->put('social-callback', 'login');
         return $this->socialAuthService->startLogIn($socialDriver);
     }
+
+    /**
+     * Log the user out of the application.
+     *
+     * @param  \Illuminate\Http\Request  $request
+     * @return \Illuminate\Http\Response
+     */
+    public function logout(Request $request)
+    {
+        if (config('saml2.enabled') && session()->get('last_login_type') === 'saml2') {
+            return redirect('/saml2/logout');
+        }
+
+        $this->guard()->logout();
+
+        $request->session()->invalidate();
+
+        return $this->loggedOut($request) ?: redirect('/');
+    }
 }

app/Http/Controllers/Auth/RegisterController.php

@@ -103,7 +103,11 @@ class RegisterController extends Controller
     {
         $this->checkRegistrationAllowed();
         $socialDrivers = $this->socialAuthService->getActiveDrivers();
-        return view('auth.register', ['socialDrivers' => $socialDrivers]);
+        $samlEnabled = (config('saml2.enabled') === true) && (config('saml2.auto_register') === true);
+        return view('auth.register', [
+            'socialDrivers' => $socialDrivers,
+            'samlEnabled' => $samlEnabled,
+        ]);
     }
 
     /**

app/Http/Controllers/Auth/Saml2Controller.php

@@ -0,0 +1,96 @@
+<?php
+
+namespace BookStack\Http\Controllers\Auth;
+
+use BookStack\Auth\Access\Saml2Service;
+use BookStack\Http\Controllers\Controller;
+
+class Saml2Controller extends Controller
+{
+
+    protected $samlService;
+
+    /**
+     * Saml2Controller constructor.
+     */
+    public function __construct(Saml2Service $samlService)
+    {
+        parent::__construct();
+        $this->samlService = $samlService;
+
+        // SAML2 access middleware
+        $this->middleware(function ($request, $next) {
+            if (!config('saml2.enabled')) {
+                $this->showPermissionError();
+            }
+
+            return $next($request);
+        });
+    }
+
+    /**
+     * Start the login flow via SAML2.
+     */
+    public function login()
+    {
+        $loginDetails = $this->samlService->login();
+        session()->flash('saml2_request_id', $loginDetails['id']);
+
+        return redirect($loginDetails['url']);
+    }
+
+    /**
+     * Start the logout flow via SAML2.
+     */
+    public function logout()
+    {
+        $logoutDetails = $this->samlService->logout();
+
+        if ($logoutDetails['id']) {
+            session()->flash('saml2_logout_request_id', $logoutDetails['id']);
+        }
+
+        return redirect($logoutDetails['url']);
+    }
+
+    /*
+     * Get the metadata for this SAML2 service provider.
+     */
+    public function metadata()
+    {
+        $metaData = $this->samlService->metadata();
+        return response()->make($metaData, 200, [
+            'Content-Type' => 'text/xml'
+        ]);
+    }
+
+    /**
+     * Single logout service.
+     * Handle logout requests and responses.
+     */
+    public function sls()
+    {
+        $requestId = session()->pull('saml2_logout_request_id', null);
+        $redirect = $this->samlService->processSlsResponse($requestId) ?? '/';
+        return redirect($redirect);
+    }
+
+    /**
+     * Assertion Consumer Service.
+     * Processes the SAML response from the IDP.
+     */
+    public function acs()
+    {
+        $requestId = session()->pull('saml2_request_id', null);
+
+        $user = $this->samlService->processAcsResponse($requestId);
+        if ($user === null) {
+            $this->showErrorNotification(trans('errors.saml_fail_authed', ['system' => config('saml2.name')]));
+            return redirect('/login');
+        }
+
+        session()->put('last_login_type', 'saml2');
+        return redirect()->intended();
+    }
+
+}

app/Http/Middleware/VerifyCsrfToken.php

@@ -19,6 +19,6 @@ class VerifyCsrfToken extends Middleware
      * @var array
      */
     protected $except = [
-        //
+        'saml2/*'
     ];
 }

composer.json

@@ -22,6 +22,7 @@
         "laravel/framework": "^6.0",
         "laravel/socialite": "^4.2",
         "league/flysystem-aws-s3-v3": "^1.0",
+        "onelogin/php-saml": "^3.3",
         "predis/predis": "^1.1",
         "socialiteproviders/discord": "^2.0",
         "socialiteproviders/gitlab": "^3.0",

phpunit.xml

@@ -48,5 +48,6 @@
         <server name="GOOGLE_SELECT_ACCOUNT" value=""/>
         <server name="APP_URL" value="http://bookstack.dev"/>
         <server name="DEBUGBAR_ENABLED" value="false"/>
+        <server name="SAML2_ENABLED" value="false"/>
     </php>
 </phpunit>

readme.md

@@ -174,4 +174,5 @@ These are the great open-source projects used to help build BookStack:
     * [Laravel IDE helper](https://github.com/barryvdh/laravel-ide-helper)
 * [WKHTMLtoPDF](http://wkhtmltopdf.org/index.html)
 * [Draw.io](https://github.com/jgraph/drawio)
-* [Laravel Stats](https://github.com/stefanzweifel/laravel-stats)
+* [Laravel Stats](https://github.com/stefanzweifel/laravel-stats)
+* [OneLogin's SAML PHP Toolkit](https://github.com/onelogin/php-saml)

resources/icons/saml2.svg

@@ -0,0 +1,4 @@
+<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+    <path d="M0 0h24v24H0z" fill="none"/>
+    <path d="M12.65 10C11.83 7.67 9.61 6 7 6c-3.31 0-6 2.69-6 6s2.69 6 6 6c2.61 0 4.83-1.67 5.65-4H17v4h4v-4h2v-4H12.65zM7 14c-1.1 0-2-.9-2-2s.9-2 2-2 2 .9 2 2-.9 2-2 2z"/>
+</svg>

resources/lang/de/errors.php

@@ -17,6 +17,8 @@ return [
     'ldap_fail_authed' => 'LDAP-Zugriff mit DN und Passwort ist fehlgeschlagen',
     'ldap_extension_not_installed' => 'LDAP-PHP-Erweiterung ist nicht installiert.',
     'ldap_cannot_connect' => 'Die Verbindung zum LDAP-Server ist fehlgeschlagen. Beim initialen Verbindungsaufbau trat ein Fehler auf.',
+    'saml_already_logged_in' => 'Sie sind bereits angemeldet',
+    'saml_user_not_registered' => 'Kein Benutzer mit ID :name registriert und die automatische Registrierung ist deaktiviert',
     'social_no_action_defined' => 'Es ist keine Aktion definiert',
     'social_login_bad_response' => "Fehler bei der :socialAccount-Anmeldung: \n:error",
     'social_account_in_use' => 'Dieses :socialAccount-Konto wird bereits verwendet. Bitte melden Sie sich mit dem :socialAccount-Konto an.',

resources/lang/de_informal/errors.php

@@ -9,16 +9,11 @@ return [
     'permissionJson' => 'Du hast keine Berechtigung, die angeforderte Aktion auszuführen.',
 
     // Auth
+    'saml_already_logged_in' => 'Du bist bereits angemeldet',
     'error_user_exists_different_creds' => 'Ein Benutzer mit der E-Mail-Adresse :email ist bereits mit anderen Anmeldedaten registriert.',
     'email_already_confirmed' => 'Die E-Mail-Adresse ist bereits bestätigt. Bitte melde dich an.',
     'email_confirmation_invalid' => 'Der Bestätigungslink ist nicht gültig oder wurde bereits verwendet. Bitte registriere dich erneut.',
-    'email_confirmation_expired' => 'Der Bestätigungslink ist abgelaufen. Es wurde eine neue Bestätigungs-E-Mail gesendet.',
+
-    'ldap_fail_anonymous' => 'Anonymer LDAP-Zugriff ist fehlgeschlafgen',
-    'ldap_fail_authed' => 'LDAP-Zugriff mit DN und Passwort ist fehlgeschlagen',
-    'ldap_extension_not_installed' => 'LDAP-PHP-Erweiterung ist nicht installiert.',
-    'ldap_cannot_connect' => 'Die Verbindung zum LDAP-Server ist fehlgeschlagen. Beim initialen Verbindungsaufbau trat ein Fehler auf.',
-    'social_no_action_defined' => 'Es ist keine Aktion definiert',
-    'social_login_bad_response' => "Fehler bei der :socialAccount-Anmeldung: \n:error",
     'social_account_in_use' => 'Dieses :socialAccount-Konto wird bereits verwendet. Bitte melde dich mit dem :socialAccount-Konto an.',
     'social_account_email_in_use' => 'Die E-Mail-Adresse ":email" ist bereits registriert. Wenn Du bereits registriert bist, kannst Du Dein :socialAccount-Konto in Deinen Profil-Einstellungen verknüpfen.',
     'social_account_existing' => 'Dieses :socialAccount-Konto ist bereits mit Ihrem Profil verknüpft.',

resources/lang/en/errors.php

@@ -17,6 +17,12 @@ return [
     'ldap_fail_authed' => 'LDAP access failed using given dn & password details',
     'ldap_extension_not_installed' => 'LDAP PHP extension not installed',
     'ldap_cannot_connect' => 'Cannot connect to ldap server, Initial connection failed',
+    'saml_already_logged_in' => 'Already logged in',
+    'saml_user_not_registered' => 'The user :name is not registered and automatic registration is disabled',
+    'saml_no_email_address' => 'Could not find an email address, for this user, in the data provided by the external authentication system',
+    'saml_invalid_response_id' => 'The request from the external authentication system is not recognised by a process started by this application. Navigating back after a login could cause this issue.',
+    'saml_fail_authed' => 'Login using :system failed, system did not provide successful authorization',
+    'saml_email_exists' => 'Registration unsuccessful since a user already exists with email address ":email"',
     'social_no_action_defined' => 'No action defined',
     'social_login_bad_response' => "Error received during :socialAccount login: \n:error",
     'social_account_in_use' => 'This :socialAccount account is already in use, Try logging in via the :socialAccount option.',

resources/views/auth/login.blade.php

@@ -45,6 +45,16 @@
                 @endforeach
             @endif
 
+            @if($samlEnabled)
+                <hr class="my-l">
+                <div>
+                    <a id="saml-login" class="button outline block svg" href="{{ url("/saml2/login") }}">
+                       @icon('saml2')
+                      {{ trans('auth.log_in_with', ['socialDriver' => config('saml2.name')]) }}
+                    </a>
+                </div>
+            @endif
+
             @if(setting('registration-enabled', false))
                 <div class="text-center pb-s">
                     <hr class="my-l">
@@ -54,4 +64,4 @@
         </div>
     </div>
 
-@stop
+@stop

resources/views/auth/register.blade.php

@@ -49,6 +49,16 @@
                     </div>
                 @endforeach
             @endif
+
+            @if($samlEnabled)
+                <hr class="my-l">
+                <div>
+                    <a id="saml-login" class="button outline block svg" href="{{ url("/saml2/login") }}">
+                        @icon('saml2')
+                        {{ trans('auth.log_in_with', ['socialDriver' => config('saml2.name')]) }}
+                    </a>
+                </div>
+            @endif
         </div>
     </div>
 @stop

resources/views/settings/roles/form.blade.php

@@ -19,7 +19,7 @@
                     @include('form.text', ['name' => 'description'])
                 </div>
 
-                @if(config('auth.method') === 'ldap')
+                @if(config('auth.method') === 'ldap' || config('saml2.enabled') === true)
                     <div class="form-group">
                         <label for="name">{{ trans('settings.role_external_auth_id') }}</label>
                         @include('form.text', ['name' => 'external_auth_id'])
@@ -255,4 +255,4 @@
             {{ trans('settings.role_users_none') }}
         </p>
     @endif
-</div>
+</div>

resources/views/users/form.blade.php

@@ -25,7 +25,7 @@
     </div>
 </div>
 
-@if($authMethod === 'ldap' && userCan('users-manage'))
+@if(($authMethod === 'ldap' || config('saml2.enabled') === true) && userCan('users-manage'))
     <div class="grid half gap-xl v-center">
         <div>
             <label class="setting-list-label">{{ trans('settings.users_external_auth_id') }}</label>
@@ -84,4 +84,4 @@
         </div>
 
     </div>
-@endif
+@endif

routes/web.php

@@ -216,6 +216,13 @@ Route::post('/register/confirm/resend', 'Auth\ConfirmEmailController@resend');
 Route::get('/register/confirm/{token}', 'Auth\ConfirmEmailController@confirm');
 Route::post('/register', 'Auth\RegisterController@postRegister');
 
+// SAML routes
+Route::get('/saml2/login', 'Auth\Saml2Controller@login');
+Route::get('/saml2/logout', 'Auth\Saml2Controller@logout');
+Route::get('/saml2/metadata', 'Auth\Saml2Controller@metadata');
+Route::get('/saml2/sls', 'Auth\Saml2Controller@sls');
+Route::post('/saml2/acs', 'Auth\Saml2Controller@acs');
+
 // User invitation routes
 Route::get('/register/invite/{token}', 'Auth\UserInviteController@showSetPassword');
 Route::post('/register/invite/{token}', 'Auth\UserInviteController@setPassword');