身份验证快速入门
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 运维部署
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- Docker
- 运行环境要求
- Python · Docker
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 读取环境变量
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第 1 步:收集需求
询问用户: 服务名称 - 人类可读的(例如,“发票服务”) 服务名称 - 小写标识符(例如,`invoices`)。用于权限、受众、文件名。域资源 — 名词(例如,发票、付款、客户) 每个资源的操作 — 动词(例如,读取、写入、创建、删除、发送、批准)
第 2 步:复制并自定义模板
该模板位于`assets/template/`。将整个目录复制到用户的目标路径,然后替换所有占位符: 占位符 · 替换为 `__SERVICE_NAME__` · 人类可读的名称 `__SERVICE_SLUG__` · 小写的 slug `__SERVICE_DESCRIPTION__` · 一行描述
第 3 步:验证结构
定制后,项目应具有:
第 4 步:本地运行
验证: `GET /health` 返回 `{"status": "ok"}`(无身份验证) `GET /items/` 返回绕过用户的数据(绕过身份验证) 当绕过关闭且未提供令牌时,路由返回正确的 401/403 JSON
第 5 步:指导后续步骤
脚手架运行后,将用户指向references/next-steps.md以进行: 添加更多权限和类型别名 添加检查回调(暂停、配额) 使用真实数据库连接第2阶段所有权验证 注册身份验证服务
# Auth Quickstart: Zero to Running Service
Scaffold a complete FastAPI service with ab0t-auth baked in from the start.
## When to Use This vs auth_fastapi_skill
| Situation | Use |
|-----------|-----|
| No code exists yet | **This skill** |
| Existing service needs auth added | auth_fastapi_skill |
| Need to understand permission design in depth | auth_fastapi_skill |
| Need scenario walkthroughs by industry | auth_service_ab0t |
## Scaffold Workflow
### Step 1: Gather Requirements
Ask the user for:
1. **Service name** — human-readable (e.g., "Invoice Service")
2. **Service slug** — lowercase identifier (e.g., `invoices`). Used in permissions, audience, file names.
3. **Domain resources** — the nouns (e.g., invoices, payments, customers)
4. **Actions per resource** — the verbs (e.g., read, write, create, delete, send, approve)
5. **Maintainer email** — for `.permissions.json`
If the user is vague, suggest reasonable defaults and confirm.
### Step 2: Copy and Customize Template
The template lives in `assets/template/`. Copy the entire directory to the user's target path, then replace all placeholders:
| Placeholder | Replace with |
|-------------|-------------|
| `__SERVICE_NAME__` | Human-readable name |
| `__SERVICE_SLUG__` | Lowercase slug |
| `__SERVICE_DESCRIPTION__` | One-line description |
| `__MAINTAINER_EMAIL__` | Contact email |
**Files to customize:**
1. **`.permissions.json`** — Replace starter permissions with real ones derived from the user's resources and actions. Follow the `{slug}.{action}.{resource}` format. Set `admin.implies` to include all lower permissions. Never imply `cross_tenant`.
2. **`app/auth.py`** — Replace starter type aliases (`Reader`, `Writer`, `Admin`) with domain-specific aliases matching the permissions. Example for an invoice service:
```python
InvoiceReader = Annotated[AuthenticatedUser, Depends(
require_permission(auth, "invoices.read", check=belongs_to_org))]
InvoiceSender = Annotated[AuthenticatedUser, Depends(
require_permission(auth, "invoices.send", check=belongs_to_org))]
```
3. **`app/api/items.py`** — Rename to match the primary resource (e.g., `invoices.py`). Replace the example routes with real ones using the domain-specific type aliases. Keep the same auth patterns (list with filter, get with Phase 2, create without Phase 2, delete with Phase 2, admin-only).
4. **`app/main.py`** — Update the router import and prefix to match the renamed module.
5. **`app/config.py`** — Add any service-specific settings.
### Step 3: Verify Structure
After customization, the project should have:
```
my-service/
├── app/
│ ├── __init__.py
│ ├── main.py # FastAPI app with auth lifespan
│ ├── config.py # Pydantic settings
│ ├── auth.py # AuthGuard, type aliases, Phase 2, check callbacks
│ └── api/
│ ├── __init__.py
│ ├── health.py # Unauthenticated health check
│ └── {resource}.py # Auth-protected CRUD routes
├── .permissions.json # Permission definitions for registration
├── .env.example # Environment variable reference
├── .gitignore # Excludes credentials/, .env, etc.
├── requirements.txt # Dependencies including ab0t-auth
└── Dockerfile # Production container
```
### Step 4: Run Locally
```bash
cd my-service
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # Edit values
# Development with auth bypass
AB0T_AUTH_DEBUG=true AB0T_AUTH_BYPASS=true uvicorn app.main:app --reload
```
Verify:
- `GET /health` returns `{"status": "ok"}` (no auth)
- `GET /items/` returns data with bypass user (auth bypassed)
- Routes return proper 401/403 JSON when bypass is off and no token is provided
### Step 5: Guide Next Steps
After the scaffold is running, point the user to [references/next-steps.md](references/next-steps.md) for:
- Adding more permissions and type aliases
- Adding check callbacks (suspension, quota)
- Wiring up Phase 2 ownership verification with a real database
- Registering with the auth service
- Multi-tenancy setup
- Middleware for blanket auth
- Production checklist
For deep dives, reference the **auth_fastapi_skill**:
- [permissions-design.md](../auth_fastapi_skill/references/permissions-design.md) — full schema and design principles
- [route-patterns.md](../auth_fastapi_skill/references/route-patterns.md) — all 7 route protection patterns
- [implementation-details.md](../auth_fastapi_skill/references/implementation-details.md) — all 19 type aliases, check callbacks
- [registration.md](../auth_fastapi_skill/references/registration.md) — auth service registration walkthrough
## Permission Design Quick Reference
**Format:** `{slug}.{action}` or `{slug}.{action}.{resource}`
| Action | Meaning | Risk |
|--------|---------|------|
| `read` | View without side effects | low |
| `write` | Modify existing records | medium |
| `create` | Create new records | medium |
| `delete` | Permanently remove | high |
| `execute` | Run user-provided code | high |
| `admin` | Full org-level access (implies lower perms) | critical |
| `cross_tenant` | Cross-org access (NEVER implied by admin) | critical |
## Common Mistakes
1. **Forgetting to rename placeholders** — grep for `__SERVICE` after scaffolding to catch any missed replacements
2. **Skipping Phase 2** — every route with `/{id}` in the path needs `verify_resource_access()` after the DB fetch
3. **Implying `cross_tenant` from `admin`** — never do this; it must be a conscious separate grant
4. **Unscoped list queries** — always use `get_user_filter(user)` for list/search routes
5. **404 after 403** — always check resource exists (404) before checking access (403)
---
> Source: [ab0t-com/auth_wrapper](https://github.com/ab0t-com/auth_wrapper) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
章节与文件索引
按说明文件中的顺序排列。
何时使用此选项与 authfastapiskill
第 1 步:收集需求
第 2 步:复制并自定义模板
第 3 步:验证结构
第 4 步:本地运行
文件/命令 -> invoices · .permissions.json · assets/template/ · __SERVICE_NAME__ · __SERVICE_SLUG__ · __SERVICE_DESCRIPTION__ · __MAINTAINER_EMAIL__ · {slug}.{action}.{resource}
内容校验值 -> 477887f38123
当前原文的自动摘译,尚未人工审校。
何时使用此选项与 authfastapiskill
情况 · 使用 尚无代码 · 该技能 现有服务需要添加 auth · auth_fastapi_skill 需要深入了解权限设计 · auth_fastapi_skill 需要行业场景演练 · auth_service_ab0t