umbraco-auth-provider

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Umbraco Auth Provider

Umbraco 身份验证提供程序

What is it?

什么是身份验证提供程序？

An Auth Provider enables external login (OAuth/SSO) for the Umbraco backoffice. It provides the UI component (login button) that connects to a backend authentication provider. The backend must be configured separately in C# - this extension type handles the frontend presentation and behavior. Common providers include Google, Microsoft, GitHub, and custom OAuth providers.

身份验证提供程序可为Umbraco后台启用外部登录（OAuth/SSO）功能。它提供连接到后端身份验证提供程序的UI组件（登录按钮）。后端需在C#中单独配置——此扩展类型负责前端的展示与行为。常见的提供程序包括Google、Microsoft、GitHub以及自定义OAuth提供程序。

Documentation

文档

Always fetch the latest docs before implementing:

External Login Providers: https://docs.umbraco.com/umbraco-cms/reference/security/external-login-providers
Extension Types: https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-types
Foundation: https://docs.umbraco.com/umbraco-cms/customizing/foundation

在实现前请务必获取最新文档：

外部登录提供程序：https://docs.umbraco.com/umbraco-cms/reference/security/external-login-providers
扩展类型：https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-types
基础框架：https://docs.umbraco.com/umbraco-cms/customizing/foundation

Workflow

工作流程

Fetch docs - Use WebFetch on the URLs above
Ask questions - Which OAuth provider? Custom UI needed? Auto-redirect?
Configure backend - Set up C# authentication provider first
Generate frontend files - Create manifest + optional custom element
Explain - Show what was created and how to test

获取文档 - 使用WebFetch获取上述URL的内容
确认需求 - 选择哪种OAuth提供程序？是否需要自定义UI？是否自动重定向？
配置后端 - 先设置C#身份验证提供程序
生成前端文件 - 创建清单文件 + 可选的自定义元素
说明解释 - 展示创建的内容及测试方法

Minimal Examples

最简示例

Manifest with Default Button (umbraco-package.json)

带默认按钮的清单（umbraco-package.json）

json

{
  "name": "My Auth Provider",
  "extensions": [
    {
      "type": "authProvider",
      "alias": "My.AuthProvider.GitHub",
      "name": "GitHub Login",
      "forProviderName": "Umbraco.GitHub",
      "meta": {
        "label": "Login with GitHub",
        "defaultView": {
          "icon": "icon-github",
          "color": "default",
          "look": "secondary"
        }
      }
    }
  ]
}

json

{
  "name": "My Auth Provider",
  "extensions": [
    {
      "type": "authProvider",
      "alias": "My.AuthProvider.GitHub",
      "name": "GitHub Login",
      "forProviderName": "Umbraco.GitHub",
      "meta": {
        "label": "Login with GitHub",
        "defaultView": {
          "icon": "icon-github",
          "color": "default",
          "look": "secondary"
        }
      }
    }
  ]
}

Manifest (TypeScript)

TypeScript清单

typescript

import type { ManifestAuthProvider } from '@umbraco-cms/backoffice/extension-registry';

const manifest: ManifestAuthProvider = {
  type: 'authProvider',
  alias: 'My.AuthProvider.Google',
  name: 'Google Login',
  forProviderName: 'Umbraco.Google', // Must match backend provider name
  meta: {
    label: 'Sign in with Google',
    defaultView: {
      icon: 'icon-google',
      color: 'default',
      look: 'outline',
    },
    behavior: {
      autoRedirect: false,
      popupTarget: 'umbracoAuthPopup',
      popupFeatures: 'width=600,height=600,menubar=no,location=no',
    },
    linking: {
      allowManualLinking: true,
    },
  },
};

export const manifests = [manifest];

typescript

import type { ManifestAuthProvider } from '@umbraco-cms/backoffice/extension-registry';

const manifest: ManifestAuthProvider = {
  type: 'authProvider',
  alias: 'My.AuthProvider.Google',
  name: 'Google Login',
  forProviderName: 'Umbraco.Google', // 必须与后端提供程序名称匹配
  meta: {
    label: 'Sign in with Google',
    defaultView: {
      icon: 'icon-google',
      color: 'default',
      look: 'outline',
    },
    behavior: {
      autoRedirect: false,
      popupTarget: 'umbracoAuthPopup',
      popupFeatures: 'width=600,height=600,menubar=no,location=no',
    },
    linking: {
      allowManualLinking: true,
    },
  },
};

export const manifests = [manifest];

Custom Login Button Element

自定义登录按钮元素

typescript

import type { ManifestAuthProvider } from '@umbraco-cms/backoffice/extension-registry';

const manifest: ManifestAuthProvider = {
  type: 'authProvider',
  alias: 'My.AuthProvider.Custom',
  name: 'Custom SSO Login',
  forProviderName: 'Umbraco.CustomSSO',
  element: () => import('./custom-auth-button.element.js'),
  meta: {
    label: 'Enterprise SSO',
  },
};

typescript

import type { ManifestAuthProvider } from '@umbraco-cms/backoffice/extension-registry';

const manifest: ManifestAuthProvider = {
  type: 'authProvider',
  alias: 'My.AuthProvider.Custom',
  name: 'Custom SSO Login',
  forProviderName: 'Umbraco.CustomSSO',
  element: () => import('./custom-auth-button.element.js'),
  meta: {
    label: 'Enterprise SSO',
  },
};

Custom Button Element (custom-auth-button.element.ts)

自定义按钮元素（custom-auth-button.element.ts）

typescript

import { html, css, customElement, property } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';

@customElement('my-custom-auth-button')
export class MyCustomAuthButtonElement extends UmbLitElement {
  @property({ type: String })
  providerName = '';

  @property({ type: String })
  displayName = '';

  #handleClick() {
    // Dispatch event to trigger auth flow
    this.dispatchEvent(
      new CustomEvent('auth-request', {
        bubbles: true,
        composed: true,
        detail: { providerName: this.providerName },
      })
    );
  }

  render() {
    return html`
      <button @click=${this.#handleClick}>
        <img src="/App_Plugins/MyAuth/logo.svg" alt="" />
        <span>${this.displayName}</span>
      </button>
    `;
  }

  static styles = css`
    button {
      display: flex;
      align-items: center;
      gap: var(--uui-size-space-3);
      width: 100%;
      padding: var(--uui-size-space-4);
      border: 1px solid var(--uui-color-border);
      border-radius: var(--uui-border-radius);
      background: var(--uui-color-surface);
      cursor: pointer;
    }

    button:hover {
      background: var(--uui-color-surface-alt);
    }

    img {
      width: 24px;
      height: 24px;
    }
  `;
}

export default MyCustomAuthButtonElement;

typescript

import { html, css, customElement, property } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';

@customElement('my-custom-auth-button')
export class MyCustomAuthButtonElement extends UmbLitElement {
  @property({ type: String })
  providerName = '';

  @property({ type: String })
  displayName = '';

  #handleClick() {
    // 触发身份验证流程的事件
    this.dispatchEvent(
      new CustomEvent('auth-request', {
        bubbles: true,
        composed: true,
        detail: { providerName: this.providerName },
      })
    );
  }

  render() {
    return html`
      <button @click=${this.#handleClick}>
        <img src="/App_Plugins/MyAuth/logo.svg" alt="" />
        <span>${this.displayName}</span>
      </button>
    `;
  }

  static styles = css`
    button {
      display: flex;
      align-items: center;
      gap: var(--uui-size-space-3);
      width: 100%;
      padding: var(--uui-size-space-4);
      border: 1px solid var(--uui-color-border);
      border-radius: var(--uui-border-radius);
      background: var(--uui-color-surface);
      cursor: pointer;
    }

    button:hover {
      background: var(--uui-color-surface-alt);
    }

    img {
      width: 24px;
      height: 24px;
    }
  `;
}

export default MyCustomAuthButtonElement;

Auto-Redirect Provider (Single Sign-On)

自动重定向提供程序（单点登录）

typescript

const manifest: ManifestAuthProvider = {
  type: 'authProvider',
  alias: 'My.AuthProvider.EnterpriseSSO',
  name: 'Enterprise SSO',
  forProviderName: 'Umbraco.EnterpriseSSO',
  meta: {
    label: 'Enterprise Login',
    behavior: {
      autoRedirect: true, // Automatically redirects to provider
    },
  },
};

typescript

const manifest: ManifestAuthProvider = {
  type: 'authProvider',
  alias: 'My.AuthProvider.EnterpriseSSO',
  name: 'Enterprise SSO',
  forProviderName: 'Umbraco.EnterpriseSSO',
  meta: {
    label: 'Enterprise Login',
    behavior: {
      autoRedirect: true, // 在登录页面自动重定向到提供程序
    },
  },
};

Backend C# Configuration (for reference)

后端C#配置（参考）

csharp

// Composer to register the provider
public class GitHubAuthenticationComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.AddBackOfficeExternalLogins(logins =>
        {
            logins.AddBackOfficeLogin(
                backOfficeAuthenticationBuilder =>
                {
                    backOfficeAuthenticationBuilder.AddGitHub(
                        backOfficeAuthenticationBuilder.SchemeForBackOffice("Umbraco.GitHub")!,
                        options =>
                        {
                            options.ClientId = "your-client-id";
                            options.ClientSecret = "your-client-secret";
                            options.CallbackPath = "/umbraco-github-signin";
                        });
                },
                options =>
                {
                    options.AutoLinkOptions = new ExternalSignInAutoLinkOptions(
                        autoLinkExternalAccount: true,
                        defaultUserGroups: new[] { "admin" }
                    );
                });
        });
    }
}

csharp

// 注册提供程序的Composer
public class GitHubAuthenticationComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.AddBackOfficeExternalLogins(logins =>
        {
            logins.AddBackOfficeLogin(
                backOfficeAuthenticationBuilder =>
                {
                    backOfficeAuthenticationBuilder.AddGitHub(
                        backOfficeAuthenticationBuilder.SchemeForBackOffice("Umbraco.GitHub")!,
                        options =>
                        {
                            options.ClientId = "your-client-id";
                            options.ClientSecret = "your-client-secret";
                            options.CallbackPath = "/umbraco-github-signin";
                        });
                },
                options =>
                {
                    options.AutoLinkOptions = new ExternalSignInAutoLinkOptions(
                        autoLinkExternalAccount: true,
                        defaultUserGroups: new[] { "admin" }
                    );
                });
        });
    }
}

Meta Properties

元属性

Property	Description
`label`	Button text
`defaultView.icon`	Button icon
`defaultView.color`	Button color (default, positive, warning, danger)
`defaultView.look`	Button style (default, primary, secondary, outline)
`behavior.autoRedirect`	Auto-redirect to provider on login page
`behavior.popupTarget`	Window name for popup
`behavior.popupFeatures`	Popup window features
`linking.allowManualLinking`	Allow linking to existing accounts

属性	描述
`label`	按钮文本
`defaultView.icon`	按钮图标
`defaultView.color`	按钮颜色（default、positive、warning、danger）
`defaultView.look`	按钮样式（default、primary、secondary、outline）
`behavior.autoRedirect`	在登录页面自动重定向到提供程序
`behavior.popupTarget`	弹窗的窗口名称
`behavior.popupFeatures`	弹窗窗口特性
`linking.allowManualLinking`	允许关联到现有账户

Common Icons

常用图标

```
icon-google
```
- Google
```
icon-microsoft
```
- Microsoft
```
icon-github
```
- GitHub
```
icon-facebook
```
- Facebook
```
icon-twitter
```
/
```
icon-x
```
- Twitter/X
```
icon-cloud
```
- Generic OAuth

That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.

```
icon-google
```
- Google
```
icon-microsoft
```
- Microsoft
```
icon-github
```
- GitHub
```
icon-facebook
```
- Facebook
```
icon-twitter
```
/
```
icon-x
```
- Twitter/X
```
icon-cloud
```
- 通用OAuth

就是这样！请务必获取最新文档，保持示例简洁，生成可直接运行的完整代码。