@aws- blocks/ auth- common (英语)

AWS Blocks Auth Building Blocks的所有共享接口和UI组件. 使用此软件包来构建提供者- 不可知的 Author UI, 或者在创建自定义 Author Building Block 时导入类型 .

设计与模拟等价细节 : 设计

出口

会话- cookie 安全政策/cookies(中文(简体) )

所有 AWS 块 Auth BBs 路由它们的会话- cookie SameSite 编号 : Secure 编号 : Partitioned 通过这个帮助者来选择,所以它们会从结构上而不是从漂移中汇合. 鉴于 { crossDomain, isLocalhost } 它返回犬科属性 :

buildCookieSecurityAttrs(input) 返回集合的 BB 的字符串窗体 Set-Cookie 手持; resolveCookieSecurity(input) 返回通过结构化饼干配置的 BB 属性对象. isLoopbackRequest(ctx) 检测回路源( r)localhost, (中文(简体) ), 127.0.0.1, (中文(简体) ), [::1](按要求) isLocalhost 决定.

可选 plainHttpOrigin 输入标记一个已部署的正门服务于平原 HTTP( 无证书的 ALB): 它会下降 Secure 来自同一来源的 Lax 饼干,否则浏览器会在HTTP上丢弃. 它并不改变跨域饼干,这是API自己的HTTPS响应设定. isInsecurePublicOrigin() 是从门的计谋中得来的BLOCKS_PUBLIC_ORIGIN 从开始 http://),从请求头里从没有. 现在 bb-auth-basic 通过它; 其它授权 BBs 保存 Secure所以在普通HTTP门后 他们的会话不会持续.

服务器- 服务器接口( S)BlocksAuth(中文(简体) )

执行所有授权基准 BlocksAuth。服务器侧码是相同的,无论提供者是谁:

import { AuthBasic } from '@aws-blocks/bb-auth-basic';

const auth = new AuthBasic(scope, 'auth');

export const api = new ApiNamespace(scope, 'api', (context) => ({
  // Require auth — throws 401 if not signed in
  async getProfile() {
    const user = await auth.requireAuth(context);
    return { username: user.username };
  },

  // Optional auth — returns null if not signed in
  async getContent() {
    const user = await auth.getCurrentUser(context);
    return user ? `Hello ${user.username}` : 'Hello guest';
  },

  // Boolean check — for branching
  async isLoggedIn() {
    return await auth.checkAuth(context);
  },
}));

// Export the state machine API for the Authenticator component
export const authApi = auth.createApi();

认证器组件

这个 Authenticator 使UI被国家机器驱动。 它与任何认证提供者合作—— AuthBasic, (中文(简体) ), AuthOIDC, (中文(简体) ), AuthCognito 因为它基于 AuthState的逻辑.

import { Authenticator } from '@aws-blocks/auth-common/ui';
import { authApi } from 'aws-blocks';

document.body.appendChild(Authenticator(authApi));

重新样式、重新贴上标签、隐藏或完全替换制成的表格,参见 自定义 Auth 用户界面。 。 。 .

本构成部分:

• 电话 getAuthState() 挂起,以确定要制作什么
• 渲染器为每个可用的动作组成字段并提交按钮
• 内部行动(否) url: 收集输入和呼叫 setAuthState({ action, ...fields })
• 外部行动 url: 制作一个提交外部 URL( Outh/ OIDC) 的 HTML 格式
• 播放认证更改到其他标签/窗口,并在更改到来时重新回复

账户菜单栏

页面上方的收缩栏 。 签名时显示"QQ用户名QQ签名出",或者签名出"签名出"按钮. 点击“ 签名” 打开 Authenticator 在一个模式上覆盖.

import { AccountMenuBar } from '@aws-blocks/auth-common/ui';
import { authApi } from 'aws-blocks';

document.body.prepend(AccountMenuBar(authApi));

使用 AccountMenuBar 用于页眉和 Authenticator 当您想要一个独立的登录形式(如专用登录页)时.

已认证

只有在用户签名时才会渲染内容. 当认证状态改变时自动更新( 相同的窗口和交叉 Tab) .

import { AuthenticatedContent } from '@aws-blocks/auth-common/ui';
import { authApi } from 'aws-blocks';

document.body.appendChild(
  AuthenticatedContent(authApi, (user) => {
    const el = document.createElement('div');
    el.textContent = `Welcome, ${user.username}`;
    return el;
  })
);

未认证用户的退后

在用户未签名时, 通过一个可选的第三个参数来显示替代内容 :

const loginPrompt = document.createElement('p');
loginPrompt.textContent = 'Please sign in to continue.';

document.body.appendChild(
  AuthenticatedContent(authApi, (user) => {
    const el = document.createElement('div');
    el.textContent = `Welcome, ${user.username}`;
    return el;
  }, loginPrompt)
);

在不提供倒置时,容器在签出(背向相容)时不产生任何结果.

状态

用于"加载/成功/出错"的有主题,可访问状态行 offernance appers 否则会带有内线样式的手卷. 它返回一个手柄:挂载 handle.element,然后用 handle.set(kind, text) 作为同步操作的进展.

import { StatusMessage } from '@aws-blocks/auth-common/ui';

const status = StatusMessage({ kind: 'loading', text: 'Loading…' });
document.querySelector('#app-status')!.replaceWith(status.element);

try {
  await saveSettings(); // your own async work
  status.set('success', 'Done.');
} catch (e) {
  status.set('error', `Failed: ${(e as Error).message}`);
}

该元素是一个礼貌的ARIA活区(ARIA活区)role="status", (中文(简体) ), aria-live="polite")),因此屏幕阅读器会在不偷取焦点的情况下宣布每次过渡. 这个 loading 状态让旋转者荣耀 prefers-reduced-motion。所有颜色来自共享 --bb-* 符号,所以它自动匹配活动光/暗主题.

过 testId 范围 -text ),当一个页面使多个状态区域.

Auth 状态更改订阅

订阅任何来源的认证状态变化( 相同的窗口 + 其他标签) :

import { onAuthChange } from '@aws-blocks/auth-common/ui';
import { authApi } from 'aws-blocks';

const unsubscribe = onAuthChange(authApi, (user) => {
  if (user) {
    console.log('Signed in:', user.username);
  } else {
    console.log('Signed out');
  }
});

// Later: unsubscribe();

onAuthChange 立即与当前用户调用回调,然后再次调用每个更改.

广播认证更改

如果您构建自定义认证 UI 而不是使用 Authenticator,该应用程序仍需要知道 Auth 何时改变,所以其他组件和标签的反应。 使用 submitAuthAction 作为单一通知符:它提交动作,推进缓存状态,并在任何已签入/已签出过渡中广播,所以两个已签入 财务报告和审定财务报表 保持UI的反应.

import { submitAuthAction } from '@aws-blocks/auth-common/ui';
import { authApi } from 'aws-blocks';

// Sign-in: submits, updates the cache, and broadcasts the transition.
const next = await submitAuthAction(authApi, { action: 'signIn', username: 'alice', password: 'secret' });
if (next.retriable) showError(next.error); // wrong password / MFA code: re-prompt, nothing broadcast

// Sign-out is the SAME call. The broadcast fires on the transition, so
// AccountMenuBar, AuthenticatedContent, and other tabs update immediately.
await submitAuthAction(authApi, { action: 'signOut' });

submitAuthAction(api, input) 返回结果 AuthState。一个赤裸的 setAuthState 调用翻转服务器会话但通知 无 在客户端上,这就是为什么直接调用它的习惯UI会变得僵化(特别是在签出; 第185期). 这个 Authenticator 用途 submitAuthAction 内部,所以你得到这个免费 当你使用它.

broadcastAuthChange (低级原始)

broadcastAuthChange 是基础 广播原始 submitAuthAction 打电话 只在认证状态通过路径改变时直接联系它 submitAuthAction 不遮盖,你需要 推动变化自己:

import { broadcastAuthChange } from '@aws-blocks/auth-common/ui';

// After a successful sign-in
broadcastAuthChange({ userId: 'alice', username: 'alice' });

// After sign-out
broadcastAuthChange(null);

function broadcastAuthChange(user: AuthUser | null): void

通过报名 AuthUser,或 null 签了字 它发射一个 BroadcastChannel 其它标签的信息加当前标签的窗口事件,这是每个 onAuthChange 订户听取. 只有浏览器:它触摸 window所以在安保部门期间别叫它.

应用程序代码通常安装伞包而不是 auth-common,该导入是 @aws-blocks/blocks/ui数字 :

import { broadcastAuthChange, onAuthChange, Authenticator } from '@aws-blocks/blocks/ui';

词根 @aws-blocks/blocks 入境点不出口,因为UI出口在后面 /ui 子路径,所以后端捆绑 不拉在反应. @aws-blocks/auth-common/ui 财务报告和审定财务报表 @aws-blocks/blocks/ui 是同一函数; 使用伞形路径, 除非您依赖 auth-common 直接说.

这个 Authenticator 组件自动执行。 你们只需要 broadcastAuthChange 如果你正在建造定制的UI。 完全通过自定义UI,包括 setAuthState 循环和 AuthActionInput 合同,见 自定义 Auth 用户界面。 。 。 .

赛明会injectTheme + 键 --bb-* 符号)

UI组件将一个框架中性设计-托肯层船. 每个 构成部分Authenticator, (中文(简体) ), AccountMenuBar, (中文(简体) ), AuthenticatedContent(中文(简体) ) 向小样式表注入 document.head 这是第一次 因此,主题的外观 与组件 旅行到任何宿主 - lt-html, 香草 DOM, React, Next.js — 没有样式表可以导入 .

样式表是 CSS 自定义属性 :root (单位:千美元)--bb-color-*, (中文(简体) ), --bb-space-*, (中文(简体) ), --bb-radius-*, (中文(简体) ), --bb-font-*, (中文(简体) ), --bb-shadow-*) 加上 基础 .bb-* 组件类 。 灯光和 提供暗色调色板; 暗色由自动选择 prefers-color-scheme。 。 。 .

因为信物已经打开了 :root,你自己的标记 可以消耗它们为 一致的外观, 不导入任何东西 :

.my-button {
  background: var(--bb-color-accent);
  color: var(--bb-color-accent-text);
  border-radius: var(--bb-radius-sm);
  padding: var(--bb-space-2) var(--bb-space-4);
}

通过设置强制一个特定的调色板 data-bb-theme 任何祖传 (它胜过媒体查询):

<body data-bb-theme="dark"> ... </body>

打电话 injectTheme() 在任何纪念品之前 组件挂载(例如,在启动时以页面染色体为主题)。 这个 是天能地能的,是安全无虞的——第二次呼叫是无,它返回 无声无息 document数字 :

import { injectTheme } from '@aws-blocks/blocks/ui';

injectTheme();

THEME_CSS (样式表作为字符串)和 THEME_STYLE_ID (单位:千美元) <style> 元素的 id) 也被导出给捆绑 CSS 的主机 通过一个积分步骤或在测试中断言反对它.

类型

AuthState

归来 getAuthState() 财务报告和审定财务报表 setAuthState()。 。 。 .

AuthAction

所有的行动都是形式。 它们在提交文件方面有所不同.

AuthField

AuthUser

提供商特有的BB扩展此段(例如:, AuthBasicUser 添加 createdAt) (中文(简体) ).