Overview:
- What’s new in Umbraco 9.3?
- Integrate external login providers for Members (improved OAuth support)
- Auto-linking for Members
- Two-factor Authentication (2FA) for Members
- Custom paths for storing Media
- New Umbraco Runtime Notifications
- Umbraco logo in the backoffice
- Performance Enhancements
- Updated Dependencies
- Community Contributions
- How to get your hands on Umbraco 9.3
Update 15-02-2022: Added information to the Umbraco logo in the backoffice feature.
What’s new in Umbraco 9.3?
Umbraco 9.3 provides a number of new and improved features that make it easier to configure and work with Umbraco 9. The emphasis is on developer experience so many of the additions will be noticeable when you are creating functionality in specific areas. This in turn makes it easier to provide value and functionality for your Umbraco projects.
You also find bug fixes and smaller improvements that help make things a little more smooth. Here are some of the highlights of the release:
Integrate external login providers for Members (improved OAuth support)
Umbraco 9 uses ASP.NET Core Identity for all authentication, both for backoffice Users and for Members, and this brings a host of options for developers to customize and extend. A popular use case is to add external login providers to provide a better authentication experience in an Umbraco installation. Having the ability to use an OAuth service, e.g. your Google account, to log in to the Member section on an Umbraco powered website not only makes it a lot easier but also more secure. It can also be a requirement to use a specific service, such as Okta or Microsoft 365 to log in to an internal site or intranet.
Umbraco 9 was already a big improvement on earlier Member authentication, going from a custom Membership provider to ASP.NET Core Identity, and with Umbraco 9.3 you get even more options to work with. If you’re familiar with adding external login providers to backoffice Users, you’ll be right at home.
All that is required to get up and running is a bit of dependency injection, using AddMemberExternalLogins on IUmbracoBuilder, to configure the service you want to integrate with and then register the configuration in Startup.cs. You can find a complete example in the External login providers documentation which has been updated with the new Member features.
If you want an example of how to implement this in your authentication flows you can use the Macro snippets for Login and Edit Profile. They have been updated for Umbraco 9.3 to show all external login providers registered with this pattern.
Auto-linking Member Accounts
Aside from adding the option to authenticate with OAuth providers, you might also need to link account creation and synchronization to an external service. This is also a lot easier in Umbraco 9.3 with new auto-linking options allowing to create new a Member or link existing accounts to update Member data based on the external login provider.
Again, this works similar to what was already implemented for users, so if you’ve tried that it should be familiar ground. Detailed explanations for both Users and the new auto-linking options for Members can be found in the Linking External Login Provider accounts documentation.
Two-factor Authentication (2FA) for Members
The last big update to Member authentication in Umbraco 9.3 is new features for adding 2FA to Member login flow. Enabling two-factor authentication is a great way to increase the security of a system. With Umbraco 9.3 it is a lot easier to enable for Umbraco Members. You can set up 2FA to use an authentication service (available from many vendors such as Microsoft, Google and many more) or even create your own codes and send them via email/SMS. Using an authentication app/service is viewed as the more secure option and the recommended approach unless you have specific requirements.
You find an all-new interface, ITwoFactorProvider, for adding 2FA via dependency injection as well as detailed documentation of the new improvements. It’s also worth mentioning that you can find examples of adding 2FA to your Member UI in the Login and Edit Profile Macro snippets.
Custom paths for storing Media
There are cases where you’d want to store files uploaded to the Media Library in a different path than the default location ~/media. This can easily be configured in Umbraco 9 via the UmbracoMediaPath property in appsettings.json or via a composer. If you want to store all your Media Library files in a different folder, this can be updated by adding:
That’s all well and good but a few things have been addressed in Umbraco 9.3 to provide more control over where the Media is stored and how files are served. First off, the above change will also change the URL Media is served from to “hostname/assets/…” which might not be intended. Secondly, it would require you to move any previously uploaded files to the new location.
In Umbraco 9.3 you’ll find a new configuration option that can be a useful alternative - say hi to UmbracoMediaPhysicalRootPath. This allows you to configure the physical location exclusively while preserving the standard URL for Media:
So in this case the files would be stored in “X:/Shared/Media” and served from “hostname/media/…”. Only changing the physical path and not the URL also allows for easy configuration of store files outside the wwwroot folder, in the above example this is shown as a network drive - easy and friendly 🙂
Another big improvement is that Media and App_Plugins files have been merged into the default WebRootProvider that's used by the whole ASP.NET Core framework. This provider is used to serve all static files using a single UseStaticFiles() call that adds a single StaticFileMiddelware, making it easier to configure. You can find examples of this here:
- Configuring custom response headers for all static files
- Use Tag Helpers to automatically append a version/cache buster to the URL
This currently only works for the PhysicalFileSystem. We'll release an updated version of Umbraco.StorageProviders.AzureBlob to ensure you get the same behavior on Umbraco Cloud.
New Umbraco Runtime Notifications
If you’ve been looking for ways to run custom code based on the Umbraco runtime starting, stopping or restarting there’s great news. In addition to the existing UmbracoApplicationStartingNotification and UmbracoApplicationStoppingNotification two new notifications have been added in Umbraco 9.3:
These are specifically tied to the Umbraco runtime, which can differ from the generic ASP.NET Core host application lifetime. All of the notifications have a new IsRestarting property to indicate whether the starting/started/stopping/stopped notification is published as part of a restart. Examples and details can be found in the original PRs linked above.
The U is back (in the office)
The Umbraco logo has been re-introduced to the backoffice and the Umbraco logo font has been added to the login screen (previously only showed the logo).
Logo + logo font on the Umbraco login screen
This has been done to increase brand awareness, or in plain speak, let people know they are using Umbraco CMS. The logo is in the same position in the backoffice as on the login screen.
Umbraco logo in the backoffice
Clicking the logo in the backoffice shows the current version number and a link to the umbraco.com website.
Raising brand awareness is important for everyone working with Umbraco. For many, it can be a big help to know the system they are using. It allows users of the backoffice to find information, documentation, engage with, or maybe even become regular contributors in the Umbraco community.
Update 15-02-2022: We have been made aware that this functionality was not included in the release candidate and was introduced late in the process which has resulted in limited time for user feedback. That is a mistake on our part. We should not be introducing new functionality or features, small or large, during the RC phase. This should only be for addressing issues before the public release.
Furthermore, there is a proposed additional ability to hide the logo in the backoffice, should that be a requirement. This is targeted for Umbraco 9.4 (March 24th) and Umbraco 8.18 (February 24th). You can see all the details on the PR: https://github.com/umbraco/Umbraco-CMS/pull/11999.
Performance Enhancements
There are also 2 performance improvements regarding property data that silently made their way into this release (they got merged up from the latest Umbraco 8 branch and are also part of the 8.18 release candidate).
Prune focal point and cropping values
The Image Cropper and Media Picker (v3) editors store their values into the database as JSON, but previously included indentation and redundant data. The default focal point and empty crops are now cleaned up and the crop width/height isn't stored as property data anymore (as they were already retrieved from the data type configuration). These savings can add up significantly, especially when you have a large number of images in your Media section (and even more if you have a lot of different crops configured). Our internal tests showed cases where we were able to reduce the data to only 7,5% of the original size. More information can be found on the PR: https://github.com/umbraco/Umbraco-CMS/pull/11805
Streamlined JSON data
During our testing, we also noticed a lot of other editors that stored indented JSON and some even empty values (empty strings or JSON arrays). Umbraco already skips adding database rows for property data values that are NULL, so we now take advantage of that by ensuring these empty values are converted to NULL. This again reduces the amount of stored property data significantly, as we expect most installations will have empty values in optional textboxes, tags (eg. for SEO keywords). Check out the PR, including our testing method: https://github.com/umbraco/Umbraco-CMS/pull/11806.
Both these improvements will only be applied when saving/publishing items from the backoffice, so you won't see any savings right away. In the case of content, you might want to configure a cleanup policy (released in Umbraco 9.1) to remove older content versions. You can find more on how to set this up in the Content Version Cleanup documentation.
Because this data is stored in the Umbraco content cache/NuCache (the cmsContentNu database table, local files and memory) and both the ExternalIndex/InternalIndex of Examine, this should have a compounding, positive impact on CPU, memory and disk space usage.
Updated Dependencies
Umbraco 9.3 also includes the following dependency updates
- ImageSharp.Web version to v1.0.5
- Follow-redirects from 1.14.4 to 1.14.7 in /src/Umbraco.Web.UI.Client
Changes since the release candidate
A couple of the changes in this release did not make it into the 9.3 release candidate. These are performance enhancements and the addition of the logo and logo font to the backoffice and login screen.
Community Contributions
Of the 27 bug fixes and feature additions in 9.3.0, a total of 13 of them have been contributed by the community, by 7 unique contributors.
We’re welcoming two brand new contributors who have made their first pull request for Umbraco CMS; they’re marked with a star below. Welcome to the contributor club Johannes and Maarten! 🏆
⭐ = First pull request to any Umbraco repository
And of course, as a thank you, we’ve just added another bunch of trees to our growing plot for today’s 9.3.0 release to celebrate your contributions! 🌳🌲🌴
How to get your hands Umbraco 9.3
As always, from today, all new Umbraco 9 projects on Umbraco Cloud will be running 9.3. For all our Umbraco Cloud customers with existing projects, this upgrade is only 2 minutes away:
We’ve wrapped it all up for you, so all you have to do now is follow these steps:
- Add a Development Environment to your project, if you do not already have one (Add a Development environment by clicking “Manage Environments” in the project view)
- Make sure you also restore the content to the Development Environment from your Live.
- When the Development Environment is all set up and you’ve made sure you don’t have any pending changes on the Development Environment - you are all ready to upgrade to Umbraco 9.3!
- It's as easy as clicking a button - like, literally clicking the "Upgrade Available" button on the Development Environment. The auto-upgrader will take care of everything from here! 🚀
- Once it's done, check the Development Environment to make sure everything is looking right.
- When that's confirmed, you are ready to deploy the upgrade to the next environment - Live or Staging, and start taking full advantage of all the new features.
Non-Cloud and release notes:
As always, installation and release notes can be found on Our: https://our.umbraco.com/contribute/releases/930
This release is also available from Nuget: https://www.nuget.org/packages/Umbraco.Cms/9.3.0
