iam

IAM

IAM（Identity and Access Management，身份识别与访问管理）是一个面向业务系统接入的身份与访问管理服务。

它围绕“用户是谁、如何证明用户身份、用户能访问什么资源”三个核心问题，统一提供用户身份建模、账号认证、访问授权、第三方身份源接入、Profile 联想搜索读模型。 同时，它还提供 REST / gRPC / Go SDK 等多种接入方式，以便于业务系统接入和集成。

功能特性

IAM 可以拆解为三个核心模块和两个辅助模块。

核心模块

1. Identity：用户身份与档案关系

• 回答“系统中的用户是谁”、“用户与业务档案是什么关系”。
• 主要负责 User、Profile、ProfileLink 等身份关系模型。

2.AuthN：认证

• 回答“如何证明当前请求者是某个系统用户”。
• 主要负责账号体系、登录方式、凭证校验、Session、Token 签发与校验、JWKS、RefreshToken 等认证能力。

3.AuthZ：授权

• 回答“当前用户能否对某个资源执行某个操作”。
• 主要负责角色、资源、权限、角色绑定、策略判定、策略变更传播等授权能力。

辅助模块

1. IDP：第三方身份源接入

• 回答“如何接入外部身份提供方，并将外部身份映射为系统内账号或用户”。
• 主要服务于 AuthN，例如微信、小程序、公众号、企业微信、OAuth Provider 等身份源接入。

2.Suggest：Profile 联想搜索读模型

• 回答“如何根据关键词快速搜索候选用户档案”。
• 主要作为面向管理端、运营端或业务系统的辅助查询能力，不直接承担核心身份语义。

软件架构

分层与端口

SVG 图源

运行时与组合根

SVG 图源

核心原则：

main 很薄；
process 管生命周期；
container 管组合装配；
transport 管协议适配；
application 管用例编排；
domain 管业务规则；
infra 管外部资源。

模块边界

SVG 图源

三个核心模块的事实所有权与协作边界见下图：

SVG 图源

快速开始

依赖检查

运行 IAM 前，请确保本地环境已经安装以下依赖：

• Go 1.25+
• Make
• MySQL
• Redis
• Docker，可选，运行 API 契约校验时需要

构建

make deps
make build

运行

make run APISERVER_CONFIG=configs/apiserver.dev.yaml

健康检查

curl http://localhost:18081/health
curl http://localhost:18081/.well-known/jwks.json

测试

make test

常用质量检查：

make docs-hygiene
go test ./internal/pkg/architecture
go test ./pkg/sdk/...

涉及 REST 契约：

make docs-swagger
make api-validate

涉及 gRPC 契约：

make proto-gen
go test ./internal/apiserver/transport/grpc

涉及 Suggest：

go test ./internal/apiserver/domain/suggest/... \
  ./internal/apiserver/application/suggest/... \
  ./internal/apiserver/infra/suggest/... \
  ./internal/apiserver/infra/mysql/suggest/... \
  ./internal/apiserver/transport/rest/suggest/...

使用指南

IAM 支持 REST、gRPC 和 Go SDK 三种接入方式。

REST API

REST API 适合 Web、App、管理后台、登录、HTTP 调试和 Suggest Profile autocomplete。

契约入口：

• api/rest/README.md
• api/rest/authn.v2.yaml
• api/rest/authz.v3.yaml
• api/rest/identity.v2.yaml
• api/rest/idp.v2.yaml
• api/rest/suggest.v2.yaml

Suggest REST 重点接口：

GET /api/v2/suggest/profile?k={keyword}&limit={limit}

响应语义：

候选结果必须经过 ProfileAccessScope 过滤；
手机号形态关键词需要 AllowMobileSearch；
响应只返回 mobile_mask，不返回明文 mobile。

gRPC API

gRPC 面向可信服务间调用，当前发布 v2 proto。

契约入口：

• api/grpc/README.md
• api/grpc/iam/authn/v2/authn.proto
• api/grpc/iam/authz/v3/authz.proto
• api/grpc/iam/identity/v2/identity.proto
• api/grpc/iam/idp/v2/idp.proto

Go SDK

Go 服务端推荐通过官方 SDK 接入 IAM。

入口：

• pkg/sdk/README.md
• pkg/sdk

示例：

package main

import (
    "context"
    "log"

    authnv2 "github.com/FangcunMount/iam/v3/api/grpc/iam/authn/v2"
    sdk "github.com/FangcunMount/iam/v3/pkg/sdk"
)

func main() {
    ctx := context.Background()

    client, err := sdk.NewClient(ctx, &sdk.Config{
        Endpoint: "localhost:8081",
    })
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    resp, err := client.Auth().VerifyToken(ctx, &authnv2.VerifyTokenRequest{
        AccessToken: "jwt-token",
    })
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("valid=%v", resp.GetValid())
}

SDK 是接入产品层，不是业务层。

它封装 REST/gRPC/JWKS/ServiceAuth/AuthZ Check 等接入复杂度，但不定义 IAM 业务规则。

文档导航

新版文档中心位于 docs/README.md。

推荐入口：

docs/
├── 00-概览/
├── 01-运行时/
├── 02-业务模块/
│   ├── 01-Identity/
│   ├── 02-AuthN/
│   ├── 03-AuthZ/
│   ├── 04-IDP/
│   └── 05-Suggest/
├── 03-基础设施/
├── 04-接口与SDK/
├── 05-工程质量与运维/
├── 06-专题设计/
├── _archive/
└── README.md

如何贡献

提交代码或文档时，请遵守以下规则。

保持分层边界

• domain 不依赖 infra/database；
• application 不依赖 transport/infra；
• transport 不直接访问 container 或全局配置；
• container 只做组合根，不处理请求；
• Suggest REST handler 不直接操作 Trie/Hash；
• Suggest domain 不依赖 infra/search。

同步机器契约

• 修改 REST 路由时同步 api/rest；
• 修改 Suggest REST 时同步 api/rest/suggest.v2.yaml；
• 修改 gRPC service/message 时同步 api/grpc；
• 修改 SDK 公开 API 时同步 pkg/sdk 文档和 compile test。

同步文档

• 代码行为变化时更新 docs/；
• Suggest 行为变化时同步 docs/02-业务模块/05-Suggest 和 docs/06-专题设计 中相关表达；
• 不从 _archive 复制当前事实；
• 不恢复旧目录作为 active 文档入口。

保护安全边界

• Suggest 查询必须经过 ProfileAccessScope 过滤；
• 不把 ProfileLink 写成 ProfileAccessScope；
• 不返回明文 mobile，只返回 mobile_mask；
• 降级时不能绕过权限直接查全局 MySQL。

运行验证

make docs-hygiene
go test ./internal/pkg/architecture
make api-validate
make proto-gen
go test ./pkg/sdk/...
go test ./internal/apiserver/domain/suggest/... \
  ./internal/apiserver/application/suggest/... \
  ./internal/apiserver/infra/suggest/... \
  ./internal/apiserver/infra/mysql/suggest/... \
  ./internal/apiserver/transport/rest/suggest/...

关于作者

本项目由 FangcunMount 维护。

许可证

本项目采用 Apache License 2.0 开源许可证，详见 LICENSE。