deleteSession(@PathVariable String id) {
sessionService.deleteSession(id);
return ResponseEntity.noContent().build();
}
}
// Custom annotation
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface RequirePermission {
String action();
String resource();
}
// Aspect for handling the annotation
@Aspect
@Component
public class IamAspect {
@Autowired
private IamService iamService;
@Before("@annotation(requirePermission)")
public void checkPermission(JoinPoint joinPoint, RequirePermission requirePermission) {
// Extract user token and build resource string
String userToken = getCurrentUserToken();
String resource = buildResourceString(requirePermission.resource(), joinPoint.getArgs());
if (!iamService.authorize(userToken, requirePermission.action(), resource)) {
throw new SecurityException("Access denied");
}
}
}
```
## Frontend Integration
### React Hook
```jsx theme={null}
import { useState, useEffect } from 'react';
import { useIamClient } from '@smarterservices/iam-react';
export function usePermission(action, resource) {
const [hasPermission, setHasPermission] = useState(false);
const [loading, setLoading] = useState(true);
const iamClient = useIamClient();
useEffect(() => {
async function checkPermission() {
try {
const authorized = await iamClient.authorize(action, resource);
setHasPermission(authorized);
} catch (error) {
console.error('Permission check failed:', error);
setHasPermission(false);
} finally {
setLoading(false);
}
}
checkPermission();
}, [action, resource, iamClient]);
return { hasPermission, loading };
}
// Usage
function SessionActions({ sessionId }) {
const { hasPermission: canDelete, loading } = usePermission(
'sp:DeleteSession',
`ssrn:ss:sp::578:session/${sessionId}`
);
if (loading) return Loading...
;
return (
{canDelete && (
)}
);
}
```
### Vue.js Directive
```javascript theme={null}
import { IamClient } from '@smarterservices/iam-client';
const iam = new IamClient({
apiUrl: process.env.VUE_APP_IAM_API_URL,
token: () => store.getters.authToken
});
// Custom directive
Vue.directive('iam', {
async bind(el, binding) {
const { action, resource } = binding.value;
try {
const authorized = await iam.authorize(action, resource);
if (!authorized) {
el.style.display = 'none';
}
} catch (error) {
console.error('IAM check failed:', error);
el.style.display = 'none';
}
}
});
// Usage in template
```
## Configuration
### Environment Variables
```bash theme={null}
# IAM Service Configuration
IAM_API_URL=https://iam.smarterservices.com
IAM_SERVICE_KEY=your-service-key
IAM_CACHE_TTL=300
IAM_TIMEOUT=5000
# Application Configuration
APP_ACCOUNT_ID=578
APP_SERVICE=sp
APP_REGION=us-east-1
```
### Configuration File
```json theme={null}
{
"iam": {
"apiUrl": "https://iam.smarterservices.com",
"serviceKey": "${IAM_SERVICE_KEY}",
"cache": {
"enabled": true,
"ttl": 300,
"maxSize": 1000
},
"timeout": 5000,
"retries": 3
},
"application": {
"accountId": "578",
"service": "sp",
"region": "us-east-1"
}
}
```
## Caching
### Client-Side Caching
```javascript theme={null}
import { IamClient } from '@smarterservices/iam-client';
const iam = new IamClient({
apiUrl: 'https://iam.smarterservices.com',
token: 'your-token',
cache: {
enabled: true,
ttl: 300, // 5 minutes
maxSize: 1000
}
});
// Permissions are cached automatically
const canRead = await iam.authorize('sp:ReadSession', 'ssrn:ss:sp::578:session/ES123');
```
### Server-Side Caching
Provide any key-value cache that implements `get(key)` and `set(key, value, ttl)`; the store is entirely your choice.
```javascript theme={null}
const { IamService } = require('@smarterservices/iam-node');
// Bring your own cache store (any get/set-with-ttl implementation).
const cacheStore = createCacheStore();
const iam = new IamService({
apiUrl: 'https://iam.smarterservices.com',
serviceKey: 'your-service-key',
cache: {
get: async (key) => {
const value = await cacheStore.get(key);
return value ? JSON.parse(value) : null;
},
set: async (key, value, ttl) => {
await cacheStore.set(key, JSON.stringify(value), ttl);
}
}
});
```
## Error Handling
### Client-Side Error Handling
```javascript theme={null}
try {
const authorized = await iam.authorize(action, resource);
if (authorized) {
// Proceed with action
} else {
// Show access denied message
showError('You do not have permission to perform this action');
}
} catch (error) {
if (error.code === 'NETWORK_ERROR') {
// Handle network issues
showError('Unable to verify permissions. Please try again.');
} else if (error.code === 'INVALID_TOKEN') {
// Handle authentication issues
redirectToLogin();
} else {
// Handle other errors
console.error('IAM error:', error);
showError('Permission check failed');
}
}
```
### Server-Side Error Handling
```javascript theme={null}
app.use((error, req, res, next) => {
if (error.name === 'IamError') {
switch (error.code) {
case 'FORBIDDEN':
return res.status(403).json({
error: 'Forbidden',
message: 'Insufficient permissions'
});
case 'UNAUTHORIZED':
return res.status(401).json({
error: 'Unauthorized',
message: 'Invalid or expired token'
});
case 'SERVICE_UNAVAILABLE':
return res.status(503).json({
error: 'Service Unavailable',
message: 'Authorization service is temporarily unavailable'
});
default:
return res.status(500).json({
error: 'Internal Server Error',
message: 'Authorization check failed'
});
}
}
next(error);
});
```
## Testing
### Unit Testing
```javascript theme={null}
// Mock IAM client for testing
jest.mock('@smarterservices/iam-client');
const { IamClient } = require('@smarterservices/iam-client');
describe('Session Controller', () => {
beforeEach(() => {
IamClient.mockClear();
});
test('should allow access with proper permissions', async () => {
const mockAuthorize = jest.fn().mockResolvedValue(true);
IamClient.mockImplementation(() => ({
authorize: mockAuthorize
}));
const response = await request(app)
.get('/api/sessions/ES123456')
.set('Authorization', 'Bearer valid-token')
.expect(200);
expect(mockAuthorize).toHaveBeenCalledWith(
'sp:ReadSession',
'ssrn:ss:sp::578:session/ES123456'
);
});
test('should deny access without permissions', async () => {
const mockAuthorize = jest.fn().mockResolvedValue(false);
IamClient.mockImplementation(() => ({
authorize: mockAuthorize
}));
await request(app)
.get('/api/sessions/ES123456')
.set('Authorization', 'Bearer valid-token')
.expect(403);
});
});
```
### Integration Testing
```javascript theme={null}
describe('IAM Integration', () => {
test('should integrate with real IAM service', async () => {
const iam = new IamClient({
apiUrl: process.env.TEST_IAM_API_URL,
token: process.env.TEST_TOKEN
});
const authorized = await iam.authorize(
'sp:ReadSession',
'ssrn:ss:sp::578:session/test-session'
);
expect(typeof authorized).toBe('boolean');
});
});
```
## Best Practices
### 1. Use Least Privilege
Only request the minimum permissions needed for functionality.
### 2. Cache Appropriately
Cache permission results to improve performance, but ensure cache invalidation works correctly.
### 3. Handle Errors Gracefully
Always handle IAM service failures gracefully with appropriate fallbacks.
### 4. Validate Resources
Ensure resource strings are properly formatted and validated.
### 5. Monitor Performance
Monitor IAM service response times and implement circuit breakers if needed.
### 6. Secure Service Keys
Store service keys securely and rotate them regularly.
### 7. Log Security Events
Log all authorization decisions for audit and debugging purposes.
## Troubleshooting
### Common Issues
1. **Invalid Resource Format**: Ensure SSRN format is correct
2. **Token Expiration**: Handle token refresh properly
3. **Network Timeouts**: Implement proper timeout and retry logic
4. **Cache Inconsistency**: Ensure cache invalidation works correctly
5. **Permission Lag**: Account for eventual consistency in permission updates
### Debugging
1. **Enable Debug Logging**: Set log level to debug for detailed information
2. **Check Network Connectivity**: Verify IAM service is reachable
3. **Validate Tokens**: Ensure authentication tokens are valid
4. **Test Policies**: Use IAM policy simulator for testing
5. **Monitor Metrics**: Track authorization success/failure rates