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 联想搜索读模型

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

软件架构

分层架构

六边形架构

核心原则：

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

模块边界

快速开始

依赖检查

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

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

构建

make deps
make build

运行

make run APISERVER_CONFIG=configs/apiserver.dev.yaml

健康检查

curl http://localhost:8080/health
curl http://localhost:8080/.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.v2.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/v2/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/v2/api/grpc/iam/authn/v2"
    sdk "github.com/FangcunMount/iam/v2/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-认证AuthN/
├── 03-授权AuthZ/
├── 04-身份Identity/
├── 05-接入与契约/
├── 06-架构护栏/
├── 07-宣讲/
├── 08-Suggest/
└── 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/08-Suggest 和 docs/07-宣讲 中相关表达；
• 不从 _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。