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#

NeedMethodEndpoint/ServiceValidate JWT tokengRPCJwtTokenService.validateAccessTokenCheck permissiongRPCAuthorizationService.hasPermissionGet user by UIDgRPCAccountService.GetByUidLoginRESTPOST /api/v1.0/login/generateTicketExchange ticket for tokenRESTPOST /api/v1.0/account/exchangeAuthTicketGet current userRESTGET /api/v1.0/account/current

1. gRPC Integration (Recommended)#

Dependency#

xml

<dependency>
    <groupId>com.feilun</groupId>
    <artifactId>iam-rich-client</artifactId>
</dependency>
<dependency>
    <groupId>com.feilun</groupId>
    <artifactId>iam-boot-starter</artifactId>
</dependency>

Configuration#

yaml

grpc:
  client:
    iam-service:
      address: dns:///iam.${namespace}.svc.cluster.local:9090
      negotiation-type: plaintext

Token Validation#

java

@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#

java

@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#

java

@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#

HeaderDescriptionX-ACCESS-TOKENJWT tokenX-AppApp codeX-TenantTenant codeX-UidUser 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.

java

// Access current user context anywhere in request thread
IamAuthContext ctx = IamAuthContextHolder.get();
String uid = ctx.getUid();
String tenantCode = ctx.getTenantCode();

3. Key Data Models#

text

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#

MistakeFixMissing appCode/ tenantCodeAlways required in every gRPC requestChecking permission without siteCodePass siteCode for site-scoped resourcesCalling REST without X-App/ X-Tenant headersRequired for all REST callsUsing system mvn to buildUse ./mvnw — project requires Maven 3.8.x via wrapper

6. Account Status Reference#

CodeStatus0Inactive (pending activation)1Active2Disabled3Locked8Cancellation in progress9Cancelled