Iam Integration

SKILL.md

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

```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

| 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.

```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

```
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 |