Iam Integration

Use when integrating a new service with the IAM (Identity and Access Management) system - covers gRPC client setup, JWT token validation, permission checks,...

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