文档

快速入门

Authagonal 为每个租户提供完全符合标准的 OIDC 服务器。每个租户拥有自己的发行者 URL、发现文档和令牌端点——租户之间不共享基础设施。您可以在 5 分钟内从零开始完成登录流程的搭建。

创建租户

在 authagonal.io 注册并为您的租户选择一个 slug。该 slug 将成为您的发行者域名：{slug}.authagonal.io。创建账户后，验证您的电子邮箱以激活租户。

在注册时为您的租户选择唯一的 slug

注册客户端

在门户侧边栏中导航到客户端，然后点击创建。为您的应用输入 clientId 和 clientName。然后配置至少一个重定向 URI——这是用户完成身份验证后跳转的地址。例如：https://app.example.com/callback。

在门户中注册新的 OAuth 客户端

您的首次登录

最快的集成方式是使用 oidc-client-ts，一个轻量级的 JavaScript 和 TypeScript 应用 OIDC 客户端库。

import { UserManager } from 'oidc-client-ts';

const mgr = new UserManager({
  authority: 'https://acme.authagonal.io',
  client_id: 'my-app',
  redirect_uri: 'https://app.example.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
});

// Redirect to login
mgr.signinRedirect();

// On callback page
const user = await mgr.signinRedirectCallback();
console.log(user.profile); // { sub, email, name, ... }

如果您更喜欢不使用库的最简方式，可以使用标准的 OAuth 2.0 授权码流程配合原生 fetch：

// 1. Redirect the user to the authorization endpoint
const authorizeUrl = new URL('https://acme.authagonal.io/connect/authorize');
authorizeUrl.searchParams.set('client_id', 'my-app');
authorizeUrl.searchParams.set('redirect_uri', 'https://app.example.com/callback');
authorizeUrl.searchParams.set('response_type', 'code');
authorizeUrl.searchParams.set('scope', 'openid profile email');
authorizeUrl.searchParams.set('code_challenge', codeChallenge);
authorizeUrl.searchParams.set('code_challenge_method', 'S256');
window.location.href = authorizeUrl.toString();

// 2. On the callback page, exchange the code for tokens
const res = await fetch('https://acme.authagonal.io/connect/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: new URLSearchParams(window.location.search).get('code')!,
    redirect_uri: 'https://app.example.com/callback',
    client_id: 'my-app',
    code_verifier: codeVerifier,
  }),
});

const tokens = await res.json();
// tokens.id_token, tokens.access_token, tokens.refresh_token

您的租户默认登录页面

仪表板

门户仪表板为您提供租户的实时概览。它展示最重要的指标——用户增长、身份验证活动，以及快速导航到门户中的每个功能。

概览

仪表板顶部显示欢迎消息和当前用户总数。下方的日活跃用户图表显示过去 7 天每天完成身份验证的唯一用户数，让您快速了解参与趋势。

仪表板主屏幕，包含 DAU 图表和活动概览

活动指标

活动指标面板显示四张统计卡片，汇总关键身份验证事件：

• 成功登录——已完成的身份验证流程总数
• 失败登录——凭证错误、账户锁定或策略拒绝
• 活跃用户——所选时间段内完成身份验证的唯一用户数
• SCIM 操作——来自已连接身份提供商的用户和组配置事件

使用时间范围筛选器在24 小时、3 天、7 天和30 天之间切换。所有统计卡片和图表会更新以反映所选时间窗口。

可配置时间范围的活动指标

快速导航

指标面板下方，导航卡片直接链接到每个主要功能：客户端、用户、组、角色、SSO、SCIM、品牌和设置。每张卡片都显示简要说明，方便新团队成员快速了解。

客户端

OAuth 客户端代表通过您的租户进行用户身份验证的应用。每个客户端都有自己的重定向 URI、作用域、授权类型、令牌有效期和 MFA 策略配置。

客户端列表

客户端页面显示所有已注册客户端的表格。每行显示 clientId、显示名称、以彩色标签形式显示的允许授权类型，以及是否启用了 PKCE。点击任意行可打开完整的配置编辑器。

带有授权类型标签和 PKCE 指示器的客户端列表

创建客户端

点击创建客户端以注册新应用。您需要提供两个字段：

• clientId——客户端的唯一标识符（例如 my-spa）
• clientName——易于阅读的显示名称

注册新的 OAuth 客户端

删除客户端

要删除客户端，请打开客户端配置，然后点击页面底部的删除客户端按钮。系统会要求您在永久删除前进行确认。已删除客户端的所有活跃会话和令牌将立即失效。

客户端配置参考

每个客户端都有一组全面的配置选项，分为多个部分。

常规设置

URI

URI 字段使用标签输入——输入值后按回车或逗号添加。点击标签上的 X 可将其移除。

用于配置 URI 的标签输入字段

作用域与授权类型

令牌有效期

按客户端配置令牌有效期

登出 URI

客户端可以注册 back-channel 和 front-channel 登出 URI。两者均为可选——配置与您的应用清理会话方式相匹配的那一个或两个。

MFA 策略

每个客户端可以使用按客户端设置覆盖租户范围的 MFA 策略。MFA 策略下拉菜单提供三个选项：

按客户端的 MFA 策略覆盖

企业 SSO

企业 SSO 让您的客户使用自己的身份提供商。Authagonal 支持 SAML 2.0 和 OIDC 联合身份验证，配合基于域的路由，用户可以根据其电子邮箱地址自动跳转到正确的身份提供商。

基于域的 SSO 路由

SAML 2.0 连接

要创建 SAML 连接，请导航到 SSO 页面并选择 SAML 选项卡。提供以下信息：

保存连接后，Authagonal 会获取元数据文档并导入身份提供商的签名证书、SSO 端点 URL 和名称标识符格式。元数据会定期刷新以获取证书轮换。

创建 SAML 2.0 SSO 连接

OIDC 连接

要创建 OIDC 联合身份验证连接，请选择 OIDC 选项卡并提供：

创建 OIDC 联合身份验证连接

域路由

域路由根据用户的电子邮箱域名自动将用户重定向到正确的身份提供商。当用户在登录页面输入电子邮箱时，Authagonal 会检查域名部分（例如 acme.com）是否匹配任何已配置的 SSO 连接。如果匹配，用户将被无缝重定向到其组织的身份提供商。

域路由将电子邮箱域名映射到身份提供商

JIT 配置

默认情况下，当用户首次通过 SSO 登录且在您的租户中不存在时，Authagonal 会自动创建其账户（即时配置）。可以通过在创建或编辑连接时勾选禁用 JIT 配置来按连接禁用此功能。

禁用 JIT 配置后，只有预先配置的用户——通过 SCIM、门户的用户页面或 API——才能通过该连接登录。未知用户会收到 access_denied 错误，并被引导联系其管理员。

用户

用户页面让您管理租户中的所有终端用户。您可以搜索用户、查看用户详情、创建新账户，并查看每个用户的配置来源。

搜索与分页

搜索栏支持按电子邮箱或用户 ID 筛选。搜索有 300 毫秒的防抖延迟，因此在您输入时结果会更新，而不会过度调用 API。结果以每页 50 个用户分页——使用表格底部的导航控件在页面之间切换。

用户表格

用户表格为每个用户显示以下列：

带搜索栏和分页的用户列表

创建用户

点击创建用户以添加新的本地用户。表单需要填写：

创建新的本地用户

首选语言

每个用户都有一个首选语言，它同时决定其托管界面以及 Authagonal 发送给他们的事务性电子邮件（验证、密码重置、欢迎等）。您可以在创建用户时设置它，并随时从用户详情页面更改。如果用户未设置首选语言，Authagonal 将回退到英语。选择器提供所有受支持的语言：英语、德语、法语、西班牙语、葡萄牙语、越南语和简体中文。

在详情页面设置用户的首选语言

用户详情

点击用户列表中的任意一行以打开其详情页。您可以在此编辑个人资料、管理角色、重置 MFA、查看自定义属性，以及删除用户。

个人资料

编辑用户的邮箱、姓/名、电话、公司、外部 ID 和激活状态。邮箱更改必须在租户内保持唯一；如果已被占用，API 会返回 email_in_use。

角色

分配和取消在角色页面定义的角色。当客户端启用 includeRolesInTokens 时，角色成员关系会出现在 ID 和访问令牌中。

多因素认证

查看为用户注册的每个 MFA 凭据——身份验证器应用（TOTP）、WebAuthn/通行密钥以及恢复码——每个都有注册和最后使用时间戳。您可以删除单个凭据，或重置所有 MFA。重置会强制用户在下次登录时重新注册。

自定义属性

附加到用户的任意键/值数据。键必须唯一。属性通过用户资料 API 和 SCIM 公开，并可通过配置自定义作用域的 userClaims 映射到访问令牌声明。

组织

该用户所属的组织。它是您自己的一个自由文本标识符，会作为 org_id 声明出现在该用户的令牌上，以及出现在 /connect/userinfo 上（需带 profile 作用域）。Authagonal 从不推导这个值：它由您的配置应用设置，或由创建该用户的 SCIM 凭据设置，也可以在此处手动设置。

字段旁边的链接会列出共享该值的所有人，同一个筛选条件在 API 上也可用，形式为 GET /api/v1/users?organizationId=。用它来查明谁属于某个特定客户，而不必翻遍整个用户目录。

删除用户

永久删除该用户及其所有 MFA 凭据。输入用户邮箱以确认——无法撤销。

组

组让您组织用户并在令牌中包含组成员关系。组可以在门户中手动创建，也可以通过 SCIM 从外部身份提供商自动配置。

组列表

组页面显示租户中的所有组及以下信息：

带来源指示器的组列表

创建组

点击创建组并输入组的 displayName。组名应具有描述性且在租户内唯一（例如「Engineering」、「Billing Admins」、「Beta Testers」）。

组详情与成员

点击任意组可打开详情视图。在这里您可以查看所有当前成员并管理成员关系：

• 添加成员——输入用户 ID 将用户添加到组。
• 移除成员——点击任意成员旁边的移除按钮即可单独移除。

在详情视图中管理组成员关系

令牌中的组

当客户端启用 includeGroupsInTokens 时，ID 令牌中会包含一个 groups 声明，其中包含用户的组成员关系。每个条目包含组的 id 和 name：

{
  "sub": "user-123",
  "email": "[email protected]",
  "groups": [
    { "id": "grp-001", "name": "Engineering" },
    { "id": "grp-002", "name": "Beta Testers" }
  ]
}

角色

角色支持应用中的基于角色的访问控制（RBAC）。在 Authagonal 中定义角色，将其分配给用户，并使用令牌中的 roles 声明在您的应用逻辑中执行授权。

管理角色

角色页面显示所有已定义角色的表格，支持内联编辑。每个角色包含：

创建角色

点击创建角色并提供名称和描述。角色名称应简洁，并在应用中遵循一致的命名约定（例如，使用小写加连字符：billing-admin）。

内联编辑

角色支持直接在表格中内联编辑。点击任意角色上的铅笔图标进入编辑模式——名称和描述字段变为可编辑。修改值后，点击对勾图标保存。更改立即生效。

删除角色

点击任意角色上的删除图标将其移除。系统会要求您在永久删除前进行确认。移除角色不会追溯使现有令牌失效——该角色将不会出现在删除后签发的新令牌中。

在角色表格中内联编辑角色

令牌中的角色

分配给用户的角色作为 roles 声明包含在 ID 令牌中。您的应用可以读取此声明来做出授权决策：

{
  "sub": "user-123",
  "email": "[email protected]",
  "roles": ["admin", "billing-admin"]
}

SCIM 用户配置

SCIM 2.0（跨域身份管理系统）支持从 Okta、Azure AD、OneLogin 和 JumpCloud 等企业身份提供商自动配置用户和组。配置完成后，用户账户和组成员关系会自动从上游身份提供商同步到您的 Authagonal 租户。

SCIM 用户生命周期同步与下游配置

设置步骤

按照以下步骤为客户端启用 SCIM 用户配置：

1. 选择客户端应用——选择 SCIM 配置将关联的 OAuth 客户端。
2. 生成 SCIM 令牌——提供描述和到期天数，然后生成令牌。
3. 立即复制令牌——原始令牌值仅显示一次。在关闭对话框前复制它。
4. 配置您的身份提供商——在您的身份提供商的 SCIM 设置中，输入基础 URL 和 Bearer 令牌。
5. 测试用户同步——从您的身份提供商触发测试同步，并验证用户是否出现在 Authagonal 门户中。

SCIM 基础 URL

使用以下基础 URL 配置您的身份提供商：

https://{slug}.authagonal.io/scim/v2

将 {slug} 替换为您的租户 slug。

SCIM 设置页面，包含令牌生成功能

令牌管理

SCIM 令牌用于验证来自身份提供商的配置请求。您可以为每个客户端管理多个令牌：

要撤销令牌，请点击令牌旁边的撤销按钮。已撤销的令牌在列表中仍然可见（用于审计目的），但会立即停止接受请求。

令牌管理，包含活跃和已撤销令牌指示器

测试连接

通过查询 ServiceProviderConfig 端点验证您的 SCIM 集成是否正常工作：

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://acme.authagonal.io/scim/v2/ServiceProviderConfig

成功的响应会返回一个 JSON 文档，描述支持的 SCIM 功能，包括批量操作、筛选和更改密码功能。

一个凭据能看到什么

一个 SCIM 凭据只能看到它自己配置的用户和组。读取、更新或删除由其他连接器创建的用户会返回 404，列表只返回它自己的，而一个组的成员也只能是同一个连接器配置过的用户。以任何其他方式创建的账户，无论是由管理员创建、通过自助注册创建，还是通过 SSO 即时配置创建，对 SCIM 都完全不可见。

这条边界是按客户端划分的，而不是按令牌。在同一个客户端上签发的两个凭据是拥有两个密钥的同一个身份，每一个都可以修改另一个创建的内容。请给互不信任的连接器各配一个客户端。externalId 的作用范围也是如此，因此两个连接器可以各自把 ext-001 用在不同的人身上而不会冲突。

取消配置

DELETE /scim/v2/Users/{id} 会停用该账户并将其标记为已删除。记录会按 RFC 7644 允许的方式保留，但对之后的每一次操作都返回 404，并且不会出现在列表中。该用户的 MFA 注册和组成员关系会被清除，其 externalId 映射会被释放，已签发的令牌全部被撤销，因此访问权限立即终止，而不是等到令牌下次过期。

如果同一个人后来被重新雇用并重新创建，他们会获得一个新的用户 id。标识符从不重复使用：该 id 是您签发过的每一个令牌中的 subject，因此重用它会在每个信任该 id 的应用中，悄无声息地把前一位持有者的历史交给新入职的人。

为已同步的用户标记组织

SCIM 没有提供任何方式让连接器说明它正在同步您的哪一个客户。核心 SCIM 未定义组织属性，因此一次普通的用户创建只会告诉您此人的姓名和邮箱，不会说明他们属于谁。如果多个客户都向您的租户配置用户，他们的用户到达时无法区分。

回答这个问题的是凭据，而不是请求本身。创建 SCIM 令牌时，请将组织设置为您自己的一个标识符。通过该令牌配置的每个用户都会被标记上它，此后它会作为 org_id 声明出现在这些用户的令牌上。为每个客户在同一个客户端上签发一个凭据，他们同步过来的用户就能被正确归属，而不必为每个客户单独注册一个客户端。留空则用户不带标记，这也是在此功能出现之前每个凭据的行为方式。

标记只在用户被创建时应用，绝不会在之后的更新中应用，因此一次例行的增量同步不会悄悄改动已有账户的归属。如果您同时还运行一个配置应用，凭据上显式设置的标记优先：/try 响应只会填充仍然为空的组织。

支持的架构

我们实现了 SCIM 2.0 的核心 User 和 Group 架构（RFC 7643）。支持的用户属性有 userName、name.givenName、name.familyName、displayName、emails、active、externalId 和 preferredLanguage / locale。

enterprise user 扩展未实现，因此 department、manager、employeeNumber、costCenter、division 和 organization 会被接受并忽略，而不是被存储，create、replace 和 PATCH 都是如此。Entra 和 Okta 默认都会映射其中一部分，因此您无需把它们从属性映射中删除。要把某个用户归属到您的某个客户，请改为在 SCIM 凭据上设置组织：enterprise 的 organization 属性是由您客户的身份提供商断言的，它被有意设计为不会成为该用户的 org_id。

OAuth 作用域

作用域允许客户端请求用户数据或权限的特定部分。Authagonal 支持标准 OIDC 作用域和您为自己的 API 定义的自定义作用域。

内置作用域

自定义作用域

在作用域页面定义您自己的作用域。每个作用域描述客户端可以请求的权限或资源（例如 billing.read、orders.write）。

令牌上的自定义声明

自定义声明包含两半。来源是按用户的数据：每个 AuthUser 都有一个 customAttributes 字典，可以通过 Portal（用户 → 用户 → 自定义属性）、SCIM 或 TCC 配置钩子来填充。释放按作用域进行：每个作用域的 userClaims 列表声明允许离开服务器的键。

当客户端请求作用域时，Authagonal 会遍历已授予的作用域，合并其 userClaims 列表，仅从用户的 customAttributes 中输出这些键。未知键会被静默丢弃 — 客户端无法通过猜测名称读取属性。标准 OIDC 声明 (sub、email、name 等) 遵循规范，不受白名单限制。

# 1. On the user (Portal → Users → {user} → Custom Attributes)
department = "engineering"
employee_id = "E-1042"
seat_tier = "enterprise"

# 2. On a custom scope (Portal → Scopes → projects.read)
name        = "projects.read"
userClaims  = ["department", "seat_tier"]   # <-- whitelist

# 3. Client requests scope=openid projects.read
# Decoded access token (relevant fields only):
{
  "sub": "u-9b…",
  "scope": "openid projects.read",
  "department": "engineering",
  "seat_tier":  "enterprise"
  // employee_id is NOT emitted — it's not in the whitelist for any granted scope.
}

将作用域分配给客户端

在客户端 → 作用域与授权选项卡中添加允许的作用域。客户端只能请求已被授予的作用域；未知的作用域将被拒绝，返回 invalid_scope。

品牌

自定义您的租户登录页面的外观和感觉。品牌设置让您将身份验证体验与产品的视觉形象相匹配——从 Logo 和颜色到高级 CSS 覆盖。

外观

带实时颜色预览的外观设置

联系信息

登录页面切换

控制租户登录页面上显示的元素：

应用了自定义品牌的示例登录页面

自定义 CSS

如需完全控制登录页外观，请在品牌设置中提供 CSS 文件 URL。该文件会在默认样式之后加载，因此您的规则优先。

深色模式

登录应用提供浅色、深色和跟随系统三种主题。用户在登录页面上通过切换按钮选择；选择会在会话间保留。当设置为 system 时，SPA 会实时跟踪 prefers-color-scheme。

浅色值在 :root 中声明；深色覆盖仅限于 .dark。通过 customCssUrl 设置的租户品牌样式始终优先——无论用户选择何种主题，您的颜色都会保留。

设置

配置租户范围的安全策略、Webhook 和环境设置。这些设置全局适用于所有客户端，除非在客户端级别被覆盖。

密码策略

定义租户中所有用户的密码复杂度要求：

密码策略配置

MFA 策略

租户范围的 MFA 策略设置默认的多因素身份验证行为。单个客户端可以覆盖此设置。

会话与锁定

控制会话持续时间和账户锁定行为：

会话和锁定配置

Webhook

Webhook 让你实时响应认证事件。两个事件 (onUserAuthenticated、onTokenIssued) 是可强制的 — 默认情况下它们异步触发，不会阻塞用户，但你可以按事件启用强制，使非 2xx 响应或 {"allow": false} 响应体拒绝该操作。其余事件都是通知 — 永远是触发即忘，从不阻塞。

其他 Webhook 设置：

Webhook 事件配置

验证 Webhook

一旦配置了任何 Webhook URL，Authagonal 就会为每个租户生成一个签名密钥（一个 whsec_… 值，在设置 → Webhook 下以只读方式显示）。每次出站投递都会带有一个 X-Authagonal-Signature: t=<unix>,v1=<hex> 头，其中 v1 为 HMAC-SHA256(secret, "{t}.{body}")，基于原始请求体计算。在你的端点上重新计算它并进行常量时间比较，以确认请求确实来自 Authagonal 且未被篡改 —— 并拒绝 t 过于陈旧的投递以阻止重放攻击。

import crypto from 'node:crypto';

// rawBody MUST be the exact bytes Authagonal sent — verify before any JSON re-serialization.
function verifyAuthagonalWebhook(signatureHeader, rawBody, signingSecret) {
  const parts = Object.fromEntries(signatureHeader.split(',').map((p) => p.split('=')));
  const { t, v1 } = parts;

  // Replay protection: reject deliveries older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  return v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

维护窗口

为证书轮换和基础设施更新等破坏性操作设置首选维护窗口。选择一个 UTC 时间（0-23）——门户还会显示对应的本地时区时间以方便参考。

注册与访问

谁可以成为您租户中的用户，以及他们在什么条件下可以登录。

不活跃用户保留

可选地停用并随后删除长期未使用的账户，避免目录里永远堆积着休眠身份。两者在您设置之前都处于关闭状态，且删除是永久性的。

审计导出与远程备份

两种按计划、而非按需申请取出数据的方式。审计导出会把每一个已结束整天的审计事件推送到您指定的 URL，并附带签名以便您验证它来自我们，可用于接入 SIEM 或合规归档。远程备份会把您每日和每周备份的副本发送到您掌控的目的地，可选择不认证、基本认证或 Bearer 令牌。两者都在设置中配置，数据归您保管，与我们保存的备份彼此独立。

沙箱环境

沙箱环境是生产租户的完整克隆，可通过单独的 URL 访问。使用它来测试配置更改、SSO 集成和 Webhook 端点，而不影响正式用户。

沙箱可通过 {slug}-sandbox.authagonal.io 访问。

沙箱环境控制

计费

通过门户的计费页面管理您的订阅和账单。此页面提供当前方案的概览，并提供访问 Stripe 计费门户以管理支付方式、发票和方案变更。

订阅信息

计费页面一目了然地显示您当前的订阅详情。您会看到一个状态标签，指示您的订阅状态——active、trialing、past_due、canceled 或 unpaid——以及您的方案名称、当前计费周期（起止日期），以及您的订阅是否设置在当前周期结束时取消。

管理订阅

点击管理订阅按钮，在新窗口中打开 Stripe 计费门户。在那里您可以更新支付方式、查看和下载发票、更改方案或取消订阅。

如果尚未创建订阅，则会显示设置计费引导操作，指导您选择方案并输入支付信息。

计费页面显示您当前的订阅详情并提供 Stripe 访问入口

自定义域名

通过您自己的域名（例如 auth.yourdomain.com）而非默认的 {slug}.authagonal.io 提供身份验证页面。自定义域名为您的用户提供无缝的品牌化身份验证体验。

添加域名

在添加域名表单中输入您要使用的主机名（例如 auth.yourdomain.com）。添加后，该域名将以 pending_verification 状态显示在您的域名列表中。

DNS 验证

创建一条 CNAME 记录，将您的域名指向 {slug}.authagonal.io。DNS 记录就位后，点击验证以检查 DNS 传播。

auth.yourdomain.com.  CNAME  acme.authagonal.io.

TLS 证书

域名验证通过后，您需要 TLS 证书以便用户可以通过 HTTPS 安全连接。Authagonal 支持两种选项：

自动（cert-manager）——Authagonal 使用 cert-manager 自动配置和续期 TLS 证书。这是大多数用户的推荐选项。无需额外配置。

自带证书（BYO）——以 PEM 格式上传您自己的证书和私钥。如果您的组织要求使用特定证书颁发机构的证书，此选项很有用。系统会跟踪证书到期时间，以便您在过期前续期。

域名状态

每个域名显示一个状态标签，指示其当前状态：pending_verification（DNS 尚未确认）、verified（DNS 已确认，TLS 待配置）、active（完全可用）或 failed（检测到配置问题）。

域名列表显示每个自定义域名及其当前状态

以 PEM 格式上传您自己的 TLS 证书和私钥

电子邮件配置

配置您的租户如何发送事务性电子邮件 —— 验证、密码重置和 MFA 通知。可在默认共享发件人、通过 Resend 验证的自定义域名，或自己的 SMTP 服务器之间进行选择。

本地化邮件

事务性电子邮件以收件人的首选语言发送。验证、密码重置、账户已存在、欢迎、账单和管理员邀请邮件均有七种语言的模板：英语、德语、法语、西班牙语、葡萄牙语、越南语和简体中文。当收件人的语言没有对应模板时，邮件将回退到英语。

语言在发送时根据收件人已存储的偏好来确定。该偏好可来自多个位置：

• 注册和创建账户 —— 取自用户在托管登录界面上所选的语言。
• 门户中的用户页面 —— 由管理员在创建或编辑用户时设置。
• SCIM 配置 —— 当用户通过 SSO 同步时，从 IdP 的 preferredLanguage 映射而来。
• 自助账户页面 —— 由用户本人在 /login/account 上选择。

电子邮件提供商

发件人身份

发件人电子邮件和名称在所有提供商模式中共享。发件人电子邮件为必填；名称为空时将回退到租户名称。

Resend 自定义域名

仅需在 Resend 验证一次您的发送域名，然后即可用作此租户的 From 地址。DNS TXT 记录（SPF、DKIM）由"域名"页面提供；Resend 会自动验证。

自定义 SMTP

使用您自己的 SMTP 服务器 —— 适用于内部中继、Resend 未覆盖的供应商或法规要求固定的场景。

自定义发送域名

使用 Resend 提供商时，您可以注册自己的域名，让电子邮件来自您的品牌（例如 [email protected]），而不是 @authagonal.io。

1. 进入"设置 → 电子邮件"，选择 Resend 自定义域名提供商。
2. 输入您的域名并点击"注册"。
3. 将显示的 DNS 记录（DKIM、SPF 和 return path）添加到您域名的 DNS 中。
4. 点击"检查验证"—— DNS 生效后（通常 1–10 分钟），域名状态将变为已验证。

测试

使用"设置 → 电子邮件"中的"发送测试邮件"按钮验证配置。系统将使用当前保存的设置向您的管理员邮箱发送测试邮件。

审计日志

审计日志提供对租户执行的所有管理操作的只读记录。通过门户或 API 进行的每项更改都会被记录完整的上下文，为合规和故障排除提供完整的追踪记录。

日志列

跟踪的操作

以下管理操作会记录在审计日志中：

审计日志提供所有管理操作的完整记录

备份

Authagonal 每小时自动备份您的租户数据。备份包括所有用户、组、角色、客户端、SSO 连接、SCIM 令牌、品牌信息和设置。您可以在"备份"页面查看备份历史并下载最新的完整备份。

备份工作原理

• 每日运行一次完整备份，捕获租户存储分片中的每个表。
• 增量备份每小时运行一次，仅捕获自上次备份以来发生变化的行。
• 备份存储在 Azure Blob Storage 中，使用与您的租户相同的托管标识。
• 已删除的记录通过 tombstone 跟踪并包含在备份中，以确保审计的完整性。

下载备份

点击"下载最新"以获取 ZIP 文件，其中包含最新的完整备份以及随后合并的所有增量备份。每个表都导出为 JSONL 文件（每行一个 JSON 对象）。

配置应用

预配应用是你自己的服务。每当创建用户时，Authagonal 都会调用它们，让它们可以开通账户、分配许可证、决定该用户属于哪个组织，或者直接拒绝这次注册。

工作原理

创建用户时，Authagonal 会按 TCC（Try/Confirm/Cancel）模式调用你的预配应用的回调 URL。在其中任何一个应用被提交之前，所有应用都必须在 Try 阶段接受，这样多个下游系统可以达成一致，或者由其中一个否决，而不会留下创建了一半的账户。

预配何时运行

每一条创建用户的路径都会运行预配，不只是自助注册。已经完成预配的应用与用户组合会被跳过，因此一个应用对每个用户只会看到一次。

Try 请求

Authagonal 会把这段 JSON POST 到 <code>{callbackUrl}/try</code>。没有值的字段会被省略，而不是以 null 发送。

通过 SSO 到来的用户是最值得提前考虑的常见情况：他们还没有组织，而 federated_connection 会告诉你他们来自你的哪一个客户。

{
  "transactionId": "8f14e45fceea167a5a36dedd4bea2543",
  "userId": "0f6b1c8e-3d2a-4f51-9e77-2c1a4b5d6e7f",
  "email": "[email protected]",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "customAttributes": {
    "federated_connection": "acme-okta"
  }
}

Try 响应

你的应用返回 200 和一个 JSON 主体。这个主体不只是一次确认收到：下游应用正是通过它来分配最终出现在用户令牌上的组织和属性。

{
  "approved": true,
  "organizationId": "org_acme",
  "customAttributes": { "org_role": "member" }
}

为用户打上正确的组织标记

在这里、在同一个地方决定组织，而不是在每条创建路径上各决定一次。SSO 用户会带上 federated_connection，它标识出为其完成认证的连接，因而也标识出客户，并且在同一个客户联合了多个邮箱域名时依然正确。受邀用户没有连接，因此请用你签发的邀请来匹配他们。两条路径都会在用户存在之前到达 /try，因此一段逻辑就能覆盖两者，也不会有两套规则各自漂移。

// POST {callbackUrl}/try
app.post('/provisioning/try', async (req, res) => {
  const { email, customAttributes } = req.body;

  // An SSO user carries the connection that vouched for them. That is the
  // customer, and it stays right when one customer has several domains.
  const connection = customAttributes?.federated_connection;

  const org = connection
    ? await orgByConnection(connection)
    : await orgByPendingInvite(email);

  if (!org) return res.json({ approved: false, reason: 'No organization for this user' });

  // Stamped on the user and emitted as org_id on every token from now on.
  res.json({ approved: true, organizationId: org.id });
});

添加配置应用

要添加配置应用，请提供名称、回调 URL 和可选的API 密钥。API 密钥作为 Bearer 令牌在每个 Webhook 请求的 Authorization 头中发送，允许您的应用验证来自 Authagonal 的请求。

测试

点击任意配置应用旁边的测试，向您的回调 URL 发送测试请求。测试结果显示 HTTP 状态码和响应正文，帮助您验证应用是否正确接收和处理 Webhook。

测试配置应用以验证 Webhook 交付和响应处理

方案限制

每个租户的最大配置应用数量可配置，默认限制为 6 个。如果您的工作流程需要更多配置目标，管理员可以调整此限制。

团队

团队页面管理门户管理员——可以通过管理门户访问和配置您的租户的人员。所有团队成员对租户配置的各个方面拥有完全管理权限。

管理员列表

管理员列表显示每位团队成员的姓名、电子邮箱和添加日期。当前用户行旁边会显示「您」标识，方便您识别自己的账户。

邀请管理员

要邀请新团队成员，请提供其电子邮箱、姓名和临时密码（至少 8 个字符）。受邀用户使用临时密码登录，应在首次登录时更改密码。

邀请字段

管理员邀请将创建一个完全配置的用户——无需邮件往返。

移除管理员

点击任意团队成员旁边的移除以撤销其访问权限。移除确认前会显示确认对话框。您不能移除自己——团队中必须始终至少有一名管理员。

在团队页面管理门户管理员

支持

无需离开门户，即可向 Authagonal 团队提交支持请求。每个请求都是一段连续的对话，从首次反馈到最终解决，您和我们的团队始终保持同步。

您的请求

支持页面会列出您提交的每一个请求，最新动态排在最前。借助状态标识，您可以一眼看出哪些在等您、哪些在等我们。

您的支持请求，含主题、状态、优先级和最近动态

• 每一行显示主题、当前状态（进行中、等待回复、已解决或已关闭）、优先级以及最近动态的时间。
• 点击新建请求即可创建一个，然后填写主题、优先级和您的第一条留言。
• 彩色状态标识让您能轻松扫一眼，找出需要您处理的请求。

请求对话

打开请求即可看到完整对话。回复按顺序显示，我们团队的新消息无需刷新页面即可出现。

您与 Authagonal 团队之间的请求对话

• 您与 Authagonal 团队之间的对话消息按时间先后顺序显示。
• 可在对话中直接回复并附加文件，分享日志、截图或配置。
• 对话实时更新，我们团队一发出回复就会立即显示。
• 如果您改为直接回复通知邮件，您的消息也会自动归入对话。

面向您用户的支持台

除了您从我们这里获得的支持之外，Authagonal 还可以为您的终端用户运行一个支持台。他们在您租户自有品牌主机上的账户页面里提交工单，您的团队则在门户中回复。

它之所以存在，是因为登录不了的人，恰恰就是够不到那些必须登录才能用的支持工具的人。支持台紧挨着登录页面，所以被挡在门外的用户仍有一条路可走，而且每张工单送达时就已经关联到您目录中的真实账户，而不是关联到某人随手填写的地址。

启用它

在门户中打开设置并启用支持门户。在您启用之前，您的用户看不到任何内容。

您的用户看到什么

已登录用户会在您租户主机上的账户页面里看到一块带有您品牌的支持区域。他们可以提交工单、查看自己提交过的全部工单，并在对话中回复。您团队的回复也会通过电子邮件送达，因此用户不必反复回来查看。

启用匿名工单后，登录不了的人仍然可以提交工单。他们留下一个电子邮箱地址和自己的问题描述，随后拿到一个通往该对话的私密链接。这个链接是唯一的入口，因此请把它当作凭据看待：它无法被猜出，而任何持有它的人都可以阅读并回复那一个对话。

客服收件箱

您的团队在门户的支持收件箱中回复。它与您向我们提交的工单是彼此独立的两个地方，并且对 tenant:support 及以上角色开放，因此您可以只把支持台的权限给某位客服人员，而不必把门户的其余部分也交出去。

用户用自己的语言书写

工单按用户书写时使用的语言保存，而对话中的每个人都用自己的语言阅读它。您的客服人员看到的是被翻译成其门户语言的消息，用户看到的是被翻译成其语言的回复，原文始终保留在旁。语言从第一条消息中检测得出，并固定到该工单上。每种语言的译文只计算一次并复用，因此长对话不会反复重新翻译。

时区

工单会记录用户提交时所在的时区。此后每条消息都会在您的时间旁边显示对方的当地时间，于是 14:32 发出的回复，对等待它的人来说会显示为实际的 02:32。当时区未知时，例如通过电子邮件到达的工单，或者时区与您相同时，则不显示任何内容。

Webhook

设置一个支持 Webhook URL，即可在工单事件发生时接收它们，用于触发告警或把工单镜像到您自己的系统中。投递内容带有签名，便于您验证它确实来自我们。

导入与迁移

将现有的身份系统迁移到您的 Authagonal 租户。支持两种来源 —— Duende IdentityServer(一个 SQL Server 数据库)和 Auth0(Management API)。每种来源都会运行只读预览,让您在提交之前准确查看将要复制的内容。

从 Duende IdentityServer 导入

将现有的 Duende IdentityServer SQL Server 数据库中的 Clients、Scopes、用户和角色迁移到您的 Authagonal 租户。导入分为两个阶段 —— 预览和提交 —— 这样您可以在任何更改之前查看将要复制的内容。

导入的内容

导入器从 Duende 的 ConfigurationDb 和 ASP.NET Identity 表中读取数据,将映射的行写入您的租户。短时效资源(如 persisted grants、device codes 和签名密钥)会被跳过。

提交前预览

粘贴您的 Duende ConfigurationDb / IdentityDb 连接字符串,然后点击 运行预览。预览会以只读方式连接并统计将要导入的每一行 —— 不会写入任何数据。

• Clients、Scopes、用户、角色和角色分配的实体计数。
• 当目标租户已存在匹配的 Clients、角色或 Scopes 时发出覆盖警告。
• 对未知表和未映射列的警告,便于您了解哪些数据将被丢弃。

带有计数和警告的预览面板

密码哈希

Duende 使用 ASP.NET Identity V3(PBKDF2)存储密码。Authagonal 的 PasswordHasher 可直接验证该格式,并在首次成功登录时重新哈希为原生格式 —— 用户无需重置流程即可保留现有密码。

用户 ID 协调

如果此租户中已存在的用户与传入记录拥有相同的电子邮件，导入会在导入前将该账户的 userId 轮换为源 sub，这样导入的角色、登录和声明就会附加到现有账户上，而已经通过其源 sub 引用该用户的应用在切换后仍能继续解析。该账户现有的密码和个人资料会被保留；源角色会叠加合并到其上。预览会在您提交之前列出每一个将被协调的账户。

执行导入

在查看预览后,点击 开始导入。提交阶段会将 Clients、Scopes、用户、角色和外部登录引用写入您的租户存储。重复的 clientId、scope name、email 和 role name 会被跳过 —— 导入器可安全重复运行。

不会导入的内容

• Persisted grants、device codes、server-side sessions —— 短时效,自动重新生成。
• 签名密钥 —— Authagonal 为每个租户签发自己的密钥。
• 自定义列和表 —— 任何超出 Duende 标准 schema 的内容都会以警告形式出现,以便您了解数据已被丢弃。
• 已禁用的 Client —— 以禁用状态导入;准备好后可在 Clients 页面重新启用。

从 Auth0 导入

将 Authagonal 连接到您的 Auth0 租户的 Management API,迁移您的应用、API、角色、用户和企业连接。导入的用户和应用 ID 会被保留,因此切换之后现有的 sub 和 client_id 引用仍可正常解析。

您需要准备的内容

在 Auth0 中创建一个授权访问 Management API 的机器到机器(Machine-to-Machine)应用,并授予以下读取 scope:read:users、read:clients、read:resource_servers、read:roles、read:connections、read:client_grants。将其域名、client ID 和 client secret 粘贴到导入表单中 —— 它们仅用于本次导入。

导入的内容

密码

Auth0 的 Management API 从不返回密码哈希。如果您拥有 Auth0 支持团队协助导出的批量密码(NDJSON),请一并提供 —— bcrypt 哈希会原样导入,您的用户无需重置即可保留密码。该文件还包含您的完整用户集合,从而突破 Auth0 API 列表 1,000 个用户的上限。若不提供,用户将以档案形式导入,并在首次登录时设置新密码。

API 参考

每个租户在 https://{slug}.authagonal.io 上暴露一个符合标准的 OIDC 服务器。所有端点遵循 OAuth 2.0 和 OpenID Connect 规范。此参考涵盖您的应用可能需要交互的每个端点。

带 PKCE 的授权码流程

OIDC 发现和 JWKS

发现文档让 OIDC 客户端库可以自动配置自身。这两个端点均不需要身份验证。

GET /.well-known/openid-configuration

返回 OpenID Provider 配置文档。响应包含客户端与此租户交互所需的所有元数据。

GET /.well-known/openid-configuration/jwks

返回用于验证令牌签名的 JSON Web Key Set。响应包含一个 keys 数组，其中每个 RSA 公钥包含 kty、use、kid、alg、n 和 e 字段。

curl https://acme.authagonal.io/.well-known/openid-configuration

授权端点

GET /connect/authorize

发起授权码流程。用户必须有活跃会话，否则将被重定向到登录页面。成功后，用户将携带授权码被重定向回您的应用。

成功响应：302 重定向到 redirect_uri，附带 code 和 state 查询参数。

错误响应：302 重定向，附带 error、error_description 和 state 查询参数。

推送授权请求 (PAR)

RFC 9126。客户端不再把每个授权参数放在 URL 上，而是用普通的客户端认证将它们 POST 到 /connect/par，并取回一个短期的不透明 request_uri。浏览器随后访问 /connect/authorize?client_id=...&request_uri=... — 其它内容不会出现在浏览器历史、服务器日志或 Referer 头中，并且服务器已在客户端认证下完成参数完整性校验。

POST /connect/par

客户端认证与 /connect/token 相同：使用 HTTP Basic 携带 client_id/client_secret，或者通过表单字段提交凭据。公共客户端无需 secret 直接提交。请求体携带的参数与你通常发送给 /connect/authorize 的相同；request_uri 本身会被拒绝（规范 §2.1 禁止链式 PAR）。返回 201 Created。

响应

在后续的 GET /connect/authorize?client_id=…&request_uri=… 调用中，所有其它参数都从已推送的载荷中读取，多余的查询参数会被忽略。授权调用上的 client_id 必须与推送请求时的客户端一致。一旦被消费（或 expires_in 到期），request_uri 会从存储中移除。

# 1. Push parameters (server returns request_uri + expires_in)
curl -X POST https://acme.authagonal.io/connect/par \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "response_type=code" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "scope=openid profile email" \
  -d "state=$(openssl rand -hex 16)" \
  -d "code_challenge=YOUR_CODE_CHALLENGE" \
  -d "code_challenge_method=S256"

# 2. Send the user to /authorize with only client_id + request_uri
# https://acme.authagonal.io/connect/authorize?client_id=my-app&request_uri=urn:ietf:params:oauth:request_uri:abc123...

令牌端点

POST /connect/token

用凭证交换令牌。请求必须使用 Content-Type: application/x-www-form-urlencoded。客户端身份验证可以通过 HTTP Basic auth（Authorization: Basic base64(client_id:client_secret)）或表单正文参数（client_id + client_secret）提供。

授权码授权

刷新令牌授权

客户端凭证授权

设备代码授权

令牌响应：

curl -X POST https://acme.authagonal.io/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "client_id=my-app" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

UserInfo 端点

GET /connect/userinfo

返回已验证用户的声明。需要具有 openid 作用域的有效访问令牌。

curl https://acme.authagonal.io/connect/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

令牌内省（RFC 7662）

POST /connect/introspect

验证令牌并返回其元数据。需要客户端凭证（Basic auth 或表单正文参数）。

活跃令牌响应：

非活跃令牌响应：{ "active": false }

curl -X POST https://acme.authagonal.io/connect/introspect \
  -u "my-app:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_OR_REFRESH_TOKEN"

令牌撤销（RFC 7009）

POST /connect/revocation

撤销先前签发的令牌。需要客户端凭证。

根据 RFC 7009 规范，该端点始终返回 200 OK，即使令牌无效或已被撤销。

设备授权（RFC 8628）

POST /connect/deviceauthorization

为输入受限设备（CLI、智能电视、IoT 设备）发起设备授权流程。设备向用户显示一个代码，用户随后在另一台有浏览器的设备上批准请求。

响应：

批准流程：用户访问 verification_uri，输入 user_code，然后批准请求。同时，设备使用 device_code 轮询令牌端点。

轮询错误代码：

curl -X POST https://acme.authagonal.io/connect/deviceauthorization \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=my-cli" \
  -d "scope=openid profile email"

结束会话 / 注销

GET POST /connect/endsession

注销当前用户会话，触发对所有注册了 BackChannelLogoutUri 的客户端的后通道注销，并撤销所有授权。

如果提供了有效的 post_logout_redirect_uri 且匹配已注册的 URI，用户将收到 302 重定向。否则，将返回 JSON 响应确认会话已结束。

SCIM 2.0 API 参考

Authagonal 支持 SCIM 2.0 协议，用于自动化用户和组的配置。Okta、Azure AD 和 OneLogin 等身份提供商可以使用此 API 将您的 Authagonal 租户与企业目录保持同步。

基础 URL：https://{slug}.authagonal.io/scim/v2

身份验证：所有请求需要 Bearer 令牌。在门户的设置 > SCIM 用户配置中生成 SCIM 令牌。

通用请求头：

列表端点通过 startIndex（从 1 开始）和 count（最大 200）查询参数支持分页，并通过 filter 参数支持筛选（例如 userName eq "[email protected]"）。

用户

GET /scim/v2/Users — 列出用户，支持可选的分页和筛选。

GET /scim/v2/Users/{id} — 通过 Authagonal 用户 ID 获取单个用户。

POST /scim/v2/Users — 创建新用户。返回 201 Created。

PUT /scim/v2/Users/{id} — 完全替换用户资源。必须提供所有字段。

PATCH /scim/v2/Users/{id} — 使用 SCIM PatchOp 进行部分更新。

DELETE /scim/v2/Users/{id} — 软删除用户（停用账户并撤销所有令牌）。返回 204 No Content。

curl -X POST https://acme.authagonal.io/scim/v2/Users \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "[email protected]",
    "name": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "displayName": "Jane Smith",
    "active": true,
    "externalId": "ext-12345"
  }'

组

GET /scim/v2/Groups — 列出所有组，支持可选的分页和筛选。

GET /scim/v2/Groups/{id} — 通过 ID 获取单个组，包括其成员列表。

POST /scim/v2/Groups — 创建新组。返回 201 Created。

PUT /scim/v2/Groups/{id} — 完全替换组资源（包括其成员列表）。

PATCH /scim/v2/Groups/{id} — 用于添加或移除组成员的部分更新。

DELETE /scim/v2/Groups/{id} — 硬删除组。返回 204 No Content。

curl -X PATCH https://acme.authagonal.io/scim/v2/Groups/GROUP_ID \
  -H "Authorization: Bearer SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "add",
        "path": "members",
        "value": [
          { "value": "USER_ID_1" },
          { "value": "USER_ID_2" }
        ]
      }
    ]
  }'

Portal API（自动化）

Portal API 让您自己的后端能够自动化您在门户中所能执行的一切操作——管理用户、客户端、组、角色、作用域、SSO 连接和设置——通过一种机器对机器（M2M）凭据完成。它与门户 UI 调用的是同一套 API。

基础 URL：https://portal-api.<your-domain>/api/v1。请求通过 Bearer 访问令牌进行身份验证；租户取自令牌，而非 URL。

创建 API 凭据

在门户中，打开 Clients → Create API credential，选择一个访问级别并为其命名。Authagonal 会生成一个为 Portal API 配置好的 OAuth client_credentials 客户端，并返回 Client ID 和密钥。

访问级别

获取令牌

在您的管理租户令牌端点——https://<your-tenant>.<your-domain>/connect/token——用该凭据换取访问令牌，然后将令牌作为 Bearer 请求头发送给 Portal API。令牌有效期为一小时。

# 1. Exchange the credential for an access token (your tenant's token endpoint)
curl -X POST https://acme.authagonal.io/connect/token \
  -d grant_type=client_credentials \
  -d client_id=api-3f2a... \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope=tenant:admin

# Response: { "access_token": "ey...", "token_type": "Bearer", "expires_in": 3600 }

# 2. Call the Portal API with the access token
curl https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN"

端点

所有路径均相对于基础 URL,并需要 Bearer 访问令牌。每个分组旁的作用域是该凭据所需的最低访问级别。列表端点接受 startIndex 和 count 查询参数。

GET/api/v1/clients— 列出 OAuth 客户端。

GET/api/v1/clients/{id}— 按 ID 获取单个客户端。

POST/api/v1/clients— 创建客户端。返回客户端 ID;对于机密客户端,还会返回一次性密钥。

PUT/api/v1/clients/{id}— 更新客户端(重定向 URI、授权类型、令牌有效期、PKCE/PAR 要求)。

DELETE/api/v1/clients/{id}— 删除客户端。

POST/api/v1/clients/api-credential— 创建机器对机器的 Portal API 凭据。

GET/api/v1/users— 列出用户。支持 count、search（邮箱或姓名前缀）、organizationId（筛选出单个组织）以及 after（游标分页）。

GET/api/v1/users/count— 租户的用户总数。

GET/api/v1/users/stats/mfa— MFA 注册统计。

GET/api/v1/users/{id}— 获取单个用户。

POST/api/v1/users— 使用邮箱和密码创建用户。

PUT/api/v1/users/{id}— 更新用户（资料、邮箱、启用/封禁状态、organizationId）。

DELETE/api/v1/users/{id}— 删除用户。

GET/api/v1/users/{id}/mfa— Get a user's enrolled MFA methods.

DELETE/api/v1/users/{id}/mfa— Reset a user's MFA enrollment.

GET/api/v1/roles— 列出角色。

POST/api/v1/roles— 创建角色。

DELETE/api/v1/roles/{id}— 删除角色。

POST/api/v1/roles/assign— 为用户分配角色。

POST/api/v1/roles/unassign— 移除用户的角色。

GET/api/v1/groups— 列出组。

GET/api/v1/groups/{id}— 获取组及其成员。

POST/api/v1/groups— 创建组。

POST/api/v1/groups/{id}/members— 向组中添加成员。

DELETE/api/v1/groups/{groupId}/members/{userId}— 从组中移除成员。

DELETE/api/v1/groups/{id}— 删除组。

GET/api/v1/group-role-mappings— 列出组到角色的映射(根据组成员身份在签发令牌时授予的角色)。

GET/api/v1/scopes— 列出 API 作用域。

POST/api/v1/scopes— 创建作用域。

DELETE/api/v1/scopes/{name}— 删除作用域。

GET/api/v1/saml/connections— 列出 SAML 连接。

POST/api/v1/saml/connections— 创建 SAML 连接。

DELETE/api/v1/saml/connections/{id}— 删除 SAML 连接。

GET/api/v1/oidc/connections— 列出 OIDC 连接。

POST/api/v1/oidc/connections— 创建 OIDC 连接。

DELETE/api/v1/oidc/connections/{id}— 删除 OIDC 连接。

GET/api/v1/sso/domains— 列出路由到 SSO 连接的域名(home-realm 发现)。

GET/api/v1/branding— 获取租户品牌设置(颜色、logo、支持的语言)。

PUT/api/v1/branding— 更新租户品牌设置。

GET/api/v1/settings— 获取租户设置(webhook、公开注册、令牌策略)。

PUT/api/v1/settings— 更新租户设置。

POST/api/v1/settings/webhook-secret/regenerate— 轮换 webhook 签名密钥。

POST/api/v1/settings/test-email— 使用当前邮件配置发送测试邮件。

GET/api/v1/custom-domains— 列出自定义登录域名及其验证状态。

POST/api/v1/custom-domains— 添加自定义域名。

POST/api/v1/custom-domains/{domain}/verify— 为自定义域名触发 DNS 验证。

DELETE/api/v1/custom-domains/{domain}— 移除自定义域名。

GET/api/v1/email/domains— 列出发件人邮件域名。

GET/api/v1/audit— 查询租户审计日志。

示例:创建用户

curl -X POST https://portal-api.authagonal.io/api/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "S3cure-temp-passw0rd",
    "firstName": "Ada",
    "lastName": "Lovelace"
  }'

# 200 OK
# { "userId": "8f3a...", "email": "[email protected]" }

登录页面

这些是您的终端用户在您租户的认证服务器上看到的托管页面。Authagonal 提供每一个开箱即用的页面，让您无需构建任何 UI 即可获得完整、安全的登录体验。本页将逐一介绍每个页面，并说明哪些门户设置可以控制它。

登录

• 邮箱优先的两步式流程：用户先输入邮箱并点击继续，然后出现密码输入框。
• 当存在 SSO 连接时，「使用 {provider} 继续」单点登录按钮会自动出现。
• 忘记密码和创建账户链接，二者均可显示或隐藏。
• 可选的 Cloudflare Turnstile 人机验证，用于阻止自动化登录尝试。

在门户管理后台中控制

• 品牌设置用于设定 Logo、配色、应用名称、支持邮箱和自定义 CSS。
• 显示或隐藏忘记密码和注册链接（品牌设置）。
• SSO 连接会添加社交登录按钮（SSO 页面）。
• 会话有效期和锁定阈值（设置 → 安全）。

注册

• 收集名字和姓氏（可选）、邮箱以及密码。
• 实时密码策略清单会随用户输入而更新，让要求在提交前一目了然。
• 可选的 Cloudflare Turnstile 人机验证。
• 为已有账户的用户提供「登录」链接。

在门户管理后台中控制

• 显示或隐藏注册链接（品牌设置）。
• 您租户的密码策略决定了清单内容。
• 品牌设置为整个页面设定样式。

忘记密码

• 用户输入邮箱后，会看到一条中性的「请查收邮件」确认提示。
• 该页面绝不透露账户是否存在，从而挫败账户枚举探测。
• 「返回登录」链接可将用户带回登录页面。

在门户管理后台中控制

• 显示或隐藏忘记密码链接（品牌设置）。
• 您租户的邮件投递负责发送重置邮件。
• 品牌设置为整个页面设定样式。

重置密码

• 新密码和确认密码输入框，配有逐条规则的实时要求清单。
• 当重置令牌不再有效时，会显示清晰的链接无效或已过期状态。
• 确认密码已更改的成功状态。

在门户管理后台中控制

• 您租户的密码策略决定了清单内容。
• 品牌设置为整个页面设定样式。

MFA 验证

• 在身份验证器应用、通行密钥和恢复码之间切换的方式切换器。
• 6 位 TOTP 输入框，所有数字输入完毕后自动提交。
• 为丢失身份验证器访问权限的用户提供恢复码输入。
• 用于硬件支持验证的通行密钥按钮。

在门户管理后台中控制

• MFA 策略按应用设置（客户端 → 安全）。
• 任何已注册验证因素的用户都会始终被要求验证，无论策略如何。

MFA 设置

• 显示已注册方式的状态，让用户知道哪些已经配置好。
• 通过二维码、手动密钥备用方案和确认步骤完成身份验证器设置。
• 用于硬件支持认证的通行密钥注册。
• 用于账户恢复的恢复码生成。
• 当 MFA 为自助而非强制时，提供可选的跳过。

在门户管理后台中控制

• MFA 策略按应用设置；强制会在登录时强制完成设置（客户端 → 安全）。
• 品牌设置为整个页面设定样式。

设备授权

• 居中的用户代码输入框，用于输入设备上显示的代码。
• 授权该设备的批准步骤。
• 当用户尚未认证时显示的登录过渡页。
• 设备授权完成后的已批准确认。

在门户管理后台中控制

• 在应用上启用设备代码授权（客户端 → 授权类型）。
• 设置设备代码有效期（客户端 → 令牌）。

授权同意

• 显示发起请求的客户端 Logo 和名称。
• 逐项权限列表，为每项权限配有友好、易读的标签。
• 用于授予或拒绝访问的允许和拒绝按钮。
• 解释该决定含义的授权提示页脚。

在门户管理后台中控制

• 按应用开启要求授权同意（客户端 → 安全）。
• Logo、名称和 URL来自应用自身的元数据。
• 品牌设置渲染授权同意卡片。

已连接应用（授权）

• 列出用户已授权的每个应用，含其名称、权限范围和授权日期。
• 撤销对某个应用的访问权限，生效前会有确认步骤。
• 当用户尚未授权任何应用时，显示友好的空状态。

在门户管理后台中控制

• 该列表由需要授权同意的应用填充。
• 品牌设置为整个页面设定样式。

账户

位于 /login/account 的托管自助账户页面，已登录用户可在此管理自己的个人资料和首选语言，无需门户访问权限。

• 编辑名字和姓氏、公司和电话；电子邮件地址以只读方式显示。
• 从受支持的语言中选择首选语言；界面会即时预览所选语言，并在保存时保留该选择。
• 已保存的语言决定用户的托管界面以及他们所收到的事务性电子邮件的语言。

在门户管理后台中控制

• 品牌设置为整个页面设定样式。
• 管理员也可在门户的用户页面上编辑同一个首选语言。

身份验证流程

身份验证流程涵盖终端用户如何与您的 Authagonal 租户交互——登录、注册、重置密码和设置 MFA。这些端点由托管登录页面使用，如果您正在构建自定义登录 UI，也可以直接调用。

登录

POST /api/auth/login

使用电子邮箱和密码验证用户身份。成功后，签发会话 Cookie 并返回用户配置文件。如果配置了 MFA，响应会指示在会话完全建立之前需要第二因素。

请求正文：

{
  "email": "[email protected]",
  "password": "correct-horse-battery-staple"
}

成功响应：

MFA 必需响应：当用户已注册 MFA 时，响应包含 mfaRequired: true 以及 challengeId 和列出可用 MFA 方法的 methods 数组。

MFA 设置必需响应：当租户要求 MFA 但用户尚未注册时，响应包含 mfaSetupRequired: true 和用于注册流程的 setupToken。

错误响应：

SSO 检查：如果用户的电子邮箱域名配置了 SSO 连接，登录端点将返回 sso_required 和 redirectUrl。客户端应将用户重定向到 SSO 提供商。

账户锁定：连续 maxFailedAttempts 次登录失败后，账户将被锁定 lockoutDurationMinutes。这两个值均可在租户设置中配置。

注册

POST /api/auth/register

创建新用户账户。验证邮件会自动发送——用户必须在登录前验证其电子邮箱。

请求正文：

{
  "email": "[email protected]",
  "password": "a-strong-password-here",
  "firstName": "Jane",
  "lastName": "Smith"
}

成功：201 Created，返回新账户的 userId。使用已注册的邮箱注册同样返回 201：我们绝不透露某个邮箱是否已存在（以防止账户枚举），而是改为通过邮件通知真正的账户持有者。

错误响应：

密码重置

POST /api/auth/forgot-password

请求密码重置邮件。无论电子邮箱是否存在，端点始终返回成功响应，以防止电子邮箱枚举。

{
  "email": "[email protected]"
}

POST /api/auth/reset-password

使用邮件链接中的令牌重置用户密码。

{
  "token": "RESET_TOKEN_FROM_EMAIL",
  "newPassword": "new-strong-password"
}

成功密码重置的副作用：

• 失败登录尝试计数器重置为零
• 所有现有刷新令牌被撤销
• 生成新的安全戳（使所有现有会话失效）

MFA 设置与验证

Authagonal 支持三种 MFA 方法：TOTP（身份验证器应用）、WebAuthn（安全密钥和生物识别）和一次性恢复代码。

TOTP 设置

POST /api/auth/mfa/totp/setup — 返回 QR 码数据 URI 和手动输入密钥。用户使用身份验证器应用（Google Authenticator、Authy、1Password 等）扫描 QR 码，然后确认注册。

POST /api/auth/mfa/totp/confirm — 通过验证身份验证器应用中的 6 位数代码来确认 TOTP 注册。

{
  "code": "123456"
}

WebAuthn 设置

POST /api/auth/mfa/webauthn/setup——返回 WebAuthn API 的凭证创建选项。浏览器使用这些选项调用 navigator.credentials.create()。

POST /api/auth/mfa/webauthn/confirm — 通过提交浏览器的证明响应来确认 WebAuthn 注册。

恢复代码

POST /api/auth/mfa/recovery/generate — 生成 10 个一次性 8 字符恢复代码。每个代码只能使用一次以绕过 MFA。

MFA 验证

POST /api/auth/mfa/verify — 在成功密码登录后完成 MFA 挑战。

MFA 状态

GET /api/auth/mfa/status — 返回用户当前已注册的 MFA 方法。

SSO 登录流程

Authagonal 支持 SAML 2.0 和基于 OIDC 的 SSO 连接。基于域的路由根据用户的电子邮箱地址自动检测使用哪个 SSO 提供商。

SSO 检查

GET /api/auth/[email protected]

SAML 流程

用户被重定向到 GET /saml/{connectionId}/login，该端点向身份提供商发送 SAML AuthnRequest。身份提供商验证用户身份后将 SAML 响应发回 Assertion Consumer Service (ACS) 端点。Authagonal 验证断言、创建或更新用户并签发会话 Cookie。

用于配置身份提供商的 SAML 元数据可在 GET /saml/{connectionId}/metadata 获取。

OIDC 流程

用户被重定向到 GET /oidc/{connectionId}/login，该端点使用 PKCE 重定向到上游身份提供商。用户完成身份验证后，回调端点 /oidc/callback 交换授权码、验证 ID 令牌并创建或更新用户。

JIT 配置：SAML 和 OIDC 流程均支持即时配置。如果用户在租户中不存在，将根据身份提供商的声明自动创建。如果用户已存在，其配置文件属性将更新为与提供商的最新值匹配。

Backend-for-Frontend（BFF）

BFF 让 OAuth 令牌完全不进入浏览器。您的单页应用只持有一个 httpOnly 会话 Cookie，由您自己后端上的机密客户端完成 OpenID Connect 流程，并在服务端持有令牌。

单页应用能读到的任何东西，跨站脚本都能偷走，其中就包括内存里的访问令牌和 localStorage 里的刷新令牌。把令牌存在浏览器中还会压低它们的有效期，因为脚本触手可及的长期刷新令牌始终是一项悬着的风险。IETF 的 OAuth 2.0 for Browser-Based Apps 当前最佳实践，正是出于这个原因推荐这一模式。

作为交换，您得到的是：一个不出现任何令牌、却能跨页面刷新继续存在的会话；由服务端替您完成的令牌刷新；通过后通道注销实现的即时撤销；以及一个已认证的代理，让您的 API 永远不必解析一个浏览器有可能篡改过的令牌。

创建客户端

在门户中打开客户端，选择创建 BFF 应用。填入您的应用对外提供服务的基础 URL，例如 https://app.acme.com，Authagonal 会为您注册一个配置正确的机密客户端，而不是把拼装的活儿丢给您：

接入您的后端

支持两种运行时，行为完全一致：面向 .NET 的 Authagonal.Bff 和面向 Node 的 @authagonal/bff，后者带有 Express 和 Next.js 适配器。把其中任意一个指向门户刚刚给出的那些值即可。

// dotnet add package Authagonal.Bff
builder.Services.AddAuthagonalBff(o =>
{
    o.Authority    = "https://acme.authagonal.io";       // your tenant auth host
    o.ClientId     = builder.Configuration["Bff:ClientId"]!;
    o.ClientSecret = builder.Configuration["Bff:ClientSecret"]!;
    o.Scope        = ["openid", "profile", "email", "offline_access"];
    o.PostLogoutRedirectUri = "https://app.acme.com/";
});

var app = builder.Build();

app.UseForwardedHeaders();   // required behind a proxy or ingress, see the note below
app.MapAuthagonalBff();
app.MapFallbackToFile("index.html");   // your SPA
app.Run();

// npm install @authagonal/bff
import express from 'express';
import { authagonalBff } from '@authagonal/bff/express';

const app = express();

app.use(authagonalBff({
  authority: 'https://acme.authagonal.io',
  clientId: process.env.BFF_CLIENT_ID,
  clientSecret: process.env.BFF_CLIENT_SECRET,
  scope: ['openid', 'profile', 'email', 'offline_access'],
  postLogoutRedirectUri: 'https://app.acme.com/',
}));

app.listen(8080);

端点

默认挂载在 /bff 之下。它们必须由与您 SPA 相同的来源提供服务，因为会话 Cookie 是 httpOnly 且同源的：请把它们放在同一个主机名之下，而不是放在单独的 API 域名上。

在浏览器中调用

每个非导航请求都必须携带一个固定的防伪标头。它与 Cookie 的 SameSite 属性一起防御跨站请求伪造：跨站的表单提交无法设置自定义标头，因此缺少该标头的请求会被拒绝。

const me = await fetch('/bff/user', {
  headers: { 'X-Authagonal-Bff': '1' },
}).then(r => r.json());

if (!me.isAuthenticated) {
  // Navigate, do not fetch: this is a redirect to your identity provider.
  window.location.href = '/bff/login?returnUrl=' + encodeURIComponent(location.pathname);
}

登录和注销请通过页面导航完成，而不是 fetch：location.href = '/bff/login'。这些路由返回的是跳转到您身份提供商的重定向，而这样的重定向链并不是 fetch 能够有效跟随的。

调用您的 API

BFF 可以在自己的基础路径下转发您的 API，并在转发途中附上会话的访问令牌。浏览器发送的是 Cookie，您的 API 收到的是一个按常规校验的 Bearer 令牌，而该令牌的任何部分对页面既不可见，也无法伪造。注册一个上游后，发往 /bff/api/** 的请求就会以已认证的身份到达它。把列表留空，代理则被完全禁用。

o.Upstreams.Add(new BffUpstream
{
    Prefix        = "/orders",                        // matches /bff/api/orders/**
    TargetBaseUrl = "https://api.internal.acme.com",
    StripPrefix   = false,                            // keep /orders in the forwarded path
});

WebSocket

WebSocket 握手既无法携带自定义标头，也无法携带 Bearer 令牌，因此防伪标头和代理在这里都帮不上忙。启用票据后，SPA 就可以调用 GET /bff/ws-ticket，把这个短时效的一次性票据放到连接 URL 上，再由您的 API 去兑换。请在每次连接之前才签发一个：它在首次使用后即被删除，并在数秒内过期。

有意把令牌交给浏览器

BFF 的全部意义就在于浏览器不持有任何令牌，因此这项能力需要主动开启，适用面也很窄。它只为 Cookie 模型够不到的那一种情况而存在：位于另一个来源的资源服务器，例如您嵌入在 iframe 中的应用，必须用 Bearer 令牌来调用。启用后，GET /bff/token?resource=… 会返回一个交换得到的令牌：会话的令牌被降权到某一个白名单资源，并绑定到任何白名单上下文参数。浏览器永远看不到会话自身的令牌，而它拿到的那个令牌时效很短，且只面向单一受众。指定了白名单之外资源的请求会被拒绝，正是这一点让它不会变成一台通用的令牌铸造机。

用一个 BFF 服务多个租户

设置一个租户查询参数，一套部署就能服务众多租户：/bff/login?slug=acme 选定租户，解析器提供该租户的 authority 和客户端凭据，这个键随关联 Cookie 一路进入会话，后通道注销则从令牌的签发者解析出租户。默认解析器让单租户行为保持逐字节一致，因此只要您不使用这项功能，就不必为它付出任何代价。

值得了解的选项

完整清单。Node 包以驼峰形式镜像这些选项，因此 BasePath 对应 basePath，其余同理。

用 AI 助手来操作您的门户

把 AI 助手连到您的租户，然后让它去做那些您原本要一路点击才能完成的事：找出一个登录不了的用户，查看他们是否还有第二验证因素，邀请某个人，看看谁持有管理员角色。

这是一次普通的 OAuth 连接，而不是一把 API 密钥。每个人都以自己的身份登录并批准该访问，因此助手能做的恰好是那个人在门户中能做的事，不会更多。不会新建任何可能泄露的东西，撤销某一个助手也不会影响其他任何人。

启用它

打开设置并启用 AI 助手访问。在您启用之前它是关闭的，而在关闭期间，该端点并不存在，而不只是拒绝请求。启用之后，面板会显示要粘贴到您的 AI 客户端里的 URL：

https://portal-api.authagonal.io/api/v1/mcp/{your-tenant}

助手能做什么

恰好是连接它的那个人能做的事，按每次调用依据那个人自己的令牌来判定。tenant:support 坐席拿到的是诊断类和日常类工具；管理员工具不只是对他们隐藏起来，而是即便直接点名调用也会被拒绝。门户里受限的事情在这里同样受限：修改用户的电子邮箱地址在那里需要管理员角色，在这里也需要。

因为这是一份普通的授权，您就按普通方式管理它。撤销它，助手会立即停止工作，而不是等到令牌下次过期。助手做的每一件事都会以它所代表的那个人的名义写进您的审计日志，因此这条线索还是您一直在看的那一条。

这些工具

本次发布共二十个。由您的 AI 客户端决定启用哪些，因此如果您只想让助手做读取，就可以只把读取类工具交给它。

目前还没有包含的内容

删除用户、创建或编辑 SSO 连接、计费、备份和客户端密钥在本次发布中都没有。删除属于您的数据擦除队列，而不是摆在它旁边；SSO 连接的影响面大到一次改错就会把整支员工队伍挡在门外，所以它们目前是只读的；而一个会返回客户端密钥的工具，等于把密钥留在助手的对话记录里。请告诉我们您想要其中哪些，以及按什么顺序。

MCP 服务器身份验证

如果您对外提供 Model Context Protocol 服务器，Authagonal 可以充当它背后的授权服务器。AI 助手发起连接，它背后的人登录并授予访问权限，您的服务器则收到一个普通的 bearer 令牌，像验证任何其他 API 一样验证它。

另一种做法是把 API 密钥粘贴进助手的配置里，那是一份背后没有用户的凭据，没有有效期，没有同意步骤，也没有办法在不为所有人轮换密钥的前提下撤销某一个连接器。改用 OAuth 意味着这份授权属于一个具名的人，会出现在您的审计日志里，并且可以在门户中撤销，而不必动其他任何东西。

连接是怎么建立的

整个交换过程都由发现机制驱动，因此符合规范的客户端除了您服务器的 URL 之外不需要配置任何东西。

这个顺序里没有一步是 Authagonal 特有的：它就是 MCP 授权规范，建立在 RFC 9728（资源元数据）、RFC 8414（发现授权服务器）、RFC 7591（注册）和 RFC 8707（指明资源）之上。遵循该规范的连接器无需为我们做特殊处理就能工作。

让连接器自行注册

您从未打过交道的连接器无法使用您手工创建的客户端，因此它会在运行时注册一个。该功能默认关闭。在设置中打开动态客户端注册，注册端点就会出现在您的发现文档里；保持关闭，该端点就不会被公布，并且会拒绝请求。启用它只为您自己的租户打开注册，绝不会为别人的租户打开。

您的 MCP 服务器要实现什么

两件小事，之后它就是一台普通的资源服务器。第一，发布受保护资源元数据，指明您的租户是授权服务器。把它放在 well-known 路径上提供；如果您的 MCP 端点位于子路径上，也要在带路径后缀的形式上提供，因为客户端两种都会试。

GET https://your-app.example/.well-known/oauth-protected-resource

{
  "resource": "https://your-app.example/mcp",
  "authorization_servers": ["https://acme.authagonal.io"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp"]
}

第二，当一次调用没有带有效令牌时，返回 401 并附上指向那份元数据的 WWW-Authenticate 头。正是这个头把一次拒绝变成一次连接：没有它，客户端就无从发现该去哪里认证，只会直接失败。

// Validate the connector's token like any other resource server.
builder.Services.AddAuthentication().AddJwtBearer("McpBearer", o =>
{
    o.Authority = "https://acme.authagonal.io";              // your tenant
    o.TokenValidationParameters.ValidAudience = "https://your-app.example/mcp";
});

// Unauthenticated? Point the connector at the metadata rather than just refusing.
http.Response.Headers.WWWAuthenticate =
    "Bearer resource_metadata=\"https://your-app.example/.well-known/oauth-protected-resource\"";
return Results.Unauthorized();

作用域、方案与撤销

为您的 MCP 接口定义一个作用域，把它加入允许注册的作用域，它就会出现在授权同意屏幕上，让用户看到自己在批准什么。令牌携带用户的角色以及您配置的任何声明，因此您的服务器可以决定这个具体的人能做什么，而不是把每个连接器都一视同仁。

因为这是一份普通的 OAuth 授权，撤销也就按普通方式进行：找到该用户，撤销他们的会话或那份授权，连接器会立即停止工作，而不是等到令牌下次过期。审计日志会记录注册、同意和签发，因此您可以看到是哪个助手在什么时候请求了什么。

构建自定义登录界面

用您自己的界面替换 Authagonal 托管的登录、注册、密码重置和 MFA 界面，同时让 Authagonal 继续处理身份验证、MFA、SSO、会话和令牌签发。有两种方式：使用我们的 React 组件库，或从任意框架直接调用认证 API。此功能需主动启用——请先在租户设置中启用自定义登录界面。

前提条件：在您的根域名上启用自定义域名

登录会话是第一方 Cookie，因此您的界面与 Authagonal 认证服务器必须共享同一个可注册域名。请在与您应用运行所用的相同根域名下，将一个自定义认证域名指向 Authagonal——例如认证位于 login.acme.com，应用位于 app.acme.com。在存在已启用的自定义域名之前，自定义登录界面设置将保持禁用状态。

此外，请将您界面的来源（例如 https://app.acme.com）添加到您 OAuth 客户端的允许的 CORS 来源中——与您为令牌交换设置的列表相同。

React：@authagonal/login

npm i @authagonal/login 将认证逻辑和界面作为同一个包提供——与 Authagonal 托管登录所基于的包相同。选择适合您的层级：

• 完整应用——直接引入 App 并通过品牌设置为其设定主题。
• 组合页面——在您自己的布局中使用 LoginPage、MfaChallengePage、ResetPasswordPage…
• 基础组件 + 逻辑——使用 AuthLayout/Button/Input 和 API 客户端（login、mfaVerify、forgotPassword…）构建您自己的界面。

import { AuthLayout, Input, Button, login, ApiRequestError } from '@authagonal/login';

function MyLogin() {
  async function onSubmit(email: string, password: string) {
    try {
      const res = await login({ email, password });        // POST /login (sets the session cookie)
      if (res.mfaRequired) {/* render your MFA step → mfaVerify(...) */}
      else window.location.href = res.returnUrl;            // hand off to /connect/authorize
    } catch (e) {
      if (e instanceof ApiRequestError) {/* show e.message */}
    }
  }
  return <AuthLayout>{/* your own markup + <Input/> <Button/> */}</AuthLayout>;
}

任意框架：调用认证 API

不使用 React？可直接调用认证流程端点（位于 /api/auth 下），然后移交给标准的 OIDC /connect/authorize 流程。请发送 credentials: 'include' 以便存储会话 Cookie。

# 1. Authenticate (browser fetch — credentials:'include' so the session cookie is stored)
curl -i -X POST https://login.acme.com/api/auth/login \
  -H "Content-Type: application/json" \
  -H "Origin: https://app.acme.com" \
  --data '{"email":"[email protected]","password":"..."}'
# (handle {"mfaRequired":true} → POST /api/auth/mfa/verify, then continue)

# 2. Hand off to the OAuth flow — top-level navigation to the authorize endpoint with PKCE:
# https://login.acme.com/connect/authorize?client_id=my-app&redirect_uri=...&response_type=code
#   &scope=openid%20profile%20email&code_challenge=...&code_challenge_method=S256
# The session cookie (same-site) authenticates the user; you get back a code → exchange at /connect/token.

方案与限额

Authagonal 提供四个方案级别。所有方案包含所有功能——唯一的区别是月活跃用户（MAU）限额和超额定价。

方案级别

月活跃用户（MAU）

月活跃用户是在计费月内至少成功完成一次身份验证的唯一用户。通过 SCIM 配置但尚未登录的用户不计入您的 MAU 总数。

超额——如果您的方案支持超额，超出 MAU 限额的用户将按上方方案表中显示的每用户费率计费。您可以设置超额上限以限制计费周期的最大支出。

强制执行——如果您的方案不支持超额（入门版），超出 MAU 限额的用户在下一个计费周期或您升级到支持超额的方案之前无法登录。