Skip to content

Commit e3b970f

Browse files
Yaminik1996Yaminik1996
authored
docs: add IAM documentation (#290)
1 parent 9ae87b1 commit e3b970f

File tree

3 files changed

+210
-2
lines changed

3 files changed

+210
-2
lines changed

‎guides/conformance-tests-guide.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: "How to: Conformance tests in multicloudj"
4-
nav_order: 5
4+
nav_order: 6
55
parent: Usage Guides
66
---
77

‎guides/iam-guide.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
---
2+
layout: default
3+
title: How to IAM
4+
nav_order: 5
5+
parent: Usage Guides
6+
---
7+
# IAM
8+
9+
The `IamClient` class in the `multicloudj` library provides a comprehensive, cloud-agnostic interface to interact with Identity and Access Management services like AWS IAM, GCP IAM, and AliCloud RAM.
10+
11+
This client enables creating and managing identities (roles, service accounts), attaching and managing inline policies, and configuring trust relationships across multiple cloud providers with a consistent API.
12+
13+
---
14+
15+
## Feature Support Across Providers
16+
17+
### Core API Features
18+
19+
| Feature Name | GCP | AWS | ALI | Comments |
20+
|--------------|------------------|-----|-----|----------|
21+
| **Create Identity** | ✅ Supported | ✅ Supported | 📅 In Roadmap | Create roles/service accounts with optional trust and options |
22+
| **Get Identity** | ✅ Supported | ✅ Supported | 📅 In Roadmap | Retrieve identity metadata (ARN, email, or roleId) |
23+
| **Delete Identity** | ✅ Supported | ✅ Supported | 📅 In Roadmap | Remove an identity from the cloud provider |
24+
| **Attach Inline Policy** | ✅ Supported | ✅ Supported | 📅 In Roadmap | Attach a policy document; AWS use PutRolePolicy directly |
25+
| **Get Attached Policies** | ✅ Supported | ✅ Supported | 📅 In Roadmap | List inline policies attached to an identity |
26+
| **Get Inline Policy Details** | ✅ Supported | ✅ Supported | 📅 In Roadmap | Retrieve policy document details |
27+
| **Remove Policy** | ✅ Supported | ✅ Supported | 📅 In Roadmap | Remove an inline policy from an identity |
28+
29+
### Configuration Options
30+
31+
| Configuration | GCP | AWS | ALI | Comments |
32+
|---------------|-----|-----|-----|----------|
33+
| **Trust Configuration** | ✅ Supported | ✅ Supported | 📅 In Roadmap | Principals and conditions for assume/impersonate |
34+
35+
---
36+
37+
### Provider-Specific Notes
38+
39+
**AWS (IAM)**
40+
- Tenant ID is the AWS account ID (12-digit). IAM is global per partition; region is used by the IAM client to resolve the partition and its endpoint.
41+
- Get inline policy details: `policyName` is required.
42+
43+
**GCP (IAM)**
44+
- Tenant ID: for identity operations use project ID (or `projects/...`); for policy operations use the resource that owns the IAM policy (e.g. `projects/my-project`, `folders/123`).
45+
- Create Identity creates a Service Account on GCP. You provide the service account ID; it returns email `{id}@{project}.iam.gserviceaccount.com`. Create options are unused.
46+
- Attach policy: `resource` is the IAM member (e.g. `serviceAccount:...`); policy actions are GCP role names (e.g. `roles/storage.objectViewer`). Get inline policy details: `roleName` is required; `policyName` is not used.
47+
- Remove policy: `policyName` is the role name to remove.
48+
49+
---
50+
51+
## Creating the Client
52+
53+
### Basic Client
54+
55+
```java
56+
IamClient iamClient = IamClient.builder("aws")
57+
.withRegion("us-west-2")
58+
.build();
59+
```
60+
61+
Use the appropriate provider ID: `"aws"`, `"gcp"`, or `"ali"`. The client implements `AutoCloseable`; use try-with-resources or call `close()` when done.
62+
63+
---
64+
65+
## Identity Operations
66+
67+
### Creating an Identity
68+
69+
```java
70+
try (IamClient iamClient = IamClient.builder("aws").withRegion("us-west-2").build()) {
71+
72+
String identityId = iamClient.createIdentity(
73+
"MyRole",
74+
"Example role for storage access",
75+
"123456789012",
76+
"us-west-2",
77+
Optional.empty(),
78+
Optional.empty()
79+
);
80+
}
81+
```
82+
83+
With trust configuration:
84+
85+
```java
86+
TrustConfiguration trustConfig = TrustConfiguration.builder()
87+
.addTrustedPrincipal("arn:aws:iam::123456789012:root")
88+
.build();
89+
90+
String identityId = iamClient.createIdentity(
91+
"CrossAccountRole",
92+
"Role assumable by account 123456789012",
93+
"123456789012",
94+
"us-west-2",
95+
Optional.of(trustConfig),
96+
Optional.empty()
97+
);
98+
```
99+
100+
With creation options (path, max session duration, permission boundary):
101+
102+
```java
103+
CreateOptions options = CreateOptions.builder()
104+
.path("/service-roles/")
105+
.maxSessionDuration(3600)
106+
.build();
107+
108+
String identityId = iamClient.createIdentity(
109+
"ServiceRole",
110+
"Role for backend service",
111+
"123456789012",
112+
"us-west-2",
113+
Optional.empty(),
114+
Optional.of(options)
115+
);
116+
```
117+
118+
### Getting Identity Metadata
119+
120+
```java
121+
String identityInfo = iamClient.getIdentity("MyRole", "123456789012", "us-west-2");
122+
```
123+
124+
### Deleting an Identity
125+
126+
```java
127+
iamClient.deleteIdentity("MyRole", "123456789012", "us-west-2");
128+
```
129+
130+
---
131+
132+
## Policy Operations
133+
134+
### Building a Policy Document
135+
136+
The example below uses AWS-style actions and resources (version `2012-10-17`, S3 actions, ARN resource).
137+
138+
```java
139+
PolicyDocument policy = PolicyDocument.builder()
140+
.version("2012-10-17")
141+
.statement("StorageAccess")
142+
.effect("Allow")
143+
.addAction("s3:GetObject")
144+
.addAction("s3:PutObject")
145+
.addResource("arn:aws:s3:::my-bucket/*")
146+
.condition("StringEquals", "aws:RequestedRegion", "us-west-2")
147+
.endStatement()
148+
.build();
149+
```
150+
151+
### Attaching an Inline Policy
152+
153+
```java
154+
iamClient.attachInlinePolicy(policy, "123456789012", "us-west-2", "MyRole");
155+
```
156+
157+
### Listing Attached Policies
158+
159+
```java
160+
List<String> policyNames = iamClient.getAttachedPolicies("MyRole", "123456789012", "us-west-2");
161+
policyNames.forEach(name -> System.out.println("Policy: " + name));
162+
```
163+
164+
### Getting Inline Policy Details
165+
166+
```java
167+
String policyJson = iamClient.getInlinePolicyDetails(
168+
"MyRole",
169+
"StorageAccess",
170+
"MyRole",
171+
"123456789012",
172+
"us-west-2"
173+
);
174+
```
175+
176+
### Removing a Policy
177+
178+
```java
179+
iamClient.removePolicy("MyRole", "StorageAccess", "123456789012", "us-west-2");
180+
```
181+
182+
---
183+
184+
**Important:** Parameter semantics (identityName, policyName, roleName, tenantId) differ by provider. See Provider-Specific Notes above.
185+
186+
---
187+
188+
## Error Handling
189+
190+
### Exception Handling
191+
192+
All IAM operations may throw `SubstrateSdkException`:
193+
194+
```java
195+
try {
196+
String identityId = iamClient.createIdentity("MyRole", "Description", "123456789012", "us-west-2",
197+
Optional.empty(), Optional.empty());
198+
} catch (SubstrateSdkException e) {
199+
// Handle access denied, validation errors, etc.
200+
e.printStackTrace();
201+
}
202+
```

‎guides/index.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,12 @@ Use publish/subscribe systems to send and receive messages.
4242

4343
- [Pubsub](pubsub-guide.html)
4444

45+
## 📬 IAM
46+
47+
Learn how to manage identities and policies in a cloud-neutral way.
48+
49+
- [IAM](iam-guide.html)
50+
4551
---
4652

4753
## 🧪 Testing
@@ -52,4 +58,4 @@ Learn how to write and run conformance tests for multi-cloud applications.
5258

5359
---
5460

55-
Explore these guides to master the MultiCloudJ SDK and build robust multi-cloud Java applications with ease.
61+
Explore these guides to master the MultiCloudJ SDK and build robust multi-cloud Java applications with ease.

0 commit comments

Comments
 (0)