@aws- blocks/ bb-auth- basic (英语)

使用 JWT 会话的简单用户名/密码认证,密码政策,以及可选代码确认的签名和密码重置.

何时使用 : 原型,内部工具,MVP,或不需要OAuth/OIDC复杂性的应用.

不使用时 : 用于社交签名( Google, GitHub), 使用 AuthOIDC。对于外交部,用户组,或自定义用户属性,使用 AuthCognito。 。 。 .

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

快速启动

import { Scope, ApiNamespace } from '@aws-blocks/core';
import { AuthBasic } from '@aws-blocks/bb-auth-basic';

const scope = new Scope('my-app');
const auth = new AuthBasic(scope, 'auth', {
  sessionDuration: 86400,
  passwordPolicy: { minLength: 8, requireDigits: true },
  // Optional: enable code-confirmed signup and password reset
  codeDelivery: async (username, code) => {
    await sendEmail(username, `Your verification code: ${code}`);
  },
});

export const api = new ApiNamespace(scope, 'api', (context) => ({
  async getProfile() {
    const user = await auth.requireAuth(context);
    return { username: user.username, createdAt: user.createdAt };
  },
}));

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

客户端命名空间取自 导出名称 您选择这里( 因此 ) import { authApi } from 'aws-blocks' 匹配); 该 'auth' 内部标签 createApi() 是内部的,不影响线名空间.

前端: 提供登录 UI 并打开应用程序

导出 authApi 提供后端,但 它不会渲染登录屏幕 - 您的 SPA 仍然不显示, 直到您挂载一个认证组件 。 如果您停在后端, 一个认证的应用程序打开了一个空白/登陆页面, 而每个登录的路由都是无法到达的 。 挂载已运出 Authenticator UI在你的SPA入口 并打开其后面的应用程序外壳:

// src/index.ts — the SPA entrypoint
import { api, authApi } from 'aws-blocks';
import { AccountMenuBar, AuthenticatedContent } from '@aws-blocks/blocks/ui';

// A Sign In / account control that opens the Authenticator (sign-up / sign-in /
// confirm-code / reset) when clicked. No testids to wire by hand — the shipped
// components already carry them (see auth-common/CUSTOMIZING-AUTH-UI.md).
document.getElementById('menu-bar')!.appendChild(AccountMenuBar(authApi));

// Gate the app shell: the render callback runs only when a session exists;
// the fallback shows while signed out.
const signInMessage = document.createElement('p');
signInMessage.textContent = 'Sign in to get started.';

document.getElementById('app')!.appendChild(
  AuthenticatedContent(authApi, (user) => {
    const el = document.createElement('div');
    el.textContent = `Welcome, ${user.username}`;
    // ...build the authenticated app here, calling your `api` methods...
    return el;
  }, signInMessage),
);

• AccountMenuBar(authApi) 使弹出 Authenticator。要将窗体嵌入内线,请使用 Authenticator(authApi) 直接说.
• AuthenticatedContent(authApi, render, fallback) 订阅会话并在 render(user) 财务报告和审定财务报表 fallback 在注册/退出时——这是贝壳的大门.
• 都来自 @aws-blocks/blocks/ui (从 @aws-blocks/auth-common/ui) (中文(简体) ).
• 登入/签入的球场和扣子船的稳定测试仪 一个e2e套件可以直接瞄准—— authenticator-username, (中文(简体) ), authenticator-password, (中文(简体) ), authenticator-code,以及 authenticator-action-signUp 编号 : authenticator-action-signIn (一个) authenticator-<field> 每个输入,一个 authenticator-action-<action> (每个行动)。 完全选择者合同是在 auth-common/CUSTOMIZING-AUTH-UI.md; 不要将组件叉入添加自己的组件.

见脚手架 default 模板 src/index.ts 为了一个完整的工作应用程序 在这个接合.

API 密码

const auth = new AuthBasic(scope, id, options?)

服务器系统方法

动作输入形状 : createApi() 返回国家机器 API. setAuthState 使用单一 FLAT 歧视性输入 { action, ...fields }从不筑巢 { action, data: {...} }实例: { action: 'signIn', username, password }, (中文(简体) ), { action: 'signUp', username, password }, (中文(简体) ), { action: 'confirmSignUp', username, code, password }, (中文(简体) ), { action: 'resetPassword', username }, (中文(简体) ), { action: 'confirmResetPassword', username, code, newPassword }见 AuthActionInput 类型在 @aws-blocks/auth-common。 。 。 .

buildApi() (折旧)

折旧-使用 createApi()。 。 。 . 为后向相容性保留. 与 createApi() (它揭露 getAuthState编号 :setAuthState 国家机器, buildApi() 返回一个 ApiNamespace 带有平坦的RPC表面. 此处记录了这样现有的呼叫者可以找到形状. 请求 context 被命名空间工厂捕获,所以曝光的方法没有 context 参数 :

选项

密码策略

代码传送

何时 codeDelivery 规定如下:

• 注册 创建未确认状态的用户。 代码通过回调发送. 用户必须打电话 confirmSignUp 在他们签字之前.
• 密码重置 作为国家机器行动可以使用。 代码通过回调发送. 用户输入代码+新密码来完成重置.
• 校验代码为6位数字符串,有效期为10分钟.
• 代码在存储之前是 HMAC- hashed —— 从未以纯文本存储.
• 每个代码最多允许5个失败的猜想(签名确认和密码重置相同);在第5个错误猜想后代码无效,用户必须要求一个新的. 6位数的代码在其10分钟的窗口内可以野蛮地执行,而不使用它 关闭。 。 。 .

何时 codeDelivery 实值 没有 条件是:

• 即时报名(无确认步骤).
• 密码重置不可用( 动作不出现在状态机器中) .

处理错误

import { isBlocksError } from '@aws-blocks/core';
import { AuthBasicErrors } from '@aws-blocks/bb-auth-basic';

try {
  await auth.signIn('alice', 'wrong', context);
} catch (e) {
  if (isBlocksError(e, AuthBasicErrors.InvalidCredentials)) {
    // bad username or password
  }
}

分会 setAuthState 客户端路径

isBlocksError 工作在一个 抛出 错误。 建议的客户端路径( E)createApi() → setAuthState())不扔出——它返回一个 AuthState 谁 errorName 带有相同的结构名称。 使用 hasAuthError 到返回状态上的分支, 例如返回到一个全新的用户的注册 :

import { hasAuthError } from '@aws-blocks/core';
import { AuthBasicErrors } from '@aws-blocks/bb-auth-basic';

let next = await authApi.setAuthState({ action: 'signIn', username, password });
if (hasAuthError(next, AuthBasicErrors.InvalidCredentials)) {
  // unknown or wrong-credential user → offer sign-up instead
  next = await authApi.setAuthState({ action: 'signUp', username, password });
}

拇指规则: 抛出路径 isBlocksError; 返回时 AuthState → hasAuthError。 。 。 . 永远不要和人类相配 error 绳子.

UI 组件

此包不包括UI组件. 使用来自 @aws-blocks/auth-common/ui数字 :

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

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

见 auth-common 读取 用于完整的UI组件文档,包括 AuthenticatedContent, (中文(简体) ), onAuthChange,以及 broadcastAuthChange。 。 。 .

认证基本用户

扩展常见 AuthUser 改为:

再出口类型

这些类型来自: @aws-blocks/auth-common 由此软件包再导出,以便直接从 @aws-blocks/bb-auth-basic 不添加对 auth-common数字 :

import type {
  BlocksAuth, AuthUser, AuthState, AuthActionInput, AuthAction, AuthField,
} from '@aws-blocks/bb-auth-basic';

饼干和会议

本届会议是 HttpOnly 饼干持有一个签名的JWT。 默认饼干是 SameSite=Lax (单位:千美元) Secure 这对同源的应用程序和本地的dev代理来说是正确的.

当你通过Hosting块服务前端时, CloudFront 将静态站点和API 放在后面 一个来源 (API是同一分布的路径),所以所部署的app是同源的,并且 SameSite=Lax 默认工作, 没有任何配置 —— 离开 crossDomain 默认时 false。 。 。 .

设定 crossDomain: true 只在前端和API从 不同的可注册域 在生产中(例如Vercel上的前端,AWS上的API). 那把饼干切到 SameSite=None; Secure; Partitioned 因此,它经受住了跨地点的要求:

const auth = new AuthBasic(app, 'auth', { crossDomain: true });

在 plain-HTTP 本地主机上 BB 滴入 Secure 联 合 国 Lax 默认和下降 Partitioned 用于跨域食谱(CHIPS需要HTTPS).

撤销:读取费用和一致性

服务器端的退出( 见 signOut) 添加 一个迪纳摩DB GetItem 每个经认证的请求 —— 说 checkAuth, (中文(简体) ), getCurrentUser, (中文(简体) ), requireAuth,则 getAuthState 调用在页面加载上运行的每个检查符号 jti 反对撤销名单。 与纯无国籍的JWT验证相比, 撤销前签发的托肯( 无) jti) 跳过读取,在读取中直接过期 sessionDuration。 。 。 .

撤销读取是最终一致的 GetItem (无) ConsistentRead因此,撤销是 近即时而非瞬间: 对于后面的子秒窗口 signOut在撤销标记发布之前, 签出的信物停止在宣传窗口内到处工作,总是在自己的时间过期 exp 随便.

签名催促

野蛮武力和威信攻击 signIn 带有密码的猜测。 启用 lockout 在连续多次失败后锁定账户的政策—— 与Cognito管理的关闭点对等 AuthCognito数字 :

// Lock an account for 15 minutes after 5 consecutive failed sign-ins (defaults)
const auth = new AuthBasic(app, 'auth', { lockout: {} });

// Stricter: 3 attempts, 30-minute lock
const auth = new AuthBasic(app, 'auth', {
  lockout: { maxAttempts: 3, lockoutSeconds: 1800 },
});

锁门的时候, signIn 掷出 AuthBasicErrors.AccountLocked (单位:千美元)AccountLockedException页:1 在此之前 密码被检查,所以一个被锁定的账户会流出被攻击的bcrypt成本,并且决定中没有密码依赖的时间信号. 成功签入可以清出柜台. 计数是 每个用户名 (证书-上接目标);它不会被IP锁定,所以共享NAT不是假阳性风险.

喉咙是 选入 没有 lockout 选项, 登录是无限的, 行为与以前完全一样。 计数器与验证码和吊销标记一样,生活在TTL后置的同一家商店中,因此它们自取而出,从不生长出无约束.

计数器是一个最优的读取-修改-写出,而不是原子增量,因此同一用户名(在很多Lambda实例中)的高度并发的故障可以失去增量,使锁出行稍晚于 maxAttempts 建议。 锁定窗口是从数数到达时开始测量的 maxAttempts所以锁总能撑住 lockoutSeconds 一次绊倒.

地方发展: 模拟 KVStore 是模拟, 所以当 dev 服务器重新启动时, 锁定计数器( 如 AuthBasic state) 重置 .