0
# Utility Operations
1

2
Utility operations for debugging authorization failures, retrieving caller identity, and determining account ownership of access keys. These operations provide essential diagnostic and identity information for AWS STS workflows.
3

4
## Capabilities
5

6
### Caller Identity Retrieval
7

8
Returns details about the IAM user or role whose credentials are used to call the operation.
9

10
```java { .api }
11
/**
12
 * Returns details about the IAM user or role whose credentials are used to call the operation
13
 * @param getCallerIdentityRequest Request object (no parameters required)
14
 * @return Result containing user ID, account ID, and ARN of the calling entity
15
 */
16
GetCallerIdentityResult getCallerIdentity(GetCallerIdentityRequest getCallerIdentityRequest);
17
```
18

19
**Request and Result Types:**
20

21
```java { .api }
22
public class GetCallerIdentityRequest extends AmazonWebServiceRequest {
23
    public GetCallerIdentityRequest();
24
    // No parameters required
25
}
26

27
public class GetCallerIdentityResult {
28
    public String getUserId();
29
    public void setUserId(String userId);
30
    
31
    public String getAccount();
32
    public void setAccount(String account);
33
    
34
    public String getArn();
35
    public void setArn(String arn);
36
}
37
```
38

39
**Usage Examples:**
40

41
```java
42
import com.amazonaws.services.securitytoken.AWSSecurityTokenService;
43
import com.amazonaws.services.securitytoken.model.*;
44

45
// Basic caller identity request
46
GetCallerIdentityRequest request = new GetCallerIdentityRequest();
47
GetCallerIdentityResult result = stsClient.getCallerIdentity(request);
48

49
System.out.println("User ID: " + result.getUserId());
50
System.out.println("Account: " + result.getAccount());
51
System.out.println("ARN: " + result.getArn());
52

53
// Example output for IAM user:
54
// User ID: AIDACKCEVSQ6C2EXAMPLE
55
// Account: 123456789012
56
// ARN: arn:aws:iam::123456789012:user/DevUser
57

58
// Example output for assumed role:
59
// User ID: AROAEXAMPLE:RoleSessionName
60
// Account: 123456789012  
61
// ARN: arn:aws:sts::123456789012:assumed-role/MyRole/RoleSessionName
62

63
// Application identity verification
64
public class IdentityVerificationService {
65
    private final AWSSecurityTokenService stsClient;
66
    
67
    public IdentityVerificationService(AWSSecurityTokenService stsClient) {
68
        this.stsClient = stsClient;
69
    }
70
    
71
    /**
72
     * Verify current AWS credentials and return identity information
73
     */
74
    public IdentityInfo verifyIdentity() {
75
        try {
76
            GetCallerIdentityResult result = stsClient.getCallerIdentity(
77
                new GetCallerIdentityRequest()
78
            );
79
            
80
            return new IdentityInfo(
81
                result.getUserId(),
82
                result.getAccount(),
83
                result.getArn(),
84
                determineIdentityType(result.getArn())
85
            );
86
        } catch (Exception e) {
87
            throw new RuntimeException("Failed to verify AWS identity", e);
88
        }
89
    }
90
    
91
    private String determineIdentityType(String arn) {
92
        if (arn.contains(":user/")) {
93
            return "IAM_USER";
94
        } else if (arn.contains(":assumed-role/")) {
95
            return "ASSUMED_ROLE";
96
        } else if (arn.contains(":federated-user/")) {
97
            return "FEDERATED_USER";
98
        } else if (arn.contains(":root")) {
99
            return "ROOT_USER";
100
        } else {
101
            return "UNKNOWN";
102
        }
103
    }
104
    
105
    public static class IdentityInfo {
106
        private final String userId;
107
        private final String account;
108
        private final String arn;
109
        private final String type;
110
        
111
        public IdentityInfo(String userId, String account, String arn, String type) {
112
            this.userId = userId;
113
            this.account = account;
114
            this.arn = arn;
115
            this.type = type;
116
        }
117
        
118
        // Getters omitted for brevity
119
    }
120
}
121
```
122

123
### Access Key Information Retrieval
124

125
Returns the account identifier for a specified access key ID.
126

127
```java { .api }
128
/**
129
 * Returns the account identifier for the specified access key ID
130
 * @param getAccessKeyInfoRequest Request containing the access key ID to query
131
 * @return Result containing the account identifier that owns the access key
132
 */
133
GetAccessKeyInfoResult getAccessKeyInfo(GetAccessKeyInfoRequest getAccessKeyInfoRequest);
134
```
135

136
**Request and Result Types:**
137

138
```java { .api }
139
public class GetAccessKeyInfoRequest extends AmazonWebServiceRequest {
140
    public GetAccessKeyInfoRequest();
141
    
142
    // Required parameter
143
    public String getAccessKeyId();
144
    public void setAccessKeyId(String accessKeyId);
145
    public GetAccessKeyInfoRequest withAccessKeyId(String accessKeyId);
146
}
147

148
public class GetAccessKeyInfoResult {
149
    public String getAccount();
150
    public void setAccount(String account);
151
}
152
```
153

154
**Usage Examples:**
155

156
```java
157
// Check account ownership of an access key
158
String accessKeyId = "AKIAIOSFODNN7EXAMPLE";
159

160
GetAccessKeyInfoRequest request = new GetAccessKeyInfoRequest()
161
    .withAccessKeyId(accessKeyId);
162

163
GetAccessKeyInfoResult result = stsClient.getAccessKeyInfo(request);
164
System.out.println("Access key belongs to account: " + result.getAccount());
165

166
// Access key validation service
167
public class AccessKeyValidationService {
168
    private final AWSSecurityTokenService stsClient;
169
    
170
    public AccessKeyValidationService(AWSSecurityTokenService stsClient) {
171
        this.stsClient = stsClient;
172
    }
173
    
174
    /**
175
     * Validate if an access key belongs to a specific account
176
     */
177
    public boolean validateAccessKeyOwnership(String accessKeyId, String expectedAccount) {
178
        try {
179
            GetAccessKeyInfoRequest request = new GetAccessKeyInfoRequest()
180
                .withAccessKeyId(accessKeyId);
181
            
182
            GetAccessKeyInfoResult result = stsClient.getAccessKeyInfo(request);
183
            return expectedAccount.equals(result.getAccount());
184
            
185
        } catch (Exception e) {
186
            System.err.println("Failed to validate access key: " + e.getMessage());
187
            return false;
188
        }
189
    }
190
    
191
    /**
192
     * Determine access key type based on prefix
193
     */
194
    public String getAccessKeyType(String accessKeyId) {
195
        if (accessKeyId.startsWith("AKIA")) {
196
            return "LONG_TERM"; // IAM user or root user
197
        } else if (accessKeyId.startsWith("ASIA")) {
198
            return "TEMPORARY"; // STS temporary credentials
199
        } else {
200
            return "UNKNOWN";
201
        }
202
    }
203
    
204
    /**
205
     * Comprehensive access key analysis
206
     */
207
    public AccessKeyAnalysis analyzeAccessKey(String accessKeyId) {
208
        try {
209
            GetAccessKeyInfoResult result = stsClient.getAccessKeyInfo(
210
                new GetAccessKeyInfoRequest().withAccessKeyId(accessKeyId)
211
            );
212
            
213
            return new AccessKeyAnalysis(
214
                accessKeyId,
215
                result.getAccount(),
216
                getAccessKeyType(accessKeyId),
217
                true // valid
218
            );
219
            
220
        } catch (Exception e) {
221
            return new AccessKeyAnalysis(
222
                accessKeyId,
223
                null,
224
                getAccessKeyType(accessKeyId),
225
                false // invalid or inaccessible
226
            );
227
        }
228
    }
229
    
230
    public static class AccessKeyAnalysis {
231
        private final String accessKeyId;
232
        private final String account;
233
        private final String type;
234
        private final boolean valid;
235
        
236
        public AccessKeyAnalysis(String accessKeyId, String account, String type, boolean valid) {
237
            this.accessKeyId = accessKeyId;
238
            this.account = account;
239
            this.type = type;
240
            this.valid = valid;
241
        }
242
        
243
        // Getters omitted for brevity
244
    }
245
}
246
```
247

248
### Authorization Message Decoding
249

250
Decodes additional information about authorization status from encoded messages returned by AWS operations.
251

252
```java { .api }
253
/**
254
 * Decodes additional information about the authorization status of a request
255
 * @param decodeAuthorizationMessageRequest Request containing the encoded message to decode
256
 * @return Result containing the decoded authorization status message
257
 * @throws InvalidAuthorizationMessageException If the message is invalid or contains invalid characters
258
 */
259
DecodeAuthorizationMessageResult decodeAuthorizationMessage(DecodeAuthorizationMessageRequest decodeAuthorizationMessageRequest);
260
```
261

262
**Request and Result Types:**
263

264
```java { .api }
265
public class DecodeAuthorizationMessageRequest extends AmazonWebServiceRequest {
266
    public DecodeAuthorizationMessageRequest();
267
    
268
    // Required parameter
269
    public String getEncodedMessage();
270
    public void setEncodedMessage(String encodedMessage);
271
    public DecodeAuthorizationMessageRequest withEncodedMessage(String encodedMessage);
272
}
273

274
public class DecodeAuthorizationMessageResult {
275
    public String getDecodedMessage();
276
    public void setDecodedMessage(String decodedMessage);
277
}
278
```
279

280
**Usage Examples:**
281

282
```java
283
// Decode authorization failure message
284
String encodedMessage = "eyJDb250ZXh0IjogeyJBV1NVc2VySWQiOiAiQUlEQUlPU0ZPRE5ON0VYQU1QTEUi...";
285

286
DecodeAuthorizationMessageRequest request = new DecodeAuthorizationMessageRequest()
287
    .withEncodedMessage(encodedMessage);
288

289
try {
290
    DecodeAuthorizationMessageResult result = stsClient.decodeAuthorizationMessage(request);
291
    String decodedMessage = result.getDecodedMessage();
292
    
293
    System.out.println("Decoded authorization message:");
294
    System.out.println(decodedMessage);
295
    
296
    // Parse the JSON message for structured information
297
    // The decoded message contains details like:
298
    // - Whether request was denied due to explicit deny or absence of allow
299
    // - Principal who made the request
300
    // - Requested action and resource
301
    // - Condition key values in the request context
302
    
303
} catch (InvalidAuthorizationMessageException e) {
304
    System.err.println("Invalid authorization message: " + e.getMessage());
305
}
306

307
// Authorization debugging service
308
public class AuthorizationDebugService {
309
    private final AWSSecurityTokenService stsClient;
310
    
311
    public AuthorizationDebugService(AWSSecurityTokenService stsClient) {
312
        this.stsClient = stsClient;
313
    }
314
    
315
    /**
316
     * Decode and analyze authorization failure messages
317
     */
318
    public AuthorizationAnalysis analyzeAuthorizationFailure(String encodedMessage) {
319
        try {
320
            DecodeAuthorizationMessageRequest request = new DecodeAuthorizationMessageRequest()
321
                .withEncodedMessage(encodedMessage);
322
            
323
            DecodeAuthorizationMessageResult result = stsClient.decodeAuthorizationMessage(request);
324
            String decodedMessage = result.getDecodedMessage();
325
            
326
            // Parse JSON message (implementation would use JSON parser)
327
            return parseAuthorizationMessage(decodedMessage);
328
            
329
        } catch (InvalidAuthorizationMessageException e) {
330
            throw new RuntimeException("Cannot decode authorization message", e);
331
        }
332
    }
333
    
334
    private AuthorizationAnalysis parseAuthorizationMessage(String decodedMessage) {
335
        // Implementation would parse JSON and extract:
336
        // - deny/allow status
337
        // - principal information
338
        // - requested action
339
        // - resource ARN
340
        // - condition context
341
        
342
        return new AuthorizationAnalysis(
343
            "EXPLICIT_DENY", // or "IMPLICIT_DENY"
344
            "arn:aws:iam::123456789012:user/ExampleUser",
345
            "s3:GetObject",
346
            "arn:aws:s3:::example-bucket/key",
347
            decodedMessage
348
        );
349
    }
350
    
351
    public static class AuthorizationAnalysis {
352
        private final String denyType;
353
        private final String principal;
354
        private final String action;
355
        private final String resource;
356
        private final String fullMessage;
357
        
358
        public AuthorizationAnalysis(String denyType, String principal, String action, 
359
                                   String resource, String fullMessage) {
360
            this.denyType = denyType;
361
            this.principal = principal;
362
            this.action = action;
363
            this.resource = resource;
364
            this.fullMessage = fullMessage;
365
        }
366
        
367
        // Getters omitted for brevity
368
    }
369
}
370
```
371

372
## Utility Integration Patterns
373

374
### Complete Identity and Authorization Service
375

376
```java
377
/**
378
 * Comprehensive service combining all utility operations
379
 */
380
public class AWSIdentityAndAuthService {
381
    private final AWSSecurityTokenService stsClient;
382
    
383
    public AWSIdentityAndAuthService(AWSSecurityTokenService stsClient) {
384
        this.stsClient = stsClient;
385
    }
386
    
387
    /**
388
     * Get complete context about current AWS session
389
     */
390
    public SessionContext getCurrentSessionContext() {
391
        GetCallerIdentityResult identity = stsClient.getCallerIdentity(
392
            new GetCallerIdentityRequest()
393
        );
394
        
395
        return new SessionContext(
396
            identity.getUserId(),
397
            identity.getAccount(),
398
            identity.getArn(),
399
            System.currentTimeMillis()
400
        );
401
    }
402
    
403
    /**
404
     * Validate cross-account access key
405
     */
406
    public boolean validateCrossAccountKey(String accessKeyId, String expectedAccount) {
407
        try {
408
            GetAccessKeyInfoResult result = stsClient.getAccessKeyInfo(
409
                new GetAccessKeyInfoRequest().withAccessKeyId(accessKeyId)
410
            );
411
            
412
            return expectedAccount.equals(result.getAccount());
413
        } catch (Exception e) {
414
            return false;
415
        }
416
    }
417
    
418
    /**
419
     * Debug authorization failure with detailed analysis
420
     */
421
    public void debugAuthorizationFailure(String encodedMessage) {
422
        try {
423
            DecodeAuthorizationMessageResult result = stsClient.decodeAuthorizationMessage(
424
                new DecodeAuthorizationMessageRequest().withEncodedMessage(encodedMessage)
425
            );
426
            
427
            System.out.println("Authorization Failure Analysis:");
428
            System.out.println("====================================");
429
            System.out.println(result.getDecodedMessage());
430
            
431
            // Additional structured analysis would go here
432
            
433
        } catch (Exception e) {
434
            System.err.println("Cannot decode authorization message: " + e.getMessage());
435
        }
436
    }
437
    
438
    public static class SessionContext {
439
        private final String userId;
440
        private final String account;
441
        private final String arn;
442
        private final long timestamp;
443
        
444
        public SessionContext(String userId, String account, String arn, long timestamp) {
445
            this.userId = userId;
446
            this.account = account;
447
            this.arn = arn;
448
            this.timestamp = timestamp;
449
        }
450
        
451
        // Getters omitted for brevity
452
    }
453
}
454
```
455

456
### Error Handling Best Practices
457

458
```java
459
/**
460
 * Best practices for handling utility operation errors
461
 */
462
public class UtilityErrorHandling {
463
    
464
    public void demonstrateErrorHandling(AWSSecurityTokenService stsClient) {
465
        
466
        // GetCallerIdentity - generally doesn't fail if credentials are valid
467
        try {
468
            GetCallerIdentityResult identity = stsClient.getCallerIdentity(
469
                new GetCallerIdentityRequest()
470
            );
471
            // Process successful result
472
        } catch (AWSSecurityTokenServiceException e) {
473
            // Handle invalid credentials or service errors
474
            System.err.println("Identity verification failed: " + e.getMessage());
475
        }
476
        
477
        // GetAccessKeyInfo - can fail if key doesn't exist or no permission
478
        try {
479
            GetAccessKeyInfoResult keyInfo = stsClient.getAccessKeyInfo(
480
                new GetAccessKeyInfoRequest().withAccessKeyId("AKIAEXAMPLE")
481
            );
482
            // Process successful result
483
        } catch (AWSSecurityTokenServiceException e) {
484
            // Handle invalid access key or permission issues
485
            System.err.println("Access key lookup failed: " + e.getMessage());
486
        }
487
        
488
        // DecodeAuthorizationMessage - can fail with invalid message format
489
        try {
490
            DecodeAuthorizationMessageResult decoded = stsClient.decodeAuthorizationMessage(
491
                new DecodeAuthorizationMessageRequest().withEncodedMessage("invalid-message")
492
            );
493
            // Process successful result
494
        } catch (InvalidAuthorizationMessageException e) {
495
            // Handle malformed encoded message
496
            System.err.println("Cannot decode message: " + e.getMessage());
497
        } catch (AWSSecurityTokenServiceException e) {
498
            // Handle other service errors
499
            System.err.println("Service error: " + e.getMessage());
500
        }
501
    }
502
}