aproto OAuth 浏览器客户端
此软件包提供了浏览器特定的 OAuth 客户端执行 阿特罗多。 它执行所有 OAuth 特性 意大利 (PKCE、DPoP、, 页:1.
@atproto/oauth-client-browser 是为做前端应用程序设计的
没有后端服务器来管理 OAuth 会话, a. k. a" Single Page
应用程序" (SPA).
[大
当后端服务器可用时,建议使用
@atproto/oauth-client-node从服务器端管理 OAuth 会话并使用会话 cookie来映射 oAuth 会话到前端。 因为这个机制允许后端 要在比例上取消 OAuth 证书,此方法比 从前端直接管理 OAuth 会话。 感谢添加的 安全, OAuth 服务器在给 BFF(后端为前端).
设置
客户身份
这个 client_id 用于识别您在 OAuth 服务器上的应用程序 。 没错
用于获取客户端元数据并启动 OAuth 流量。 这个
client_id 必须是指向 客户端
元数据。 。 。 .
客户端元数据
您的 OAuth 客户端元数据应当以对应的 URL 运行
client_id 您的申请。 此 URL 应返回 JSON 对象与
客户端元数据。 客户端元数据应当按照
请务必尊重 意大利 谱.
{
// Must be the same URL as the one used to obtain this JSON object
"client_id": "https://my-app.com/client-metadata.json",
"client_name": "My App",
"client_uri": "https://my-app.com",
"logo_uri": "https://my-app.com/logo.png",
"tos_uri": "https://my-app.com/tos",
"policy_uri": "https://my-app.com/policy",
"redirect_uris": ["https://my-app.com/callback"],
"scope": "atproto",
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"token_endpoint_auth_method": "none",
"application_type": "web",
"dpop_bound_access_tokens": true
}
客户端元数据用于即时化OAuth客户端. 有两种方式 这样做:
-
要么你把元数据"烧"进你的应用程序:
import { BrowserOAuthClient } from '@atproto/oauth-client-browser' const client = new BrowserOAuthClient({ clientMetadata: { // Exact same JSON object as the one returned by the client_id URL }, // ... }) -
或者从URL同步加载:
import { OAuthClient } from '@atproto/oauth-client-browser' const client = await BrowserOAuthClient.load({ clientId: 'https://my-app.com/client-metadata.json', // ... })
如果性能对你很重要,建议烧掉元数据 输入脚本。 服务器侧向渲染技术也可以用于注入 在运行时将元数据输入脚本.
处理解析器
当您的申请启动 OAuth 流时, 它就会开始解决 (用户提供者)APTROTO操作器。 这通常通过 DNS请求. 然而,由于浏览器中没有DNS分辨率,a 必须提供后端服务.
[叹息]
使用 Bluesky 托管的服务处理解析(例如
bsky.social端点)将同时将用户IP地址和处理标识器泄露给Bluesky, a 第三方。 虽然Bluesky有公开的隐私政策,但两个开发者 和应用程序的用户需要了解和了解隐私 这一安排的影响。 鼓励应用程序开发者 改善用户隐私,在何时操作自己的处理器解析服务 也许吧 如果您是 PDS 自宿主, 您可以使用您的 PDS 的 URLhandleResolver。 。 。 .
如果有的话 string 或者说 URL 对象用作 handleResolver图书馆会
期望此值是运行该程序的服务的 URL
com.atproto.identity.resolveHandle XRPC Lexicon 方法.
[TIP]
如果您主机为自己的PDS,您可以使用它的URL作为处理解析器.
import { BrowserOAuthClient } from '@atproto/oauth-client-browser'
const client = new BrowserOAuthClient({
handleResolver: 'https://my-pds.example.com',
// ...
})
或者,如果有“DNS over HTTPS”(DoH)服务,则可以使用
解决了手柄。 在这种情况下 handleResolver 应初始化
带有 AtprotoDohHandleResolver 实例:
import {
BrowserOAuthClient,
AtprotoDohHandleResolver,
} from '@atproto/oauth-client-browser'
const client = new BrowserOAuthClient({
handleResolver: new AtprotoDohHandleResolver('https://my-doh.example.com'),
// ...
})
其他配置选项
何况 客户端元数据 财务报告和审定财务报表 处理
解析器,则 BrowserOAuthClient 构造器接受
遵循可选配置选项:
-
fetch: 自定义包装fetch函数。 这对 添加自定义信头、记录或使用不同的获取执行. 默认为window.fetch。 。 。 . -
responseMode数字 :query或者说fragment确定授权方式 响应返回客户端。 默认为fragment。 。 。 . -
plcDirectoryUrl: PLC 目录的URL. 这通常不会 除非您在本地运行整个 Atproto 堆栈 。 默认为https://plc.directory。 。 。 .
使用量
一旦 client ,可用于启动和管理 OAuth 会话.
初始化客户端
客户端会为你管理会话. 要做到这一点,首先 自我初始化 。 注意这项行动必须进行一次(和 仅限 一次当网络应用程序被装入时.
const result: undefined | { session: OAuthSession; state?: string } =
await client.init()
if (result) {
const { session, state } = result
if (state != null) {
console.log(
`${session.sub} was successfully authenticated (state: ${state})`,
)
} else {
console.log(`${session.sub} was restored (last active session)`)
}
}
返回值可用于确定客户端是否能够恢复
上次使用的会话( x)session 或如果当前导航是
授权重新定向的结果 session 财务报告和审定财务报表 state 页:1.
启动 OAuth 流量
为了启动OAuth流,我们必须首先确定哪些PDS 将启动认证流程 。 这意味着用户必须 请提供下列资料之一:
- 用户的手柄
- 用户做到了
- PDS/ 入口地址
利用这些信息,OAuthClient将解决所有需要的信息 以启动 OAuth 流程,并将用户重定向到 OAuth 服务器.
try {
await client.signIn('my.handle.com', {
state: 'some value needed later',
prompt: 'none', // Attempt to sign in without user interaction (SSO)
ui_locales: 'fr-CA fr en', // Only supported by some OAuth servers (requires OpenID Connect support + i18n support)
signal: new AbortController().signal, // Optional, allows to cancel the sign in (and destroy the pending authorization, for better security)
})
console.log('Never executed')
} catch (err) {
console.log('The user aborted the authorization process by navigating "back"')
}
返回的承诺永远不会解决(因为用户会被重定向到
oAuth 服务器。 如果用户在其中取消标志, 承诺会拒绝
(使用 AbortSignal),或者用户从 OAuth 服务器返回
(因为浏览器的后向缓存).
处理 OAuth 回复
当用户被重定向回应用程序时, OAuth 响应将会是
可在 URL 中找到。 这个 BrowserOAuthClient 将自动检测
反应和处理它时 client.init() 名为. 或者
应用程序可以手动处理使用
client.callback(urlQueryParams) 方法.
恢复会话
客户端通过内部跟踪管理的所有会话
存储。 不论从 client.init()
调用,任何其他会话都可以使用 client.restore() 方法。 这个
如果会话已无法使用, 或已存在错误, 方法会丢出错误
变成过期.
const aliceSession = await client.restore('did:plc:alice')
const bobSession = await client.restore('did:plc:bob')
当前形式的客户端不披露列出所有会话的方法 在它的商店。 应用必须跟踪这些东西.
监视会话无效
当会话无法进行时,客户端会发出事件,以便 触发全局行为(例如显示登录页).
client.addEventListener(
'deleted',
(
event: CustomEvent<{
sub: string
cause: TokenRefreshError | TokenRevokedError | TokenInvalidError
}>,
) => {
const { sub, cause } = event.detail
console.error(`Session for ${sub} is no longer available (cause: ${cause})`)
},
)
用法为 @atproto/api
这个 @atproto/api 软件包提供了与多个 Bluesky 交互的方法
具体的XRPC词汇表(com.atproto, (中文(简体) ), app.bsky, (中文(简体) ), chat.bsky, (中文(简体) ), tools.ozone(中文(简体) )
通过 Agent 接口。 这个 oauthSession 返回时间
BrowserOAuthClient 可用于即时 Agent 举个例子.
import { Agent } from '@atproto/api'
const session = await client.restore('did:plc:alice')
const agent = new Agent(session)
await agent.getProfile({ actor: agent.accountDid })
任何更新的证书 都会在引擎盖下 和新的标志 将保存在会话存储中(在浏览器索引的 DB 中).
预付款使用情况
用于开发(当地主机)
OAuth 服务器必须能够获取 client_metadata 对象。 最好的一个
如果你还没有部署你的应用软件 就是用地道
服务类 无。 。 。 .
这个 client_id 这将是类似的东西
https://<your-ngrok-id>.ngrok.io/<path_to_your_client_metadata>。 。 。 .
不过,回放客户有特殊情况。 循环客户端是
运行中的客户端 localhost。在这种情况下, OAuth 服务器将无法
以获取 client_metadata 对象因为 localhost 无法从
外边 要解决这个问题,需要Atproto OAuth服务器支持
通过提供硬码 client_metadata 对象.
这有几个限制:
- 没有配置客户端元数据(名称,标志等)的方法
- 刷新符号(如果有的话)的有效性将非常有限(通常为1个) 页:1
- 安静的签名是不允许的
- 仅
http://127.0.0.1:<any_port>财务报告和审定财务报表http://[::1]:<any_port>可用于 作为您的应用程序的来源,以及 没有http://localhost:<any_port>这个 库将自动将用户重定向到基于 IP 的来源 (单位:千美元)http://127.0.0.1:<port>(a) 与下列人员一起访问原籍国时:localhost。 。 。 .
仅为开发目的推荐使用回转客户端. 循环 客户端可以像这样被即时化 :
import { BrowserOAuthClient } from '@atproto/oauth-client-browser'
const client = new BrowserOAuthClient({
handleResolver: 'https://bsky.social',
// Only works if the current origin is a loopback address:
clientMetadata: undefined,
})
如果你需要使用一个特殊的 redirect_uris,您可以这样配置它们:
import { BrowserOAuthClient } from '@atproto/oauth-client-browser'
const client = new BrowserOAuthClient({
handleResolver: 'https://bsky.social',
// Note that the origin of the "client_id" URL must be "http://localhost" when
// using this configuration, regardless of the actual hostname ("127.0.0.1" or
// "[::1]"), port or pathname. Only the `redirect_uris` must contain the
// actual url that will be used to redirect the user back to the application.
clientMetadata: `http://localhost?redirect_uri=${encodeURIComponent('http://127.0.0.1:8080/callback')}`,
})