External Login Providers

Configure an External Login Provider for access to the backoffice of your Umbraco Cloud project environments.

The External Login Providers feature in Umbraco Cloud allows you to integrate third-party authentication systems to manage backoffice user logins securely and efficiently. This functionality is especially useful for teams that want to simplify login management or use their existing identity systems.

This feature is currently only available for backoffice logins.

Using OpenID Connect, Umbraco Cloud supports external login providers such as Microsoft Entra ID, Auth0, Google, and so on. This feature helps administrators manage backoffice access, assign user roles, and improve security.

This guide shows you how to set up and configure external login providers for your Cloud projects. It includes the following steps:

Additionally, you can explore a few examples in the section below:

Requirements

To use the External Login Provider feature on Umbraco Cloud there are the following requirements:

  • Any cloud project based on:

    • Umbraco 13 with Umbraco.Cloud.Identity.Cms 13.2.1 or higher installed

    • Umbraco 14 with Umbraco.Cloud.Identity.Cms 14.2.1 or higher installed

    • Umbraco 15 with Umbraco.Cloud.Cms 15.1.1 or higher installed

You can use any login provider that supports the Open ID Connect protocol.

This guide covers implementing the following External Login Providers with Cloud:

  • Microsoft Entra ID

  • Auth0

  • Google

Make sure you have set up a tenant or organization in the provider.

Prepare your login provider

  1. Access the Microsoft Azure Portal.

  2. Locate the Microsoft Entra ID and enter your tenant.

  3. Select Add.

Select Add and then choose App Registration to start registering your app
  1. Choose App registration.

  2. Register your app.

    • Ignore the Redirect URI as that will be covered later in the guide.

  1. Click Register.

Once the app has been registered, you must find and note down a series of keys. These keys will be used to set up the login provider on Umbraco Cloud.

Locate and note down the following keys:

  • Application (client) ID - found on the Overview page for the app.

  • Authority URL - available from Endpoints on the Overview page.

  • Secret ID - needs to be generated on the Certificates & Secrets page.

Enterprise or custom setup

If you're working with an enterprise or a custom setup, ensure the email claim is included in the ID token configuration.

Once you have the keys from your login provider, you need to follow the next steps in the Umbraco Cloud Portal.

Keep the configuration for your login provider open, as you will come back to it later in the guide.

Register the login provider on Umbraco Cloud

  1. Access the Umbraco Cloud Portal.

  2. Navigate to the External Login Provider page under the Security section.

  1. Select Add Configuration.

  2. Fill out the fields.

The alias must be unique across different login providers in the same environment.

  1. Click Create to add the new configuration.

  2. Select Redirect URIs.

  3. Take note of the Redirect URI.

  4. Head back to the configuration for your external login provider.

  1. Click on Authentication.

  2. Select Add a platform.

  3. Select Web and add the Redirect URI.

  4. Add more Redirects URIs if needed.

  5. Under Implicit grant and hybrid flows check the following options:

    1. Access Tokens (used for implicit flows)

    2. ID tokens (used for implicit and hybrid flows)

  6. Click Configure to complete the configuration.

Configuration Fields

Learn about what type of data and information you need for each field in the configuration form.

Field
Description
Formatting

Alias

A unique alias for the provider.

Use only lower-case.

Spaces are not allowed.

Client Id

A unique Client ID generated in the external login provider.

Entra ID: Guid Auth0: Random characters Google: {randomchars}.apps.googleusercontent.com

Client Secret

A secret that is generated in the External Login Provider and is associated with the Client Id.

Authority

The URL for the External Login Provider. This can be found in the External Login Provider.

Entra ID: https://login.microsoftonline.com/<Directory (tenant)> Auth0: https://{accountId}.uk.auth0.com Google: https://accounts.google.com

Scopes

These are OpenID-Connect scopes. These are the minimum requirement and will allow the app to authenticate and get the users profile data, email and name.

Default values: openid, profile and email.

Auth Type

Currently only OpenIDConnect is available.

Default: OpenIdConnect

Default User Group

Choose which Umbraco User Group the user should be assigned to if nothing else is defined. Custom User Group added to the backoffice will also be available.

Default Options: Administrators Writers Editors Translators Sensitive Data

Enforce User Group on login

A checkbox to choose whether each login will re-evaluate the users role or if it should happen only on the first login.

N/A

User Group Mappings

Use this field to map roles within the login provider with Umbrac User Groups. Example: A user with the "Content Editor" role in the login provider, will be added to the Writer User Group in Umbraco.

Login Provider Role = Umbraco User Group Entra ID: Object ID of User Group = Umbraco User Group

No User Group Found Behaviour

This decides what happens if the mapping for the users User Group hasn't been defined. The options are to select the Default User Group or to disallow the user access to the backoffice.

Options: UseDefaultUserGroup, Unauthorized

User Group Claim Name

Your provider may assign users to specific roles (For example: Admin, Editor, Viewer). The User Group Claim Name is the field in the authentication token (claim) that identifies these roles. The system reads this claim to determine a user’s permissions. Example: If your provider sends roles in a claim named user_roles, you would set the User Group Claim Name to user_roles so the system can properly recognize user permissions.

Entra ID: email (ID), groups

Metadata Address

If you need a special metadata address for your External Login Provider, you can set it here. By default, the system will resolve the metadata address from the Authority Url, which is why this property is optional.

A common scenario for using a special metadata address is when working with Entra ID and configuring claims mapping. In this case, you must set the metadata address to the following:https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid={client-id}

Handling invites when using an External Login Provider

When using an External Login Provider, the invitation flow to the backoffice can no longer be managed within Umbraco. This is because users must first be created in the External Login Provider before they can log in. Umbraco Cloud does not handle this integration.

As an administrator, you are responsible for managing user access to the backoffice.

Send users an email with a backoffice link, instructing them to click "Login with [your login provider]".

Configuration scenarios

The following scenarios showcase how to use the configuration options when setting up the external login provider.

You can use the scenarios to learn how to configure the External Login Provider to fit your needs.

Scenario 1: Default User Group for all users

Any user that will be authenticated via the external login provider will end up in a default Umbraco backoffice User Group. As an admin, it will be your job to distribute the users into groups if needed.

  • Configure the Default User Group field, to specify which group all users should be added to by default.

Scenario 2: Evaluate the User Group on each login

Any user authenticated via the external login provider will always end up in the same Umbraco backoffice User Group. The group will be re-evaluated on each login, allowing you to change the group all users are in.

  • Configure the Default User Group field with the User Group all users should be added to.

  • Enable the Enforce User Group on login.

Scenario 3: Role-based User Group mapping with fallback to Default User Group

Any user authenticated via the external login provider can have a role claim associated with its login. This claim can then map to a backoffice User Group. A user with a role that cannot be mapped will end up in a default group.

  • Configure the Default User Group with the User Group that should be the fallback group.

  • Select User Default User Group under the No User Group Found Behaviour setting.

  • Fill in the User Group Mappings map.

  • Enable Enforce User Group on login.

Scenario 4: Role-based User Group mapping with fallback to deny access

Any user authenticated via the external login provider can have a role claim associated with its login. This claim can map to a backoffice User Group. If no roles match this claim, the user is denied access to the Umbraco backoffice.

  • Select Unauthorized in the No User Group Found Behaviour setting.

  • Fill in the User Group Mappings map.

  • Enable Enforce User Group on login.

Last updated

Was this helpful?