← 开发者 API 为开发者

使用 Astrina 登录

Astrina is the single sign-on broker for the ecosystem. Configure your social-login providers once in Astrina; every site reuses them — no per-site OAuth apps, no provider SDKs.

下载 sdk.php 认证 API

流程如何运作

四次跳转，您的网站从未接触过提供商

网站将访客发送到Astrina

一个链接，包含您的client_id、返回地址和状态值。

访客选择一个账户

在Astrina中启用的任何提供商 — 您这边无需OAuth应用。

Astrina返回一次性代码

代码返回到您的回调，并在五分钟内过期。

您的服务器将其交换为一个配置文件

服务器到服务器的POST返回sub、电子邮件、姓名和头像。

显示请求图

  Site  ──(1) redirect──▶  astrina.io/auth/authorize.php  ──▶  provider (Google…)
   ▲                                    │                              │
   └──(3) ?code=…&state=… ◀──── astrina.io/auth/cb.php ◀──(2) callback ─┘
   │
   └──(4) POST code ──▶ astrina.io/auth/token.php ──▶ { sub, email, name, avatar }

一次性所有者设置 (在 Astrina 管理员中)

在控制面板中启用提供者（所有者访问）。
对于每个提供者，在该提供者的控制台中创建一个 OAuth 应用并注册 exactly 这个重定向 URI：
Googlehttps://astrina.io/auth/cb.php?provider=google
Yandexhttps://astrina.io/auth/cb.php?provider=yandex
Applehttps://astrina.io/auth/cb.php?provider=apple
Telegram@BotFather → /setdomain → astrina.io
粘贴每个应用的 Client ID + Secret (Telegram: bot username + bot token)，勾选 Enabled，保存。
在 Client sites 下，注册每个网站（名称 + 允许的重定向 URL）。复制显示的 client_id + client_secret，仅显示 once。

每个网站的集成 (3 步骤)

将 sdk.php 复制到网站并设置四个常量：

define('ASTRINA_CLIENT_ID',     'astr_xxxxxxxx');
define('ASTRINA_CLIENT_SECRET', '…');   // server-side only, never in JS
define('ASTRINA_REDIRECT_URI',  'https://mysite/auth/astrina-callback.php');
require '/path/to/sdk.php';

在任何地方添加按钮 — 一个 "使用 Astrina 登录" 按钮（显示选择器），或一排 direct provider buttons（点击 Google 直接进入 Google，无需选择页面）：

<!-- one button → Astrina chooser -->
<a class="btn" href="<?= htmlspecialchars(AstrinaID::loginUrl()) ?>">Log in with Astrina</a>

<!-- OR: direct per-provider buttons + the "Secured by Astrina ID" note -->
<?= AstrinaID::buttonsHtml() ?>

<!-- OR: hand-rolled, straight to one provider -->
<a href="<?= htmlspecialchars(AstrinaID::loginUrl('google')) ?>">Continue with Google</a>

buttonsHtml() 获取您在 Astrina 中启用的提供者，并准确渲染这些，每个都深度链接到提供者。

在重定向 URL 创建回调页面 (astrina-callback.php)：

require 'config.php';           // defines the constants + sdk.php
$u = AstrinaID::handleCallback();
if (!$u) { header('Location: /login?e=1'); exit; }
// key your local user on ($u['provider'], $u['sub']) — NOT email
$local = find_or_create_user($u['provider'], $u['sub'], $u['email'], $u['name'], $u['avatar']);
login($local); header('Location: /'); exit;

就是这样 — 无需每个网站的 OAuth 应用，无需提供者 SDK。稍后添加新提供者只需在 Astrina 中更改一行；每个网站都会自动获取。

备注

sub 是一个稳定、不透明的每个身份的 ID。将电子邮件视为信息（Telegram 不提供；用户可以更改）。

如果您更愿意本地验证而不是信任 JSON，令牌响应还携带一个 id_token（JWT HS256 使用 your 客户端密钥签名）。

代码是一次性使用的，并在 5 分钟内过期；state 由 SDK 和 Astrina 进行检查。

纯文本参考： README.md · 下载 sdk.php