categories = ["Releases"]
tags = ["Releases"]
title = "BookStack Release v21.10"
-date = 2021-10-24T14:00:00Z
+date = 2021-10-25T14:20:00Z
author = "Dan Brown"
image = "/images/blog-cover-images/gate-benofthenorth.jpg"
slug = "bookstack-release-v21-10"
draft = false
+++
-October brings us BookStack v21.10. This release is primarily intended to wrap up some
-loose ends before we make some more substantial framework changes, but it does bring with
+October brings us BookStack v21.10. This release is primarily intended to wrap up a few
+loose ends before we make more substantial framework changes, but it does bring with
it a new authentication option in addition to some new API endpoints.
In the below we'll dive into many of the new features and improvements added
-since [v21.08](/blog/bookstack-release-v21-08/).
+[since v21.08](/blog/bookstack-release-v21-08/).
* [Update instructions](https://www.bookstackapp.com/docs/admin/updates)
* [GitHub release page](https://github.com/BookStackApp/BookStack/releases/tag/v21.10)
**Upgrade Notices**
-- **Security Releases** - There were a series of security vulnerabilities found during the life of
+- **Security Releases** - There were some security vulnerabilities found during the life of
v21.08. See the [v21.08.2](/blog/bookstack-release-v21-08-2/) and
[v21.08.5](/blog/bookstack-release-v21-08-5/) posts for more details.
- **Content Security Policy** - v21.08.2 introduced the use of BookStack-applied CSP headers. These
could potentially conflict with any CSP headers set a server-level. The use of these are detailed
in the post below and details of the headers can be found on the [security page here](/docs/admin/security/#csp).
-### OpenID Connection Authentication
+### OpenID Connect Authentication
-Notes
+v21.10 brings with it the option of using OpenID Connect (OIDC) as a primary authentication method
+within BookStack.
+This allows authentication integration with a wide range of providers that support the OIDC standard.
+The implementation includes basic auto-discovery of endpoints & keys for easier configuration.
+During development it has been tested with Okta, KeyCloak and Auth0.
+For this initial implementation we don't yet support group sync but I've opened up a
+[GitHub issue here](https://github.com/BookStackApp/BookStack/issues/3004) to gain feedback on how
+identity providers supply groups. Please contribute feedback on that issue if you desire OIDC group support.
+
+You can find documentation on [using OpenID Connect here](/docs/admin/oidc-auth/).
+
### API Updates
#### Attachment Endpoints
#### Image Upload via Markdown Content
-Since v21.05.1 it has been possible to upload images as part of an API page update or creation, via
-embedding the image as a data-uri within HTML content. This release builds upon this and brings
+Since v21.05.1 it has been possible to upload images as part of an API page update or create operation,
+via embedding the image as a data-uri within HTML content. This release builds upon that to bring
the same functionality to markdown content on the same API endpoints; For example:
```markdown
### TOTP URL During MFA Setup
Since the TOTP MFA system was added to BookStack in the last feature release, it was reported
-that some TOTP-handling services require a URL or secret code instead of a QR code. To support
-this, as of v21.08.1, we now show the TOTP URL below the QR code, which the secret code can be copied out of
+that some TOTP-handling services require a URL, or secret code, instead of a QR code. To support
+this, as of v21.08.1, we now show the TOTP URL below the QR code, which the secret can be copied out from
if needed.
### IP Address in Audit Log
-v21.08.4
-Notes, mention `APP_PROXIES` env option if needed
+Within BookStack v21.08.4 the audit log was updated to now record and show the related user IP address
+for activities. Note, if you're using a reverse proxy in front of BookStack you may need to configure
+the `APP_PROXIES` .env option [as shown here](https://github.com/BookStackApp/BookStack/blob/9c2b8057ab7b744c0824a9a3e48c3ccd36b8c103/.env.example.complete#L45-L51) otherwise the reported IP
+address may be that of the proxying system instead of the user.
+Thanks to [@johnroyer](https://github.com/BookStackApp/BookStack/pull/2936) for the addition of this feature.
+
### Smarter Concurrent Editing Detection & Warnings
-v21.08.5
+Thanks to [@MatthieuParis](https://github.com/BookStackApp/BookStack/pull/2877), BookStack will now run
+additional potential editor conflict detection upon draft saves whereas previously this would only run upon the
+start of an editing session. This should prove especially useful when someone has the editor open for
+a while, since there's now a much greater chance of being alerted if someone else starts editing the
+same page. This enhancement was added as part of v21.08.5.
### New Debug View
-In v21.08.6 a new BookStack specific debug view was introduced:
+In v21.08.6 a new BookStack specific debug view was introduced.
+This was introduced to limit the accidental sharing of errors and confidential details, while
+providing important details & potentially helpful BookStack specific resources to the admin
+attempting to debug the problem at hand.
-This was introduced to limit the accidental sharing of errors and confidential details, while
-providing important details and potentially helpful BookStack specific resources to the admin
-attempting to debug the problem at hand.
+
+### Translations
+
+Another feature release, another language added to BookStack. A massive thanks to Indrek Haav for
+adding Estonian to BookStack!
+
+As usual, there's been a bunch of translation updates via CrowdIn since the last feature release.
+Thanks a bunch to all those listed below for their great continued work!
+
+- Indrek Haav (IndrekHaav) - *Estonian*
+- na3shkw - *Japanese*
+- Nicolas Pawlak (Mikolajek) - *French; Polish; German*
+- Michał Lipok (mLipok) - *Polish*
+- Hl2run - *Slovak*
+- Leonardo Mario Martinez (leonardo.m.martinez) - *Spanish, Argentina*
+- FastHogi - *German; German Informal*
+- Statium - *Russian*
+- Giancarlo Di Massa (digitall-it) - *Italian*
+- Thomas Hansen (thomasdk81) - *Danish*
+- Ngo Tri Hoai (trihoai) - *Vietnamese*
+- Luís Tiago Favas (starkyller) - *Portuguese*
+- Francesco Franchina (ffranchina) - *Italian*
+- Radim Pesek (ramess18) - *Czech*
+- aarchijs - *Latvian*
+- 10935336 - *Chinese Simplified*
+- m0uch0 - *Spanish*
+- nutsflag - *French*
+- anastasiia.motylko - *Ukrainian*
+- M Nafis Al Mukhdi (mnafisalmukhdi1) - *Indonesian*
+- 慕容潭谈 (591442386) - *Chinese Simplified*
### Introduction of Content Security Policy
Details of headers set can be found in the [CSP section of our security page](/docs/admin/security/#csp).
-### Translations
-
-TODO
-
-
### SAML 2 Enhancements
-The SAML 2.0 has received some attention in this release. It has recently been found that logging in via
+The SAML 2.0 authentication system has received some attention in this release.
+It has been found that logging in via
SAML could lose the original intended location context of a user, leading to them being redirect to the
-homepage after login instead of the page they actually wanted to read. This was due to a change in cookies
+homepage after login instead of the page they actually wanted to visit. This was due to a change in cookies
causing the user's session to be lost during the SAML flow. This release tweaks the flow so the session
is kept for correct expected redirection.
SAML2_SP_x509_KEY=<key_data>
```
-These options were primarily intended to help allow single-logout-service requests when using
+These options were primarily added to help fix single-logout-service requests when using
ADFS.Thanks to [@theodor-franke](https://github.com/BookStackApp/BookStack/pull/2902) for helping by doing the initial work to implement these changes.
### Full List of Changes
-
**Released in v21.10**
-TODO
-
+* Added OpenID Connect authentication option. Thanks to [@jasperweyne](https://github.com/BookStackApp/BookStack/pull/2169). ([#2960](https://github.com/BookStackApp/BookStack/pull/2960), [#2169](https://github.com/BookStackApp/BookStack/pull/2169), [#1390](https://github.com/BookStackApp/BookStack/issues/1390), [#1157](https://github.com/BookStackApp/BookStack/issues/1157))
+* Added Attachment API endpoints. ([#2986](https://github.com/BookStackApp/BookStack/pull/2986), [#2942](https://github.com/BookStackApp/BookStack/issues/2942))
+* Added Estonian language to BookStack via Crowdin. ([#2979](https://github.com/BookStackApp/BookStack/issues/2979))
+* Added support for SAML2 SLS signing to help address issues with ADFS. Thanks to [@theodor-franke](https://github.com/BookStackApp/BookStack/pull/2902). ([#2902](https://github.com/BookStackApp/BookStack/pull/2902))
+* Added support for base64 image content within markdown text via page POST/PUT. ([#2898](https://github.com/BookStackApp/BookStack/issues/2898))
+* Updated translations from Crowdin contributors. ([#2983](https://github.com/BookStackApp/BookStack/pull/2983))
+* Updated SAML ACS post flow to retain user session and therefore redirect to the correct location upon login. ([#2996](https://github.com/BookStackApp/BookStack/pull/2996), [#2552](https://github.com/BookStackApp/BookStack/issues/2552))
+* Fixed padding within book-tree sidebar items. Thanks to [@ffranchina](https://github.com/BookStackApp/BookStack/pull/3000). ([#3000](https://github.com/BookStackApp/BookStack/pull/3000))
**Released in v21.08.1 through v21.08.6**
* Added throttling to password reset requests. ([ca764ca](https://github.com/BookStackApp/BookStack/commit/ca764caf2d55a5c9bac61718d656423b0c3a060b))
* Added IP address to tracked activities and displayed in audit log. Thanks to [@johnroyer](https://github.com/BookStackApp/BookStack/pull/2936). ([#2936](https://github.com/BookStackApp/BookStack/pull/2936), [#2747](https://github.com/BookStackApp/BookStack/issues/2747))
* Added the option to use database table prefixes. Thanks to [@floviolleau](https://github.com/BookStackApp/BookStack/pull/2935). ([#2935](https://github.com/BookStackApp/BookStack/pull/2935))
+* Added concurrent page editing warnings upon draft save events. Thanks to [@MatthieuParis](https://github.com/BookStackApp/BookStack/pull/2877) ([#2877](https://github.com/BookStackApp/BookStack/pull/2877))
* Allowed the use of content includes when using a custom homepage.
* Updated DOMPDF chroot directory to prevent potential unintended file access. ([#2965](https://github.com/BookStackApp/BookStack/pull/2965))
* Updated TOTP setup flow to display a URL of the QR code contents during setup for non-QR scanning usage. ([#2908](https://github.com/BookStackApp/BookStack/issues/2908))
* Converted old test cases to remove reliance on BrowserKit. ([#2928](https://github.com/BookStackApp/BookStack/pull/2928))
* Fixed incorrect audit log detail on social account sign-in. ([#2930](https://github.com/BookStackApp/BookStack/issues/2930))
* Fixed issue where QR codes were not readable when using dark mode. ([#2925](https://github.com/BookStackApp/BookStack/issues/2925))
-* Added concurrent page editing warnings upon draft save events. Thanks to [@MatthieuParis](https://github.com/BookStackApp/BookStack/pull/2877) ([#2877](https://github.com/BookStackApp/BookStack/pull/2877))
* Fixed issue where TOTP setup would provide guest email address upon QR code scan when MFA setup was enforced at login. ([#2971](https://github.com/BookStackApp/BookStack/issues/2971))
This release marks the first feature release since [I left my job](https://danb.me/blog/posts/leaving-my-job-to-focus-on-open-source/) to focus on BookStack and other bits
for a while. My main focus of v21.10 was to work through some of the challenging
-and time consuming authentication elements that have been on the backlog for a while.
+& time consuming authentication elements that have been on the backlog for a while.
Having the extra time to dedicate to these has been helpful to perform the discovery and learning
-required without consuming many-a-weekend.
+required without frustratingly consuming many-a-weekend.
-Now I've reduced some of the PR backlog, initial focus going into next week will be on
+Now I've reduced some of the PR backlog, initial focus going into this week will be on
upgrading the codebase framework from Laravel 6 to Laravel 8 (As mentioned the "Next Steps"
of the last two feature release posts). Once this upgrade is done I'll look to test things out
via making improvements to existing systems. Both the search system and tagging capabilities are
-in need of some attention.
+in need of some attention and hence is where I may spend some time.
----
projects / website / commitdiff