();
builder.AddMemberExternalLogins(logins =>
{
logins.AddMemberLogin(
memberAuthenticationBuilder =>
{
memberAuthenticationBuilder.AddProvider(
// The scheme must be set with this method to work for the back office
memberAuthenticationBuilder.SchemeForMembers(ProviderMembersExternalLoginProviderOptions.SchemeName),
options =>
{
// Callback path: Represents the URL to which the browser should be redirected to.
// The default value is `/signin-oidc`.
// The value here should match what you have configured in your external login provider.
// The value needs to be unique.
options.CallbackPath = "/umbraco-provider-signin";
options.ClientId = "YOURCLIENTID";
options.ClientSecret = "YOURCLIENTSECRET";
// Example: Save login tokens
options.SaveTokens = true;
});
});
});
return builder;
}
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
For a more in-depth article on how to set up OAuth providers in .NET refer to the [Microsoft Documentation](https://learn.microsoft.com/en-us/aspnet/core/security/authentication/social/?view=aspnetcore-8.0\&tabs=visual-studio).
### Customizing the BackOffice Login Button
If you want to customize the login button, you can do so by adding a custom element to the manifest file. This is useful if you want to display something other than a button. For example, a link or an image.
The path to the custom view is a virtual path, like this example: `"~/App_Plugins/MyPlugin/BackOffice/my-external-login.js"`.
When a custom view is specified, it is 100% up to this module to perform all the required logic.
The module should define a Custom Element and export it as default. Optionally, the Custom Element can declare a number of properties to be passed to it. These properties are:
* `manifest`: The manifest object for the provider that you registered in the `umbraco-package.json` file.
* `onSubmit`: A function that is called when the form is submitted. This function will handle the form submission and redirect the user to the external login provider.
* `userLoginState`: The current view state of the user. This can be one of the following values:
* `loggingIn`: The user is on the login screen.
* `loggedOut`: The user clicked the logout button and is on the logged-out screen.
* `timedOut`: The user's session has timed out and they are on the timed-out screen.
**TypeScript**
If you use TypeScript, you can use this interface to define the properties:
{% code title="login-types.ts" %}
```typescript
type UserLoginState = 'loggingIn' | 'loggedOut' | 'timedOut';
interface IExternalLoginCustomViewElement {
userLoginState: UserLoginState;
manifest: { forProviderName: string; meta?: { label?: string } };
onSubmit: (providerName: string) => void;
}
```
{% endcode %}
#### Examples
The Custom Element can be implemented in a number of ways with many different libraries or frameworks. The following examples show how to make a button appear and redirect to the external login provider. You will learn how to use the `externalLoginUrl` property to redirect to the external login provider. The login form should look like this when you open Umbraco:
When you click the button, the form will submit a POST request to the `externalLoginUrl` property. The external login provider will then redirect back to the Umbraco site with the user logged in.
{% hint style="info" %}
You have access to the [Umbraco UI Library](https://docs.umbraco.com/umbraco-cms/customizing/ui-library) in the custom element. You can use the UI components directly in your template.
{% endhint %}
{% code title="App\_Plugins/ExternalLoginProviders/umbraco-package.json" lineNumbers="true" %}
```json
{
"$schema": "../../umbraco-package-schema.json",
"name": "My Auth Package",
"allowPublicAccess": true,
"extensions": [
{
"type": "authProvider",
"alias": "My.AuthProvider.Generic",
"name": "My Auth Provider",
"forProviderName": "Umbraco.Generic",
"element": "/App_Plugins/ExternalLoginProviders/my-external-login.js", // This line has been added
"meta": {
"label": "Generic",
"defaultView": {
"icon": "icon-cloud"
},
"behavior": {
"autoRedirect": false
},
"linking": {
"allowManualLinking": true
}
}
}
]
}
```
{% endcode %}
{% tabs %}
{% tab title="Lit" %}
It is possible to use a library such as [Lit](https://lit.dev/) to render the custom element needed for the Login screen.
The following example shows how to use Lit to render the custom element.
The custom element will render a form with a button. The button will submit the form to the `externalLoginUrl` property.
No logic needs to be performed in the `constructor` method because Lit will automatically update any event listeners. Styling is also handled by Lit in the `static styles` property.
In this example, Lit version 3 is used and imported from a node module. You must set up npm and install the Lit package first. You should use a bundler such as [Vite](https://vitejs.dev) to bundle the Lit library with your custom element.
{% hint style="info" %}
To learn more about how to set up a project with Vite, see the [Creating your first extension](https://docs.umbraco.com/umbraco-cms/tutorials/creating-your-first-extension) tutorial.
{% endhint %}
{% code title="\~/App\_Plugins/ExternalLoginProviders/my-external-login.ts" lineNumbers="true" %}
```typescript
import { LitElement, css, html } from 'lit';
import { property, customElement } from 'lit/decorators.js';
type UserLoginState = 'loggingIn' | 'loggedOut' | 'timedOut';
interface IExternalLoginCustomViewElement {
userLoginState: UserLoginState;
manifest: { forProviderName: string; meta?: { label?: string } };
onSubmit: (providerName: string) => void;
}
/**
* This is an example how to set up a LitElement component.
*/
@customElement('my-lit-view')
export default class MyLitView extends LitElement implements IExternalLoginCustomViewElement {
@property({ type: String, attribute: false })
userLoginState!: UserLoginState;
@property({ type: Object, attribute: false })
manifest!: { forProviderName: string; meta?: { label?: string } };
@property({ attribute: false })
onSubmit!: (providerName: string) => void;
get displayName() {
return this.manifest.meta?.label ?? this.manifest.forProviderName;
}
override render() {
return html`
Our Company
If you have an account with Our Company, you can sign in to Umbraco by clicking the button below.
The user is currently: ${this.userLoginState}
this.onSubmit(this.manifest.forProviderName)}>
${this.displayName}
`;
}
static override readonly styles = css`
:host {
display: block;
width: 100%;
}
#button {
width: 100%;
}
`;
}
```
{% endcode %}
{% endtab %}
{% tab title="Lit (JavaScript)" %}
It is also possible to use vanilla JavaScript with Lit.
The following example imports Lit from a CDN and uses it to render the custom element needed for the Login screen:
{% code title="\~/App\_Plugins/ExternalLoginProviders/my-external-login.js" lineNumbers="true" %}
```javascript
import { LitElement, css, html } from 'https://cdn.jsdelivr.net/gh/lit/dist@3/core/lit-core.min.js';
/**
* This is an example how to set up a LitElement component.
*/
export default class MyLitView extends LitElement {
static get properties() {
return {
manifest: { type: Object },
onSubmit: { type: Function },
userLoginState: { type: String, state: true }
};
}
get displayName() {
return this.manifest.meta?.label ?? this.manifest.forProviderName;
}
render() {
return html`
Our Company
If you have an account with Our Company, you can sign in to Umbraco by clicking the button below.
The user is currently: ${this.userLoginState}
this.onSubmit(this.manifest.forProviderName)}>
${this.displayName}
`;
}
static styles = css`
:host {
display: block;
width: 100%;
}
#button {
width: 100%;
}
`;
}
customElements.define('my-lit-view', MyLitView);
```
{% endcode %}
{% endtab %}
{% tab title="Vanilla (JavaScript)" %}
It is necessary to define a template first and then the custom element itself. The template is a small HTML form with a button.
The custom element will then render the template and attach an event listener for clicks on the button in the `constructor` method.
{% code title="\~/App\_Plugins/ExternalLoginProviders/my-external-login.js" lineNumbers="true" %}
```javascript
const template = document.createElement('template');
template.innerHTML = `
Our Company
If you have signed up with Our Company, you can sign in to Umbraco by clicking the button below.
Sign in with Our Company
`;
/**
* This is an example how to set up a custom element as a Web Component.
*/
export default class MyCustomView extends HTMLElement {
manifest = {};
onSubmit = () => {};
userLoginState = '';
constructor() {
super();
this.attachShadow({ mode: 'open' });
this.shadowRoot.appendChild(template.content.cloneNode(true));
this.shadowRoot.getElementById('button').addEventListener('click', () => {
this.onSubmit(this.manifest.forProviderName);
});
}
}
customElements.define('my-custom-view', MyCustomView);
```
{% endcode %}
{% endtab %}
{% endtabs %}
## Common issues
### 404 error on callback path
Some external login providers, such as Microsoft Entra ID, may send large query strings when the response mode is set to `query`. By default, IIS restricts the maximum allowed query string length, which can cause the external login callback to fail with a 404 error.
This typically occurs during the authentication callback to Umbraco.
{% hint style="info" %}
This limitation is imposed by IIS and is not specific to Umbraco. For more details on configuring request limits, see the official Microsoft documentation on the [Request Limits element](https://learn.microsoft.com/en-us/iis/configuration/system.webserver/security/requestfiltering/requestlimits/).
{% endhint %}
To resolve this, increase the allowed query string and URL length by setting `maxQueryString` and `maxUrl` in your `web.config` file.
For example:
```xml
```
