From 6ee48fb3386202846041c5401b862fdd43a9e9c0 Mon Sep 17 00:00:00 2001 From: Mikkel Holck Madsen Date: Wed, 2 Apr 2025 09:48:10 +0200 Subject: [PATCH 1/4] Update external-login-providers.md Add documentation for the metadata address property, and a lille note about handing invites to the backoffice --- umbraco-cloud/set-up/external-login-providers.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/umbraco-cloud/set-up/external-login-providers.md b/umbraco-cloud/set-up/external-login-providers.md index 903133a5195..3fab923e39a 100644 --- a/umbraco-cloud/set-up/external-login-providers.md +++ b/umbraco-cloud/set-up/external-login-providers.md @@ -180,7 +180,16 @@ The **alias** must be unique across different login providers in the same enviro Learn about what type of data and information you need for each field in the configuration form. -
FieldDescriptionFormatting
AliasA unique alias for the provider.

Use only lower-case.

Spaces are not allowed.

Client IdA unique Client ID generated in the external login provider.Entra ID: Guid
Auth0: Random characters
Google: {randomchars}.apps.googleusercontent.com
Client SecretA secret that is generated in the External Login Provider and is associated with the Client Id.
AuthorityThe 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
ScopesThese 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 TypeCurrently only OpenIDConnect is available.Default: OpenIdConnect
Default User GroupChoose 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 loginA 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 MappingsUse 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
No User Group Found BehaviourThis 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 NameYour 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.
+
FieldDescriptionFormatting
AliasA unique alias for the provider.

Use only lower-case.

Spaces are not allowed.

Client IdA unique Client ID generated in the external login provider.Entra ID: Guid
Auth0: Random characters
Google: {randomchars}.apps.googleusercontent.com
Client SecretA secret that is generated in the External Login Provider and is associated with the Client Id.
AuthorityThe 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
ScopesThese 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 TypeCurrently only OpenIDConnect is available.Default: OpenIdConnect
Default User GroupChoose 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 loginA 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 MappingsUse 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
No User Group Found BehaviourThis 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 NameYour 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.
Metadata AddressIf 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 known case for using a special metadata address is when using Entra Id, and you have set up Claims mapping. In this case, you need to 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, we are no longer able to handle the invitation flow to the backoffice. This is because the user needs to be created in the External Login Provider in order to log in. Umbraco Cloud can not handle this integration. +So when using an External Login Provider, it is up to you as an administrator to handle how users get access to the backoffice. + +A simple way is to send them an email containing a link to the backoffice, telling them to click the "Login with [your login provider]" button. ### Configuration scenarios From 1bd6f1c9dc4b3027703e0377709d246e910965d6 Mon Sep 17 00:00:00 2001 From: Mikkel Holck Madsen Date: Wed, 2 Apr 2025 12:26:09 +0200 Subject: [PATCH 2/4] Update umbraco-cloud/set-up/external-login-providers.md Co-authored-by: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> --- umbraco-cloud/set-up/external-login-providers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/umbraco-cloud/set-up/external-login-providers.md b/umbraco-cloud/set-up/external-login-providers.md index 3fab923e39a..bdb79ee64a0 100644 --- a/umbraco-cloud/set-up/external-login-providers.md +++ b/umbraco-cloud/set-up/external-login-providers.md @@ -181,7 +181,7 @@ The **alias** must be unique across different login providers in the same enviro Learn about what type of data and information you need for each field in the configuration form.
FieldDescriptionFormatting
AliasA unique alias for the provider.

Use only lower-case.

Spaces are not allowed.

Client IdA unique Client ID generated in the external login provider.Entra ID: Guid
Auth0: Random characters
Google: {randomchars}.apps.googleusercontent.com
Client SecretA secret that is generated in the External Login Provider and is associated with the Client Id.
AuthorityThe 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
ScopesThese 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 TypeCurrently only OpenIDConnect is available.Default: OpenIdConnect
Default User GroupChoose 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 loginA 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 MappingsUse 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
No User Group Found BehaviourThis 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 NameYour 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.
Metadata AddressIf 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 known case for using a special metadata address is when using Entra Id, and you have set up Claims mapping. In this case, you need to set the metadata address to the following: +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 From 3afba3351d4100baf51af54bd90d6f300d084a4f Mon Sep 17 00:00:00 2001 From: Mikkel Holck Madsen Date: Wed, 2 Apr 2025 12:26:50 +0200 Subject: [PATCH 3/4] Update umbraco-cloud/set-up/external-login-providers.md Co-authored-by: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> --- umbraco-cloud/set-up/external-login-providers.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/umbraco-cloud/set-up/external-login-providers.md b/umbraco-cloud/set-up/external-login-providers.md index bdb79ee64a0..9039f13f5aa 100644 --- a/umbraco-cloud/set-up/external-login-providers.md +++ b/umbraco-cloud/set-up/external-login-providers.md @@ -186,8 +186,9 @@ Learn about what type of data and information you need for each field in the con ### Handling invites when using an External Login Provider -When using an External Login Provider, we are no longer able to handle the invitation flow to the backoffice. This is because the user needs to be created in the External Login Provider in order to log in. Umbraco Cloud can not handle this integration. -So when using an External Login Provider, it is up to you as an administrator to handle how users get access to the backoffice. +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. A simple way is to send them an email containing a link to the backoffice, telling them to click the "Login with [your login provider]" button. From a9294a1d10d53b17dce042fcebaf69b8f5ecbc1b Mon Sep 17 00:00:00 2001 From: Mikkel Holck Madsen Date: Wed, 2 Apr 2025 12:27:03 +0200 Subject: [PATCH 4/4] Update umbraco-cloud/set-up/external-login-providers.md Co-authored-by: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> --- umbraco-cloud/set-up/external-login-providers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/umbraco-cloud/set-up/external-login-providers.md b/umbraco-cloud/set-up/external-login-providers.md index 9039f13f5aa..43f94e2512a 100644 --- a/umbraco-cloud/set-up/external-login-providers.md +++ b/umbraco-cloud/set-up/external-login-providers.md @@ -190,7 +190,7 @@ When using an External Login Provider, the invitation flow to the backoffice can As an administrator, you are responsible for managing user access to the backoffice. -A simple way is to send them an email containing a link to the backoffice, telling them to click the "Login with [your login provider]" button. +Send users an email with a backoffice link, instructing them to click "Login with [your login provider]". ### Configuration scenarios