0
# Federation Operations
1

2
Federation functionality for obtaining temporary credentials through external identity providers and custom federation brokers. This enables proxy applications to distribute temporary credentials without embedding long-term AWS credentials.
3

4
## Capabilities
5

6
### Federation Token Generation
7

8
Returns temporary security credentials for federated users through a custom identity broker.
9

10
```java { .api }
11
/**
12
 * Returns temporary security credentials for federated users
13
 * @param getFederationTokenRequest Request containing federated user name and policies
14
 * @return Result containing temporary credentials and federated user information
15
 * @throws MalformedPolicyDocumentException If session policy is malformed
16
 * @throws PackedPolicyTooLargeException If session policies exceed size limits
17
 * @throws RegionDisabledException If STS not activated in requested region
18
 */
19
GetFederationTokenResult getFederationToken(GetFederationTokenRequest getFederationTokenRequest);
20
```
21

22
**Request and Result Types:**
23

24
```java { .api }
25
public class GetFederationTokenRequest extends AmazonWebServiceRequest {
26
    public GetFederationTokenRequest();
27
    
28
    // Required parameters
29
    public String getName();
30
    public void setName(String name);
31
    public GetFederationTokenRequest withName(String name);
32
    
33
    // Optional parameters
34
    public String getPolicy();
35
    public void setPolicy(String policy);
36
    public GetFederationTokenRequest withPolicy(String policy);
37
    
38
    public List<PolicyDescriptorType> getPolicyArns();
39
    public void setPolicyArns(List<PolicyDescriptorType> policyArns);
40
    public GetFederationTokenRequest withPolicyArns(PolicyDescriptorType... policyArns);
41
    
42
    public Integer getDurationSeconds();
43
    public void setDurationSeconds(Integer durationSeconds);
44
    public GetFederationTokenRequest withDurationSeconds(Integer durationSeconds);
45
    
46
    public List<Tag> getTags();
47
    public void setTags(List<Tag> tags);
48
    public GetFederationTokenRequest withTags(Tag... tags);
49
}
50

51
public class GetFederationTokenResult {
52
    public Credentials getCredentials();
53
    public void setCredentials(Credentials credentials);
54
    
55
    public FederatedUser getFederatedUser();
56
    public void setFederatedUser(FederatedUser federatedUser);
57
    
58
    public Integer getPackedPolicySize();
59
    public void setPackedPolicySize(Integer packedPolicySize);
60
}
61
```
62

63
**Usage Examples:**
64

65
```java
66
import com.amazonaws.services.securitytoken.AWSSecurityTokenService;
67
import com.amazonaws.services.securitytoken.model.*;
68

69
// Basic federation token request
70
GetFederationTokenRequest request = new GetFederationTokenRequest()
71
    .withName("ProxyUser")
72
    .withDurationSeconds(3600);
73

74
GetFederationTokenResult result = stsClient.getFederationToken(request);
75
Credentials federatedCredentials = result.getCredentials();
76
FederatedUser federatedUser = result.getFederatedUser();
77

78
System.out.println("Federated User ID: " + federatedUser.getFederatedUserId());
79
System.out.println("Federated User ARN: " + federatedUser.getArn());
80

81
// Federation token with inline session policy
82
String sessionPolicy = "{"
83
    + "\"Version\": \"2012-10-17\","
84
    + "\"Statement\": [{"
85
    + "\"Effect\": \"Allow\","
86
    + "\"Action\": [\"s3:GetObject\", \"s3:ListBucket\"],"
87
    + "\"Resource\": ["
88
    + "\"arn:aws:s3:::my-app-bucket\","
89
    + "\"arn:aws:s3:::my-app-bucket/*\""
90
    + "]"
91
    + "}]"
92
    + "}";
93

94
GetFederationTokenRequest policyRequest = new GetFederationTokenRequest()
95
    .withName("S3User")
96
    .withPolicy(sessionPolicy)
97
    .withDurationSeconds(7200);
98

99
GetFederationTokenResult policyResult = stsClient.getFederationToken(policyRequest);
100

101
// Federation token with managed policy ARNs
102
List<PolicyDescriptorType> managedPolicies = Arrays.asList(
103
    new PolicyDescriptorType().withArn("arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess"),
104
    new PolicyDescriptorType().withArn("arn:aws:iam::123456789012:policy/MyCustomPolicy")
105
);
106

107
GetFederationTokenRequest managedPolicyRequest = new GetFederationTokenRequest()
108
    .withName("ManagedPolicyUser")
109
    .withPolicyArns(managedPolicies)
110
    .withDurationSeconds(1800);
111

112
GetFederationTokenResult managedPolicyResult = stsClient.getFederationToken(managedPolicyRequest);
113

114
// Federation token with session tags
115
List<Tag> sessionTags = Arrays.asList(
116
    new Tag().withKey("Department").withValue("Engineering"),
117
    new Tag().withKey("Project").withValue("WebApp"),
118
    new Tag().withKey("Environment").withValue("Production")
119
);
120

121
GetFederationTokenRequest taggedRequest = new GetFederationTokenRequest()
122
    .withName("TaggedUser")
123
    .withTags(sessionTags)
124
    .withDurationSeconds(3600);
125

126
GetFederationTokenResult taggedResult = stsClient.getFederationToken(taggedRequest);
127
```
128

129
## Federation Use Cases and Best Practices
130

131
### Proxy Application Pattern
132

133
Federation tokens are designed for proxy applications that need to distribute temporary credentials:
134

135
```java
136
/**
137
 * Example proxy service that creates federation tokens for different users
138
 */
139
public class FederationProxyService {
140
    private final AWSSecurityTokenService stsClient;
141
    
142
    public FederationProxyService(AWSSecurityTokenService stsClient) {
143
        this.stsClient = stsClient;
144
    }
145
    
146
    /**
147
     * Create federation token for a specific user with limited S3 access
148
     */
149
    public Credentials createS3UserCredentials(String username, String bucketName) {
150
        String userSpecificPolicy = createS3BucketPolicy(bucketName);
151
        
152
        GetFederationTokenRequest request = new GetFederationTokenRequest()
153
            .withName(username)
154
            .withPolicy(userSpecificPolicy)
155
            .withDurationSeconds(3600)
156
            .withTags(
157
                new Tag().withKey("Username").withValue(username),
158
                new Tag().withKey("AccessType").withValue("S3Limited")
159
            );
160
        
161
        GetFederationTokenResult result = stsClient.getFederationToken(request);
162
        return result.getCredentials();
163
    }
164
    
165
    private String createS3BucketPolicy(String bucketName) {
166
        return "{"
167
            + "\"Version\": \"2012-10-17\","
168
            + "\"Statement\": [{"
169
            + "\"Effect\": \"Allow\","
170
            + "\"Action\": [\"s3:GetObject\", \"s3:PutObject\", \"s3:ListBucket\"],"
171
            + "\"Resource\": ["
172
            + "\"arn:aws:s3:::" + bucketName + "\","
173
            + "\"arn:aws:s3:::" + bucketName + "/*\""
174
            + "]"
175
            + "}]"
176
            + "}";
177
    }
178
}
179
```
180

181
### Session Duration Limits
182

183
Federation tokens have specific duration limits:
184

185
- **IAM User credentials**: 900 seconds (15 minutes) to 129,600 seconds (36 hours), default 43,200 seconds (12 hours)
186
- **Root user credentials**: Maximum 3,600 seconds (1 hour)
187

188
```java
189
// Configure appropriate duration based on use case
190
GetFederationTokenRequest shortTermRequest = new GetFederationTokenRequest()
191
    .withName("ShortTermUser")
192
    .withDurationSeconds(900); // 15 minutes minimum
193

194
GetFederationTokenRequest longTermRequest = new GetFederationTokenRequest()
195
    .withName("LongTermUser")
196
    .withDurationSeconds(129600); // 36 hours maximum for IAM users
197
```
198

199
### Permission Limitations
200

201
Federation tokens have specific permission limitations:
202

203
1. **Cannot call IAM operations** unless MFA authentication information is included
204
2. **Cannot call STS operations** except `GetCallerIdentity`
205
3. **Session policies limit permissions** - cannot grant more than the calling user's permissions
206
4. **Resource-based policies** can grant additional permissions if they specifically reference the federated user session
207

208
```java
209
// Example of checking federation token limitations
210
public void demonstrateFederationLimitations() {
211
    GetFederationTokenRequest request = new GetFederationTokenRequest()
212
        .withName("LimitedUser");
213
    
214
    GetFederationTokenResult result = stsClient.getFederationToken(request);
215
    
216
    // These operations will work with federation tokens:
217
    // - Most AWS service operations (S3, EC2, etc.)
218
    // - GetCallerIdentity
219
    
220
    // These operations will NOT work with federation tokens:
221
    // - IAM operations (CreateUser, AttachUserPolicy, etc.)
222
    // - Other STS operations (AssumeRole, GetSessionToken, etc.)
223
}
224
```
225

226
### Corporate Network Integration
227

228
Federation tokens are ideal for corporate proxy applications:
229

230
```java
231
/**
232
 * Example corporate identity broker
233
 */
234
public class CorporateIdentityBroker {
235
    private final AWSSecurityTokenService stsClient;
236
    
237
    public CorporateIdentityBroker() {
238
        // This proxy service runs with long-term IAM user credentials
239
        this.stsClient = AWSSecurityTokenServiceClientBuilder.standard()
240
            .withCredentials(new DefaultAWSCredentialsProviderChain())
241
            .build();
242
    }
243
    
244
    /**
245
     * Authenticate corporate user and return AWS credentials
246
     */
247
    public Credentials authenticateUser(String corporateUsername, String corporatePassword) {
248
        // 1. Validate corporate credentials (LDAP, Active Directory, etc.)
249
        if (!validateCorporateCredentials(corporateUsername, corporatePassword)) {
250
            throw new AuthenticationException("Invalid corporate credentials");
251
        }
252
        
253
        // 2. Determine user's permissions based on corporate role
254
        String sessionPolicy = determineUserPermissions(corporateUsername);
255
        
256
        // 3. Create federation token
257
        GetFederationTokenRequest request = new GetFederationTokenRequest()
258
            .withName(corporateUsername)
259
            .withPolicy(sessionPolicy)
260
            .withDurationSeconds(28800) // 8 hours
261
            .withTags(
262
                new Tag().withKey("CorporateUser").withValue(corporateUsername),
263
                new Tag().withKey("AuthMethod").withValue("Corporate")
264
            );
265
        
266
        GetFederationTokenResult result = stsClient.getFederationToken(request);
267
        return result.getCredentials();
268
    }
269
    
270
    private boolean validateCorporateCredentials(String username, String password) {
271
        // Implement corporate authentication logic
272
        return true;
273
    }
274
    
275
    private String determineUserPermissions(String username) {
276
        // Implement role-based permission mapping
277
        return "{ /* user-specific policy */ }";
278
    }
279
}
280
```