- name
- iam-integration
- description
- Use when integrating a new service with the IAM (Identity and Access Management) system - covers gRPC client setup, JWT token validation, permission checks, and REST API usage for the changyuanfeilun platform.
IAM Integration Guide
Overview
IAM is the central identity service. Services integrate via gRPC (primary) or REST. All resources are scoped by appCode + tenantCode.
Quick Reference
| Need | Method | Endpoint/Service |
|---|
| Validate JWT token | gRPC | JwtTokenService.validateAccessToken |
| Check permission | gRPC | AuthorizationService.hasPermission |
| Get user by UID | gRPC | AccountService.GetByUid |
| Login | REST | POST /api/v1.0/login/generateTicket |
| Exchange ticket for token | REST | POST /api/v1.0/account/exchangeAuthTicket |
| Get current user | REST | GET /api/v1.0/account/current |
1. gRPC Integration (Recommended)
Dependency
<dependency>
<groupId>com.feilun</groupId>
<artifactId>iam-rich-client</artifactId>
</dependency>
<dependency>
<groupId>com.feilun</groupId>
<artifactId>iam-boot-starter</artifactId>
</dependency>
Configuration
grpc:
client:
iam-service:
address: dns:///iam.${namespace}.svc.cluster.local:9090
negotiation-type: plaintext
Token Validation
@Autowired JwtTokenRichClient jwtTokenClient;
// Validate token (with optional permission check)
ValidateAccessTokenRequest req = ValidateAccessTokenRequest.newBuilder()
.setAccessToken(token)
.setAppCode(appCode)
.setTenantCode(tenantCode)
// optional: add permission check
.setPermissionCheck(PermissionCheck.newBuilder()
.setObject("resource-name")
.setAct("read")
.build())
.build();
ValidateAccessTokenResponse resp = jwtTokenClient.validateAccessToken(req);
// resp.getUid(), resp.getRoleCodesList(), resp.getValid()
Permission Check
@Autowired AuthorizationRichClient authClient;
HasPermissionRequest req = HasPermissionRequest.newBuilder()
.setAppCode(appCode)
.setTenantCode(tenantCode)
.setSubject(uid)
.setObject("resource-name")
.setAct("write")
.setSiteCode(siteCode)
.build();
boolean allowed = authClient.hasPermission(req).getHasPermission();
Get Account Info
@Autowired AccountRichClient accountClient;
GetByUidRequest req = GetByUidRequest.newBuilder()
.setUid(uid).setAppCode(appCode).setTenantCode(tenantCode)
.build();
AccountProto account = accountClient.getByUid(req).getAccount();
2. REST API Integration
Required Headers
| Header | Description |
|---|
X-ACCESS-TOKEN | JWT token |
X-App | App code |
X-Tenant | Tenant code |
X-Uid | User UID (set by gateway) |
X-IS-MOBILE | true / false |
Auth Filter
Add IamAuthInfoFilter to your service to auto-extract auth context from headers into thread-local.
// Access current user context anywhere in request thread
IamAuthContext ctx = IamAuthContextHolder.get();
String uid = ctx.getUid();
String tenantCode = ctx.getTenantCode();
3. Key Data Models
Account: uid, appCode, tenantCode, loginName, email, mobile,
acctStatus(0=inactive,1=active,2=disabled,9=cancelled),
acctType(0=sub,1=main), roleCodes[], siteScope[]
Authorization: subject(uid/role), object(resource), act(read/write/delete),
permitAll(bool), permitTargetId[], permitObjectId[]
4. Multi-tenancy Rules
- Every call must include
appCode + tenantCode - JWT secrets are per-app/tenant (
iam_jwt_secret table) - Permissions are site-scoped — always pass
siteCode when checking
5. Common Mistakes
| Mistake | Fix |
|---|
Missing appCode/tenantCode | Always required in every gRPC request |
Checking permission without siteCode | Pass siteCode for site-scoped resources |
Calling REST without X-App/X-Tenant headers | Required for all REST calls |
Using system mvn to build | Use ./mvnw — project requires Maven 3.8.x via wrapper |
6. Account Status Reference
| Code | Status |
|---|
| 0 | Inactive (pending activation) |
| 1 | Active |
| 2 | Disabled |
| 3 | Locked |
| 8 | Cancellation in progress |
| 9 | Cancelled |
