Links

Add Google Authentication (Users)

A tutorial on setting up Google authentication for the Umbraco CMS backoffice users.
The Umbraco Backoffice supports external login providers (OAuth) for performing authentication of your users. This could be any OpenIDConnect provider such as Azure Active Directory, Identity Server, Google, or Facebook.
In this tutorial, we will take you through the steps of setting up a Google login for the Umbraco CMS backoffice.

What is a Google Login?

When you log in to the Umbraco Backoffice, you need to enter your username and password. Integrating your website with Google authentication adds a button that you can click to log in with your Google account.
Google login screen

Why?

I'm sure a lot of content editors and implementors of your Umbraco sites would love to have one less password to remember. Click Sign in with Google and if you are already logged in with your Google account, it will log you in directly.

What the tutorial covers

Prerequisites

For this tutorial, you need:

1. Setting up a Google OAuth API

The first thing to do is set up a Google API. To do this, you need to go to https://console.developers.google.com/ and log in with your Google account.

Setup a Google Console Project

  1. 1.
    Click the project dropdown and select New Project.
  1. 2.
    Enter a Project name, Organization, and Location.
  2. 3.
    Create the project.

Enable the Google+ API

  1. 1.
    Open the newly created project from the project dropdown.
  2. 2.
    Select Enable APIs and Services.
  1. 2.
    Use the search field to find the Google+ API.
  2. 3.
    Enable the product to enable the API.
Before you can create the credentials, you need to configure your consent screen.
  1. 1.
    Select OAuth Consent Screen from the left-side navigation menu.
  1. 2.
    Choose the User Type that fits your setup.
  2. 3.
    Select Create to move to the next step.
  1. 4.
    Fill in the required information:
    • App name
    • User support email
    • Developer contact information
  2. 5.
    Select Save and continue.
  3. 6.
    Select the scopes your project needs.
  4. 7.
    Move to the next step by selecting Save and Continue.
  5. 8.
    Verify the details provided.
  6. 9.
    Select Back to Dashboard to complete creating the Consent screen.

Create credentials

  1. 1.
    Click on Credentials in the left-side navigation menu.
  2. 2.
    Select Create Credentials and choose OAuth Client ID from the dropdown.
  1. 3.
    Select Web Application from the Application type dropdown.
  2. 4.
    Enter the following details:
    • Application Name
    • Authorized JavaScript origins
    • Authorized redirect URIs
  3. 5.
    Create the OAuth Client ID.
A popup appears displaying the ClientId and ClientSecret. You will need these values later while configuring your solution.
The ClientId and ClientSecret can always be accessed from the Credentials tab in the APIs & Services menu.

2. Integrating Google Auth in Visual Studio

Once the Google API is set up it is time to install the Google Auth provider on the Umbraco project.
If you are working with a Cloud project, see the Working locally article to complete this step.

Installing a Nuget Package

You can install and manage packages in Visual Studio either using the Package Manager Console (PowerShell) or the NuGet Package Manager.

Option 1: Package Manager Console (PowerShell)

The NuGet Package Manager Console lets you use NuGet PowerShell commands to manage NuGet packages on your project. You can use this option if you are comfortable using the Package Manager Console (PowerShell). The command listed below is specific to the Package Manager Console in Visual Studio:
  1. 1.
    Open your project/solution in Visual Studio.
  2. 2.
    Go to Tools > NuGet Package Manager > Package Manager Console.
A package manager console appears at the bottom where you can install packages with commands.
  1. 3.
    Type the following in the console:
Install-Package Microsoft.AspNetCore.Authentication.Google -Version 7.0.5

Option 2: NuGet Package Manager

The NuGet Package Manager UI in Visual Studio allows you to manage NuGet packages in projects and solutions.
  1. 1.
    Open your project in Visual Studio.
  2. 2.
    Go to Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution.
  3. 3.
    Select the Browse tab.
  4. 4.
    Type Microsoft.AspNetCore.Authentication.Google in the search field.
  5. 5.
    Ensure that your project is checked.
  6. 6.
    Select the version from the drop-down and click Install.
For more information on installing and managing packages in Visual Studio, see Microsoft Documentation.

3. Configuring the solution to allow Google logins

To use an external login provider such as Google on your Umbraco CMS project, you have to implement a couple of new classes:
  • A custom-named configuration class.
  • A static extension class.
You can create these files in a location of your choice. In this tutorial, the files will be added to an ExternalUserLogin/GoogleAuthentication folder.
  1. 1.
    Create a new class:GoogleBackOfficeExternalLoginProviderOptions.cs.
  2. 2.
    Add the following code to the file:
GoogleBackOfficeExternalLoginProviderOptions.cs
1
using Microsoft.Extensions.Options;
2
using Umbraco.Cms.Core;
3
using Umbraco.Cms.Web.BackOffice.Security;
4
5
namespace MyCustomUmbracoProject.ExternalUserLogin.GoogleAuthentication
6
{
7
public class GoogleBackOfficeExternalLoginProviderOptions : IConfigureNamedOptions<BackOfficeExternalLoginProviderOptions>
8
{
9
public const string SchemeName = "OpenIdConnect";
10
public void Configure(string name, BackOfficeExternalLoginProviderOptions options)
11
{
12
if (name != Constants.Security.BackOfficeExternalAuthenticationTypePrefix + SchemeName)
13
{
14
return;
15
}
16
17
Configure(options);
18
}
19
20
public void Configure(BackOfficeExternalLoginProviderOptions options)
21
{
22
// Customize the login button
23
options.ButtonStyle = "btn-danger";
24
options.Icon = "fa fa-cloud";
25
26
// The following options are only relevant if you
27
// want to configure auto-linking on the authentication.
28
options.AutoLinkOptions = new ExternalSignInAutoLinkOptions(
29
30
// Set to true to enable auto-linking
31
autoLinkExternalAccount: true,
32
33
// [OPTIONAL]
34
// Default: "Editor"
35
// Specify User Group.
36
defaultUserGroups: new[] { Constants.Security.EditorGroupAlias },
37
38
// [OPTIONAL]
39
// Default: The culture specified in appsettings.json.
40
// Specify the default culture to create the User as.
41
// It can be dynamically assigned in the OnAutoLinking callback.
42
defaultCulture: null,
43
44
// [OPTIONAL]
45
// Enable the ability to link/unlink manually from within
46
// the Umbraco backoffice.
47
// Set this to false if you don't want the user to unlink
48
// from this external login provider.
49
allowManualLinking: true
50
)
51
{
52
// [OPTIONAL] Callback
53
OnAutoLinking = (autoLinkUser, loginInfo) =>
54
{
55
// Customize the user before it's linked.
56
// Modify the User's groups based on the Claims returned
57
// in the external ogin info.
58
},
59
OnExternalLogin = (user, loginInfo) =>
60
{
61
// Customize the User before it is saved whenever they have
62
// logged in with the external provider.
63
// Sync the Users name based on the Claims returned
64
// in the external login info
65
66
// Returns a boolean indicating if sign-in should continue or not.
67
return true;
68
}
69
};
70
71
// [OPTIONAL]
72
// Disable the ability for users to login with a username/password.
73
// If set to true, it will disable username/password login
74
// even if there are other external login providers installed.
75
options.DenyLocalLogin = false;
76
77
// [OPTIONAL]
78
// Choose to automatically redirect to the external login provider
79
// effectively removing the login button.
80
options.AutoRedirectLoginToExternalProvider = false;
81
}
82
}
83
}
The code used here, enables auto-linking with the external login provider. This enables the option for users to login to the Umbraco backoffice prior to having a backoffice User.
Set the autoLinkExternalAccount to false in order to disable auto-linking in your implementation.
  1. 3.
    Create a new class: GoogleAuthenticationExtensions.cs.
  2. 4.
    Add the following code to the file:
GoogleAuthenticationExtensions.cs
1
using Umbraco.Cms.Core.DependencyInjection;
2
using Umbraco.Extensions;
3
using Microsoft.Extensions.DependencyInjection;
4
5
namespace MyCustomUmbracoProject.ExternalUserLogin.GoogleAuthentication
6
{
7
public static class GoogleAuthenticationExtensions
8
{
9
public static IUmbracoBuilder AddGoogleAuthentication(this IUmbracoBuilder builder)
10
{
11
// Register ProviderBackOfficeExternalLoginProviderOptions here rather than require it in startup
12
builder.Services.ConfigureOptions<GoogleBackOfficeExternalLoginProviderOptions>();
13
14
builder.AddBackOfficeExternalLogins(logins =>
15
{
16
logins.AddBackOfficeLogin(
17
backOfficeAuthenticationBuilder =>
18
{
19
backOfficeAuthenticationBuilder.AddGoogle(
20
// The scheme must be set with this method to work for the back office
21
backOfficeAuthenticationBuilder.SchemeForBackOffice(GoogleBackOfficeExternalLoginProviderOptions.SchemeName),
22
options =>
23
{
24
// Callback path: Represents the URL to which the browser should be redirected to.
25
// The default value is '/signin-google'.
26
// The value here should match what you have configured in you external login provider.
27
// The value needs to be unique.
28
options.CallbackPath = "/umbraco-google-signin";
29
options.ClientId = "YOURCLIENTID"; // Replace with your client id generated while creating OAuth client ID
30
options.ClientSecret = "YOURCLIENTSECRET"; // Replace with your client secret generated while creating OAuth client ID
31
});
32
});
33
});
34
return builder;
35
}
36
}
37
}
  1. 5.
    Replace YOURCLIENTID and YOURCLIENTSECRET with the values from the OAuth Client Ids Credentials window.
  2. 6.
    Update ConfigureServices in your Startup.cs class to register your configuration with Umbraco.
Startup.cs
1
using MyCustomUmbracoProject.ExternalUserLogin.GoogleAuthentication;
2
3
public void ConfigureServices(IServiceCollection services)
4
{
5
services.AddUmbraco(_env, _config)
6
.AddBackOffice()
7
.AddWebsite()
8
.AddComposers()
9
10
// Register your new static extension class
11
.AddGoogleAuthentication()
12
13
.Build();
14
}
  1. 7.
    Build and run the website.
  2. 8.
    Log in to the backoffice using the Google Auth option.
If auto-linking is disabled, the user will need to follow these steps in order to be able to use the Google Authenticaion:
  1. 1.
    Login to the backoffice using Umbraco credentials.
  2. 2.
    Select your user profile in the top-right corner.
  3. 3.
    Link your Google account.
  4. 4.
    Choose the account you which to link to the Umbraco login.
For future backoffice logins, the user will be able to use Google Authentication to login.